[PATCH v3 0/7] Convert the remaining text files to ReST

[PATCH v3 0/7] Convert the remaining text files to ReST

[Mauro Carvalho Chehab]

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%)

-- 
2.26.2

[PATCH v3 3/7] docs: move nommu-mmap.txt to admin-guide and rename to ReST

[Mauro Carvalho Chehab]

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>
-- 
2.26.2

Re: [PATCH v3 0/7] Convert the remaining text files to ReST

[Jonathan Corbet]

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

Re: [PATCH v3 0/7] Convert the remaining text files to ReST

[Mauro Carvalho Chehab]

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
 =============