The main goal of this series is to finish the ReST conversion. After this series, we have just those files still in plain old format:
- Documentation/RCU/RTFP.txt - Documentation/atomic_bitops.txt - Documentation/memory-barriers.txt - Documentation/atomic_t.txt - Documentation/filesystems/dax.txt - Documentation/filesystems/path-lookup.txt - Documentation/virt/kvm/devices/README
PS.: I'm using a script to remove false-positives and ignore non-converted translated files.
---
- v3: removed SPDX patches, because upstream discussion about GFDL is not finished yet. So, for now, use the old way to specify dual-licensed GPL and GFDL files.
I have already a tree ready for submission once upstream pushes this feat on SPDX specs.
Mauro Carvalho Chehab (7): docs: dt: convert booting-without-of.txt to ReST format docs: trace: ring-buffer-design.txt: convert to ReST format docs: move nommu-mmap.txt to admin-guide and rename to ReST docs: move mailbox.txt to driver-api and rename it docs: move other kAPI documents to core-api docs: Add remaining Documentation/*.txt at staging/index.rst docs: staging: use small font for literal includes
Documentation/admin-guide/mm/index.rst | 1 + .../mm/nommu-mmap.rst} | 0 Documentation/admin-guide/sysctl/vm.rst | 2 +- Documentation/arm/booting.rst | 2 +- .../bus-virt-phys-mapping.rst} | 0 Documentation/core-api/index.rst | 3 + .../this_cpu_ops.rst} | 0 .../unaligned-memory-access.rst | 0 ...-without-of.txt => booting-without-of.rst} | 298 ++++--- Documentation/devicetree/index.rst | 1 + Documentation/driver-api/index.rst | 1 + .../{mailbox.txt => driver-api/mailbox.rst} | 0 Documentation/gpu/drm-mm.rst | 2 +- Documentation/staging/index.rst | 24 + Documentation/trace/index.rst | 1 + ...ffer-design.txt => ring-buffer-design.rst} | 802 ++++++++++-------- Documentation/translations/zh_CN/arm/Booting | 2 +- arch/Kconfig | 2 +- init/Kconfig | 2 +- mm/Kconfig | 2 +- mm/nommu.c | 2 +- 21 files changed, 631 insertions(+), 516 deletions(-) rename Documentation/{nommu-mmap.txt => admin-guide/mm/nommu-mmap.rst} (100%) rename Documentation/{bus-virt-phys-mapping.txt => core-api/bus-virt-phys-mapping.rst} (100%) rename Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst} (100%) rename Documentation/{process => core-api}/unaligned-memory-access.rst (100%) rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%) rename Documentation/{mailbox.txt => driver-api/mailbox.rst} (100%) rename Documentation/trace/{ring-buffer-design.txt => ring-buffer-design.rst} (55%)
The nommu-mmap.txt file provides description of user visible behaviuour. So, move it to the admin-guide.
As it is already at the ReST, also rename it.
Suggested-by: Mike Rapoport rppt@linux.ibm.com Suggested-by: Jonathan Corbet corbet@lwn.net Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org --- Documentation/admin-guide/mm/index.rst | 1 + Documentation/{nommu-mmap.txt => admin-guide/mm/nommu-mmap.rst} | 0 Documentation/admin-guide/sysctl/vm.rst | 2 +- Documentation/gpu/drm-mm.rst | 2 +- init/Kconfig | 2 +- mm/Kconfig | 2 +- mm/nommu.c | 2 +- 7 files changed, 6 insertions(+), 5 deletions(-) rename Documentation/{nommu-mmap.txt => admin-guide/mm/nommu-mmap.rst} (100%)
diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index 11db46448354..774dad6d3d29 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -31,6 +31,7 @@ the Linux memory management. idle_page_tracking ksm memory-hotplug + nommu-map numa_memory_policy numaperf pagemap diff --git a/Documentation/nommu-mmap.txt b/Documentation/admin-guide/mm/nommu-mmap.rst similarity index 100% rename from Documentation/nommu-mmap.txt rename to Documentation/admin-guide/mm/nommu-mmap.rst diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index 4b7c496199ca..4b9d2e8e9142 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -598,7 +598,7 @@ trimming of allocations is initiated.
The default value is 1.
-See Documentation/nommu-mmap.txt for more information. +See Documentation/admin-guide/mm/nommu-mmap.rst for more information.
numa_zonelist_order diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 8d10e6b38918..9abee1589c1e 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -311,7 +311,7 @@ To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct a pointer on drm_gem_cma_get_unmapped_area().
More detailed information about get_unmapped_area can be found in -Documentation/nommu-mmap.txt +Documentation/admin-guide/mm/nommu-mmap.rst
Memory Coherency ---------------- diff --git a/init/Kconfig b/init/Kconfig index a46aa8f3174d..2dd5531dae98 100644 --- a/init/Kconfig +++ b/init/Kconfig @@ -1957,7 +1957,7 @@ config MMAP_ALLOW_UNINITIALIZED userspace. Since that isn't generally a problem on no-MMU systems, it is normally safe to say Y here.
- See Documentation/nommu-mmap.txt for more information. + See Documentation/mm/nommu-mmap.rst for more information.
config SYSTEM_DATA_VERIFICATION def_bool n diff --git a/mm/Kconfig b/mm/Kconfig index f2104cc0d35c..d41f3fa7e923 100644 --- a/mm/Kconfig +++ b/mm/Kconfig @@ -387,7 +387,7 @@ config NOMMU_INITIAL_TRIM_EXCESS This option specifies the initial value of this option. The default of 1 says that all excess pages should be trimmed.
- See Documentation/nommu-mmap.txt for more information. + See Documentation/mm/nommu-mmap.rst for more information.
config TRANSPARENT_HUGEPAGE bool "Transparent Hugepage Support" diff --git a/mm/nommu.c b/mm/nommu.c index f32a69095d50..314174817b04 100644 --- a/mm/nommu.c +++ b/mm/nommu.c @@ -5,7 +5,7 @@ * Replacement code for mm functions to support CPU's that don't * have any form of memory management unit (thus no virtual memory). * - * See Documentation/nommu-mmap.txt + * See Documentation/mm/nommu-mmap.rst * * Copyright (c) 2004-2008 David Howells dhowells@redhat.com * Copyright (c) 2000-2003 David McCullough davidm@snapgear.com
On Tue, 23 Jun 2020 15:31:33 +0200 Mauro Carvalho Chehab mchehab+huawei@kernel.org wrote:
The main goal of this series is to finish the ReST conversion. After this series, we have just those files still in plain old format:
- Documentation/RCU/RTFP.txt
- Documentation/atomic_bitops.txt
- Documentation/memory-barriers.txt
- Documentation/atomic_t.txt
- Documentation/filesystems/dax.txt
- Documentation/filesystems/path-lookup.txt
- Documentation/virt/kvm/devices/README
OK, I've applied this set - glad to see the last one!
Still *not* glad to see the LaTeX markup in the staging stuff; hopefully we can do something about that soon.
Thanks,
jon
Em Fri, 26 Jun 2020 11:34:59 -0600 Jonathan Corbet corbet@lwn.net escreveu:
On Tue, 23 Jun 2020 15:31:33 +0200 Mauro Carvalho Chehab mchehab+huawei@kernel.org wrote:
The main goal of this series is to finish the ReST conversion. After this series, we have just those files still in plain old format:
- Documentation/RCU/RTFP.txt
- Documentation/atomic_bitops.txt
- Documentation/memory-barriers.txt
- Documentation/atomic_t.txt
- Documentation/filesystems/dax.txt
- Documentation/filesystems/path-lookup.txt
- Documentation/virt/kvm/devices/README
OK, I've applied this set - glad to see the last one!
Yeah! we can now focus on keeping it updated and re-organizing things, for the docs to look more like a real book.
Still *not* glad to see the LaTeX markup in the staging stuff; hopefully we can do something about that soon.
Agreed.
The problem here is that, using the normal sized monospaced font, the maximum line width will be 67 columns[1]. The way Sphinx deals with mono-spaced texts is that it doesn't allow LaTeX to split lines. So, Sphinx sets LaTeX to truncate long lines, forcing it to honor the line breaks generated by Sphinx.
At least newer versions of Sphinx have an optimization the LaTeX output code: on some cases Sphinx detect long lines and adds an artificial line break, preceded by a markup to indicate that the text would be otherwise truncated at the LaTeX output. Yet, if it is a single long word, it will just let it go past the margins and be truncated.
For the files under staging, using this optimization will look really weird, as the text output would be (with the enclosed path, meant to show the soft and hard line size limits)[2]:
" 1 2 3 4 5 6 ␣ → 7 8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 →text here
On atomic types (atomic_t atomic64_t and atomic_long_t).
The atomic type provides an interface to the architecture's means␣ → of atomic RMW operations between CPUs (atomic operations on MMIO are not␣ → supported and can lead to fatal traps on some platforms)."
What the LaTeX raw macro does is to use a smaller font that will allow an 80-columns text to fit without those artificial breaks. I had to manually check what font size would work, and this might require future changes, if Sphinx changes the default mono-spaced font or its default size.
For the documents on staging, the solution is really simple from technical standpoint: just convert them to ReST. This would allow Sphinx to use a proportional spaced font most of the time, which passes texts in paragraphs to LaTeX. This way, the line breaks will be at the right places.
I remember I tried doing it a few times, but there were strong resistance.
It could be possible to do some tricks at the conf.py to change some defaults, but anyone willing to do that will also need to test the PDF output with all supported Sphinx versions, as the LaTeX output macros is not an stable API: we had to add several version-dependent stuff there, and even remove some features (like /resizebox for tables with many columns), as maintaining it was spending too much time and efforts.
-
[1] If you want to check, try building with the enclosed patch.
[2] The output of the second line from the file shows some artifacts introduced:
- the word "some" disappeared, as it was truncated at the output; - the last "0" was half-truncated; - the symbol indicating that a conditional line would exist ("␣") was also truncated.
Thanks, Mauro
-
diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt index 0f1fdedf36bb..9488c35ec608 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -1,3 +1,5 @@ + 1 2 3 4 5 6 7 8 +12345678901234567890123456789012345678901234567890123456789012345678901234567890some text here
On atomic types (atomic_t atomic64_t and atomic_long_t).
diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst index 184e6aece0a7..0c3acf27e1ff 100644 --- a/Documentation/staging/index.rst +++ b/Documentation/staging/index.rst @@ -19,17 +19,9 @@ Unsorted Documentation Atomic Types ============
-.. raw:: latex - - \footnotesize - .. include:: ../atomic_t.txt :literal:
-.. raw:: latex - - \normalsize - Atomic bitops =============
dri-devel@lists.freedesktop.org
-
Jonathan Corbet -
Mauro Carvalho Chehab