Skip to contentSkip to conversation

Convert the remaining text files to ReST

PATCH In review Mauro Carvalho Chehab 2 participants 10 messages Jun 23, 2020 – Jun 28, 2020

Subsystems (14)
lore
Share & tools
lore
#6 lore raw

PATCH v3 6/7 docs: Add remaining Documentation/*.txt at staging/index.rst

In reply to Mauro Carvalho Chehab

There are a few text files that aren't yet at the docs building system.

Add those to the staging/index.rst.

---
 Documentation/staging/index.rst | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)
Documentation/staging/index.rst +3 -6
index 8cc9d94b0a13..8e98517675ca 100644
@@ -19,17 +19,14 @@ Unsorted Documentation
 Atomic Types
 ============
 
-.. include:: ../atomic_t.txt
-   :literal:
+.. literalinclude:: ../atomic_t.txt
 
 Atomic bitops
 =============
 
-.. include:: ../atomic_bitops.txt
-   :literal:
+.. literalinclude:: ../atomic_bitops.txt
 
 Memory Barriers
 ===============
 
-.. include:: ../memory-barriers.txt
-   :literal:
+.. literalinclude:: ../memory-barriers.txt
Signature · 1 line
2.26.2
#3 lore raw

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

In reply to 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.

---
 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%)
Documentation/admin-guide/mm/index.rst +1 -0
index 11db46448354..774dad6d3d29 100644
@@ -31,6 +31,7 @@ the Linux memory management.
    idle_page_tracking
    ksm
    memory-hotplug
+   nommu-map
    numa_memory_policy
    numaperf
    pagemap
Documentation/admin-guide/mm/nommu-mmap.rst renamed from Documentation/nommu-mmap.txt +0 -0
similarity index 100%
rename from Documentation/nommu-mmap.txt
rename to Documentation/admin-guide/mm/nommu-mmap.rst
Documentation/admin-guide/sysctl/vm.rst +1 -1
index 4b7c496199ca..4b9d2e8e9142 100644
@@ -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
Documentation/gpu/drm-mm.rst +1 -1
index 8d10e6b38918..9abee1589c1e 100644
@@ -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
 ----------------
init/Kconfig +1 -1
index a46aa8f3174d..2dd5531dae98 100644
@@ -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
mm/Kconfig +1 -1
index f2104cc0d35c..d41f3fa7e923 100644
@@ -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"
mm/nommu.c +1 -1
index f32a69095d50..314174817b04 100644
@@ -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 <[email protected]>
  *  Copyright (c) 2000-2003 David McCullough <[email protected]>
Signature · 6 lines
2.26.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#7 lore raw

PATCH v3 7/7 docs: staging: use small font for literal includes

In reply to Mauro Carvalho Chehab

The normal font is too big to display 80 columns, causing extra breaks to be added at weird places.

change to the footnotesize, as this would fit a little bit better.

---
 Documentation/staging/index.rst | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)
Documentation/staging/index.rst +30 -3
index 8e98517675ca..184e6aece0a7 100644
@@ -19,14 +19,41 @@ Unsorted Documentation
 Atomic Types
 ============
 
-.. literalinclude:: ../atomic_t.txt
+.. raw:: latex
+
+    \footnotesize
+
+.. include:: ../atomic_t.txt
+   :literal:
+
+.. raw:: latex
+
+    \normalsize
 
 Atomic bitops
 =============
 
-.. literalinclude:: ../atomic_bitops.txt
+.. raw:: latex
+
+    \footnotesize
+
+.. include:: ../atomic_bitops.txt
+   :literal:
+
+.. raw:: latex
+
+    \normalsize
 
 Memory Barriers
 ===============
 
-.. literalinclude:: ../memory-barriers.txt
+.. raw:: latex
+
+    \footnotesize
+
+.. include:: ../memory-barriers.txt
+   :literal:
+
+.. raw:: latex
+
+    \normalsize
Signature · 1 line
2.26.2
#2 lore raw

PATCH v3 2/7 docs: trace: ring-buffer-design.txt: convert to ReST format

In reply to Mauro Carvalho Chehab

- Just like some media documents, this file is dual licensed with GPL and GFDL. As right now the GFDL SPDX definition is bogus (as it doesn't tell anything about invariant parts), let's not use SPDX here. Let's use, instead, the same test as we have on media.
- Convert title to ReST format;
- use :field: markup;
- Proper mark literal blocks as such;
- Add it to trace/index.rst file.

---
 Documentation/trace/index.rst                 |   1 +
 ...ffer-design.txt => ring-buffer-design.rst} | 802 ++++++++++--------
 2 files changed, 428 insertions(+), 375 deletions(-)
 rename Documentation/trace/{ring-buffer-design.txt => ring-buffer-design.rst} (55%)
Documentation/trace/index.rst +1 -0
index fa9e1c730f6a..7d83156c9ac1 100644
@@ -22,6 +22,7 @@ Linux Tracing Technologies
    boottime-trace
    hwlat_detector
    intel_th
+   ring-buffer-design
    stm
    sys-t
    coresight/index
Documentation/trace/ring-buffer-design.rst renamed from Documentation/trace/ring-buffer-design.txt +427 -375

1,094 lines not on this page · raw message

Signature · 1 line
2.26.2
#0 lore raw

v3 cover Convert the remaining text files to ReST

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%)
Signature · 7 lines
2.26.2


_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#4 lore raw

PATCH v3 4/7 docs: move mailbox.txt to driver-api and rename it

This file is already at the ReST format. Move it to driver-api and rename it.

---
 Documentation/driver-api/index.rst                    | 1 +
 Documentation/{mailbox.txt => driver-api/mailbox.rst} | 0
 2 files changed, 1 insertion(+)
 rename Documentation/{mailbox.txt => driver-api/mailbox.rst} (100%)
Documentation/driver-api/index.rst +1 -0
index 6567187e7687..3eb0085d5e42 100644
@@ -48,6 +48,7 @@ available subsections can be seen below.
    scsi
    libata
    target
+   mailbox
    mtdnand
    miscellaneous
    mei/index
Documentation/driver-api/mailbox.rst renamed from Documentation/mailbox.txt +0 -0
similarity index 100%
rename from Documentation/mailbox.txt
rename to Documentation/driver-api/mailbox.rst
Signature · 1 line
2.26.2
#5 lore raw

PATCH v3 5/7 docs: move other kAPI documents to core-api

In reply to Mauro Carvalho Chehab

There are a number of random documents that seem to be describing some aspects of the core-api. Move them to such directory, adding them at the core-api/index.rst file.

---
 .../bus-virt-phys-mapping.rst}                                 | 0
 Documentation/core-api/index.rst                               | 3 +++
 Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst}  | 0
 .../{process => core-api}/unaligned-memory-access.rst          | 0
 arch/Kconfig                                                   | 2 +-
 5 files changed, 4 insertions(+), 1 deletion(-)
 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%)
Documentation/core-api/bus-virt-phys-mapping.rst renamed from Documentation/bus-virt-phys-mapping.txt +0 -0
similarity index 100%
rename from Documentation/bus-virt-phys-mapping.txt
rename to Documentation/core-api/bus-virt-phys-mapping.rst
Documentation/core-api/index.rst +3 -0
index 15ab86112627..69171b1799f2 100644
@@ -39,6 +39,8 @@ Library functionality that is used throughout the kernel.
    rbtree
    generic-radix-tree
    packing
+   bus-virt-phys-mapping
+   this_cpu_ops
    timekeeping
    errseq
 
@@ -82,6 +84,7 @@ more memory-management documentation in :doc:`/vm/index`.
    :maxdepth: 1
 
    memory-allocation
+   unaligned-memory-access
    dma-api
    dma-api-howto
    dma-attributes
Documentation/core-api/this_cpu_ops.rst renamed from Documentation/this_cpu_ops.txt +0 -0
similarity index 100%
rename from Documentation/this_cpu_ops.txt
rename to Documentation/core-api/this_cpu_ops.rst
Documentation/core-api/unaligned-memory-access.rst renamed from Documentation/process/unaligned-memory-access.rst +0 -0
similarity index 100%
rename from Documentation/process/unaligned-memory-access.rst
rename to Documentation/core-api/unaligned-memory-access.rst
arch/Kconfig +1 -1
index 8cc35dc556c7..2a439fb8069e 100644
@@ -147,7 +147,7 @@ config HAVE_EFFICIENT_UNALIGNED_ACCESS
 	  problems with received packets if doing so would not help
 	  much.
 
-	  See Documentation/unaligned-memory-access.txt for more
+	  See Documentation/core-api/unaligned-memory-access.rst for more
 	  information on the topic of unaligned memory accesses.
 
 config ARCH_USE_BUILTIN_BSWAP
Signature · 1 line
2.26.2
#1 lore raw

PATCH v3 1/7 docs: dt: convert booting-without-of.txt to ReST format

In reply to Mauro Carvalho Chehab

- Add a SPDX header;
- Adjust document title;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to devicetree/index.rst.

---
 Documentation/arm/booting.rst                 |   2 +-
 ...-without-of.txt => booting-without-of.rst} | 298 ++++++++++--------
 Documentation/devicetree/index.rst            |   1 +
 Documentation/translations/zh_CN/arm/Booting  |   2 +-
 4 files changed, 168 insertions(+), 135 deletions(-)
 rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%)
Documentation/arm/booting.rst +1 -1
index 4babb6c6ae1e..a2263451dc2c 100644
@@ -128,7 +128,7 @@ it.  The recommended placement is in the first 16KiB of RAM.
 
 The boot loader must load a device tree image (dtb) into system ram
 at a 64bit aligned address and initialize it with the boot data.  The
-dtb format is documented in Documentation/devicetree/booting-without-of.txt.
+dtb format is documented in Documentation/devicetree/booting-without-of.rst.
 The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
 physical address to determine if a dtb has been passed instead of a
 tagged list.
Documentation/devicetree/booting-without-of.rst renamed from Documentation/devicetree/booting-without-of.txt +165 -133

552 lines not on this page · raw message

Documentation/devicetree/index.rst +1 -0
index 54026763916d..d2a96e1af23e 100644
@@ -15,3 +15,4 @@ Open Firmware and Device Tree
    overlay-notes
 
    bindings/index
+   booting-without-of
Documentation/translations/zh_CN/arm/Booting +1 -1
index 562e9a2957e6..c3d26ce5f6de 100644
@@ -124,7 +124,7 @@ bootloader 必须传递一个系统内存的位置和最小值,以及根文件
 
 bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统
 RAM 中,并用启动数据初始化它。dtb 格式在文档
-Documentation/devicetree/booting-without-of.txt 中。内核将会在
+Documentation/devicetree/booting-without-of.rst 中。内核将会在
 dtb 物理地址处查找 dtb 魔数值(0xd00dfeed),以确定 dtb 是否已经代替
 标签列表被传递进来。
 
Signature · 1 line
2.26.2
maintainer
#8 lore raw
In reply to Mauro Carvalho Chehab
Quoted 10 lines · On Tue, 23 Jun 2020 15:31:33 +0200 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

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
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#9 lore raw

Em Fri, 26 Jun 2020 11:34:59 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 14 lines
Quoted 10 lines · On Tue, 23 Jun 2020 15:31:33 +0200 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

Quoted 1 line

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.

Quoted 2 lines

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

-

Documentation/atomic_t.txt +2 -0
index 0f1fdedf36bb..9488c35ec608 100644
@@ -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).
 
Documentation/staging/index.rst +0 -8
index 184e6aece0a7..0c3acf27e1ff 100644
@@ -19,17 +19,9 @@ Unsorted Documentation
 Atomic Types
 ============
 
-.. raw:: latex
-
-    \footnotesize
-
 .. include:: ../atomic_t.txt
    :literal:
 
-.. raw:: latex
-
-    \normalsize
-
 Atomic bitops
 =============
 

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel