| Message ID | cover.1592918949.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | Convert the remaining text files to ReST | expand |
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 =============
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%)