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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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