Re: [PATCH] docs-rst: add inter-document cross references
From: Mauro Carvalho Chehab
Date: Fri Sep 23 2016 - 17:15:52 EST
Hi Jon,
Em Wed, 21 Sep 2016 15:44:05 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:
> ...and now I'm thinking that's maybe about enough in docs for 4.9...:)
I finished handling the plain text files that, IMHO, should be on
either user of development process books.
As you're feeling that there are enough material for 4.9, I'll
postpone their submission to early during 4.10-rc time.
Anyway, if you want to take a sneak pick, the patches are in this tree:
https://git.linuxtv.org//mchehab/experimental.git/log/?h=lkml-books
and the html books are at:
https://mchehab.fedorapeople.org/user/
https://mchehab.fedorapeople.org/development-process/
ePub at:
https://mchehab.fedorapeople.org/user/epub/
https://mchehab.fedorapeople.org/development-process/epub/
PDF and LaTex at:
https://mchehab.fedorapeople.org/user/latex/
https://mchehab.fedorapeople.org/development-process/latex/
Probably, there will be issues with PDF, as Sphinx usually require manual
work to fix issues with PDF output, and on several cases, raw LaTeX
commands inside the rst files. I also had to patch a LaTeX config locally
to avoid an out of memory error when building the user's book.
The last patch in this tree is the RFC patch that adds MAINTAINERS file
to the user's book.
In total, 42 files were converted to either one of the books,
of a total of 151 files at Documentation/, plus 2 files at /.
There, I opted to use symlinks instead of moving files. There is an
issue with that, though: it is harder to identify what files are
part of the Sphinx build, and what files aren't. Ok, we could
write some sort of script to identify the undocumented files, but
this is a way more complex that doing a
$ find . -maxdepth 1 -type f
(or doing a ls there and see the files inside it)
So, IMHO, we should be moving the files instead of symlinking them.
Thanks,
Mauro
--
The following changes since commit 17e9217d41e18293c82772b4da544f25e62c342e:
Merge branch 'doc/4.9' into docs-next (2016-09-21 15:55:06 -0600)
are available in the git repository at:
git://linuxtv.org/mchehab/experimental.git lkml-books
for you to fetch changes up to c8b07684c0278d7f9d0e30f575eb4be3a2da4c3b:
docs-rst: user: add MAINTAINERS (2016-09-23 17:39:01 -0300)
----------------------------------------------------------------
Mauro Carvalho Chehab (33):
Documentation/applying-patches.txt: fix a bad external link
REPORTING-BUGS: convert to ReST markup
README: convert it to ReST markup
Documentation/kernel-parameters.txt: convert to ReST markup
docs-rst: add documents to development-process
docs-rst: create an user's manual book
Documentation/adding-syscalls.txt: convert it to ReST markup
Documentation/bad_memory.txt: convert it to ReST markup
Documentation/basic_profiling.rst: convert to ReST markup
Documentation/binfmt_misc.txt: convert it to ReST markup
Documentation/serial-console.txt: convert it to ReST markup
Documentation/braille-console: convert it to ReST markup
Documentation/BUG-HUNTING: convert to ReST markup
Documentation/CodeOfConflict: add it to the development-process book
Documentation/devices.rst: convert it to ReST markup
Documentation/dynamic-debug-howto.txt: convert it to ReST markup
Documentation/initrd.txt: convert to ReST markup
Documentation/init.txt: convert to ReST markup
Documentation/magic-number.txt: convert it to ReST markup
Documentation/md.txt: Convert to ReST markup
Documentation/module-signing.txt: convert to ReST markup
Documentation/mono.txt: convert to ReST markup
Documentation/java.txt: convert to ReST markup
Documentation/oops-tracing.txt: convert to ReST markup
Documentation/parport.txt: convert to ReST markup
Documentation/ramoops.txt: convert it to ReST format
Documentation/sysfs-rules.txt: convert it to ReST markup
Documentation/sysrq.txt: convert to ReST markup
Documentation/unicode.txt: convert it to ReST markup
Documentation/VGA-softcursor.txt: convert to ReST markup
Documentation/volatile-considered-harmful.txt: convert to ReST markup
Documentation/parport.txt: fix table to show on LaTeX
docs-rst: user: add MAINTAINERS
Documentation/BUG-HUNTING | 164 +--
Documentation/CodeOfConflict | 1 +
Documentation/SecurityBugs | 12 +-
Documentation/VGA-softcursor.txt | 73 +-
Documentation/adding-syscalls.txt | 269 ++---
Documentation/applying-patches.txt | 2 +-
Documentation/bad_memory.txt | 26 +-
Documentation/basic_profiling.txt | 59 +-
Documentation/binfmt_misc.txt | 134 ++-
Documentation/braille-console.txt | 30 +-
Documentation/conf.py | 4 +-
Documentation/development-process/Changes.rst | 1 +
.../development-process/CodeOfConflict.rst | 1 +
Documentation/development-process/CodingStyle.rst | 1 +
Documentation/development-process/HOWTO.rst | 1 +
.../development-process/ManagementStyle.rst | 1 +
.../development-process/SubmitChecklist.rst | 1 +
.../development-process/SubmittingDrivers.rst | 1 +
.../development-process/SubmittingPatches.rst | 1 +
.../development-process/adding-syscalls.rst | 1 +
.../development-process/applying-patches.rst | 1 +
.../development-process/email-clients.rst | 1 +
Documentation/development-process/index.rst | 23 +
Documentation/development-process/kernel-docs.rst | 1 +
Documentation/development-process/magic-number.rst | 1 +
.../development-process/stable_api_nonsense.rst | 1 +
.../development-process/stable_kernel_rules.rst | 1 +
.../volatile-considered-harmful.rst | 1 +
Documentation/devices.txt | 1090 ++++++++++----------
Documentation/dynamic-debug-howto.txt | 297 +++---
Documentation/index.rst | 1 +
Documentation/init.txt | 29 +-
Documentation/initrd.txt | 199 ++--
Documentation/java.txt | 244 ++---
Documentation/kernel-parameters.txt | 33 +-
Documentation/magic-number.txt | 216 ++--
Documentation/md.txt | 528 ++++++----
Documentation/module-signing.txt | 117 +--
Documentation/mono.txt | 44 +-
Documentation/oops-tracing.txt | 255 ++---
Documentation/parport.txt | 287 +++---
Documentation/ramoops.txt | 88 +-
Documentation/serial-console.txt | 68 +-
Documentation/sysfs-rules.txt | 230 +++--
Documentation/sysrq.txt | 266 ++---
Documentation/unicode.txt | 22 +-
Documentation/user/BUG-HUNTING.rst | 1 +
Documentation/user/MAINTAINERS.rst | 174 ++++
Documentation/user/README.rst | 1 +
Documentation/user/REPORTING-BUGS.rst | 1 +
Documentation/user/SecurityBugs.rst | 1 +
Documentation/user/VGA-softcursor.rst | 1 +
Documentation/user/bad_memory.rst | 1 +
Documentation/user/basic_profiling.rst | 1 +
Documentation/user/binfmt_misc.rst | 1 +
Documentation/user/braile-console.rst | 1 +
Documentation/user/conf.py | 10 +
Documentation/user/devices.rst | 1 +
Documentation/user/dynamic-debug-howto.rst | 1 +
Documentation/user/index.rst | 35 +
Documentation/user/init.rst | 1 +
Documentation/user/initrd.rst | 1 +
Documentation/user/java.rst | 1 +
Documentation/user/kernel-parameters.rst | 1 +
Documentation/user/md.rst | 1 +
Documentation/user/module-signing.rst | 1 +
Documentation/user/mono.rst | 1 +
Documentation/user/oops-tracing.rst | 1 +
Documentation/user/parport.rst | 1 +
Documentation/user/ramoops.rst | 1 +
Documentation/user/serial-console.rst | 1 +
Documentation/user/sysfs-rules.rst | 1 +
Documentation/user/sysrq.rst | 1 +
Documentation/user/unicode.rst | 1 +
Documentation/volatile-considered-harmful.txt | 19 +-
MAINTAINERS | 3 +
README | 105 +-
REPORTING-BUGS | 68 +-
78 files changed, 2983 insertions(+), 2283 deletions(-)
create mode 120000 Documentation/development-process/Changes.rst
create mode 120000 Documentation/development-process/CodeOfConflict.rst
create mode 120000 Documentation/development-process/CodingStyle.rst
create mode 120000 Documentation/development-process/HOWTO.rst
create mode 120000 Documentation/development-process/ManagementStyle.rst
create mode 120000 Documentation/development-process/SubmitChecklist.rst
create mode 120000 Documentation/development-process/SubmittingDrivers.rst
create mode 120000 Documentation/development-process/SubmittingPatches.rst
create mode 120000 Documentation/development-process/adding-syscalls.rst
create mode 120000 Documentation/development-process/applying-patches.rst
create mode 120000 Documentation/development-process/email-clients.rst
create mode 120000 Documentation/development-process/kernel-docs.rst
create mode 120000 Documentation/development-process/magic-number.rst
create mode 120000 Documentation/development-process/stable_api_nonsense.rst
create mode 120000 Documentation/development-process/stable_kernel_rules.rst
create mode 120000 Documentation/development-process/volatile-considered-harmful.rst
create mode 120000 Documentation/user/BUG-HUNTING.rst
create mode 100644 Documentation/user/MAINTAINERS.rst
create mode 120000 Documentation/user/README.rst
create mode 120000 Documentation/user/REPORTING-BUGS.rst
create mode 120000 Documentation/user/SecurityBugs.rst
create mode 120000 Documentation/user/VGA-softcursor.rst
create mode 120000 Documentation/user/bad_memory.rst
create mode 120000 Documentation/user/basic_profiling.rst
create mode 120000 Documentation/user/binfmt_misc.rst
create mode 120000 Documentation/user/braile-console.rst
create mode 100644 Documentation/user/conf.py
create mode 120000 Documentation/user/devices.rst
create mode 120000 Documentation/user/dynamic-debug-howto.rst
create mode 100644 Documentation/user/index.rst
create mode 120000 Documentation/user/init.rst
create mode 120000 Documentation/user/initrd.rst
create mode 120000 Documentation/user/java.rst
create mode 120000 Documentation/user/kernel-parameters.rst
create mode 120000 Documentation/user/md.rst
create mode 120000 Documentation/user/module-signing.rst
create mode 120000 Documentation/user/mono.rst
create mode 120000 Documentation/user/oops-tracing.rst
create mode 120000 Documentation/user/parport.rst
create mode 120000 Documentation/user/ramoops.rst
create mode 120000 Documentation/user/serial-console.rst
create mode 120000 Documentation/user/sysfs-rules.rst
create mode 120000 Documentation/user/sysrq.rst
create mode 120000 Documentation/user/unicode.rst