Convert the remaining text files to ReST
Subsystems (14)
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
PATCH v3 1/7 docs: dt: convert booting-without-of.txt to ReST format
- 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
@@ -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
@@ -15,3 +15,4 @@ Open Firmware and Device Tree overlay-notes bindings/index + booting-without-of
Documentation/translations/zh_CN/arm/Booting +1 -1
@@ -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
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
@@ -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
PATCH v3 3/7 docs: move nommu-mmap.txt to admin-guide and rename to ReST
In reply to Mauro Carvalho ChehabThe 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
@@ -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
Documentation/admin-guide/sysctl/vm.rst +1 -1
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
PATCH v3 4/7 docs: move mailbox.txt to driver-api and rename it
In reply to Mauro Carvalho ChehabThis 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
@@ -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
Signature · 1 line
2.26.2
PATCH v3 5/7 docs: move other kAPI documents to core-api
In reply to Mauro Carvalho ChehabThere 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
Documentation/core-api/index.rst +3 -0
@@ -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
Documentation/core-api/unaligned-memory-access.rst renamed from Documentation/process/unaligned-memory-access.rst +0 -0
arch/Kconfig +1 -1
@@ -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
PATCH v3 6/7 docs: Add remaining Documentation/*.txt at staging/index.rst
In reply to Mauro Carvalho ChehabThere 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
@@ -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
PATCH v3 7/7 docs: staging: use small font for literal includes
In reply to Mauro Carvalho ChehabThe 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
@@ -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
Jonathan Corbet
maintainerQuoted 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
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
@@ -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
@@ -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