[PATCH] docs-rst: add inter-document cross references

[PATCH] docs-rst: add inter-document cross references

[Mauro Carvalho Chehab]

Add cross references for the development process documents
that were converted to ReST:
	Documentation/SubmitChecklist
	Documentation/SubmittingDrivers
	Documentation/SubmittingPatches
	Documentation/development-process/development-process.rst
	Documentation/stable_kernel_rules.txt

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---

The changes here were at patch 29/29, that did the rename. I opted to
split this change to just add the cross-references without the rename, as
it makes easier if we decide to use symlinks instead of renames.

As I rebased the rename patch as well, on the top of this one, we can
also use the rename, if people find it better.

 Documentation/SubmitChecklist                      | 10 +++++----
 Documentation/SubmittingDrivers                    |  7 ++++---
 Documentation/SubmittingPatches                    | 24 ++++++++++++++--------
 .../development-process/development-process.rst    |  2 ++
 Documentation/stable_kernel_rules.txt              |  7 +++++--
 5 files changed, 32 insertions(+), 18 deletions(-)

diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
index 22a370ff34e5..894289b22b15 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -1,3 +1,5 @@
+.. _submitchecklist:
+
 Linux Kernel patch submission checklist
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -5,7 +7,7 @@ Here are some basic things that developers should do if they want to see their
 kernel patch submissions accepted more quickly.
 
 These are all above and beyond the documentation that is provided in
-Documentation/SubmittingPatches
+:ref:`Documentation/SubmittingPatches <submittingpatches>`
 and elsewhere regarding submitting Linux kernel patches.
 
 
@@ -28,8 +30,8 @@ and elsewhere regarding submitting Linux kernel patches.
 4) ppc64 is a good architecture for cross-compilation checking because it
    tends to use ``unsigned long`` for 64-bit quantities.
 
-5: Check your patch for general style as detailed in
-   Documentation/CodingStyle.
+5) Check your patch for general style as detailed in
+   :ref:`Documentation/CodingStyle <codingstyle>`.
    Check for trivial violations with the patch style checker prior to
    submission (``scripts/checkpatch.pl``).
    You should be able to justify all violations that remain in
@@ -54,7 +56,7 @@ and elsewhere regarding submitting Linux kernel patches.
        but any one function that uses more than 512 bytes on the stack is a
        candidate for change.
 
-11: Include :ref:`kernel-doc <kernel_doc>` to document global  kernel APIs.
+11) Include :ref:`kernel-doc <kernel_doc>` to document global  kernel APIs.
     (Not required for static functions, but OK there also.) Use
     ``make htmldocs`` or ``make pdfdocs`` to check the
     :ref:`kernel-doc <kernel_doc>` and fix any issues.
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
index 2ac931645e53..252b77a23fad 100644
--- a/Documentation/SubmittingDrivers
+++ b/Documentation/SubmittingDrivers
@@ -40,9 +40,9 @@ Linux 2.4:
 	maintainer does not respond or you cannot find the appropriate
 	maintainer then please contact Willy Tarreau <w@1wt.eu>.
 
-Linux 2.6:
+Linux 2.6 and upper:
 	The same rules apply as 2.4 except that you should follow linux-kernel
-	to track changes in API's. The final contact point for Linux 2.6
+	to track changes in API's. The final contact point for Linux 2.6+
 	submissions is Andrew Morton.
 
 What Criteria Determine Acceptance
@@ -73,7 +73,8 @@ Interfaces:
 
 Code:
 		Please use the Linux style of code formatting as documented
-		in Documentation/CodingStyle. If you have sections of code
+		in :ref:`Documentation/CodingStyle <codingStyle>`.
+		If you have sections of code
 		that need to be in other formats, for example because they
 		are shared with a windows driver kit and you want to
 		maintain them just once separate them out nicely and note
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9c3dfa7babf3..36f1dedc944c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -10,10 +10,12 @@ can greatly increase the chances of your change being accepted.
 
 This document contains a large number of suggestions in a relatively terse
 format.  For detailed information on how the kernel development process
-works, see Documentation/development-process.  Also, read
-Documentation/SubmitChecklist for a list of items to check before
+works, see :ref:`Documentation/development-process <development_process_main>`.
+Also, read :ref:`Documentation/SubmitChecklist <submitchecklist>`
+for a list of items to check before
 submitting code.  If you are submitting a driver, also read
-Documentation/SubmittingDrivers; for device tree binding patches, read
+:ref:`Documentation/SubmittingDrivers <submittingdrivers>`;
+for device tree binding patches, read
 Documentation/devicetree/bindings/submitting-patches.txt.
 
 Many of these steps describe the default behavior of the ``git`` version
@@ -235,7 +237,9 @@ then only post say 15 or so at a time and wait for review and integration.
 ---------------------------
 
 Check your patch for basic style violations, details of which can be
-found in Documentation/CodingStyle.  Failure to do so simply wastes
+found in
+:ref:`Documentation/CodingStyle <codingstyle>`.
+Failure to do so simply wastes
 the reviewers time and will get your patch rejected, probably
 without even being read.
 
@@ -300,8 +304,9 @@ toward the stable maintainers by putting a line like this::
   Cc: stable@vger.kernel.org
 
 into the sign-off area of your patch (note, NOT an email recipient).  You
-should also read Documentation/stable_kernel_rules.txt in addition to this
-file.
+should also read
+:ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
+in addition to this file.
 
 Note, however, that some subsystem maintainers want to come to their own
 conclusions on which patches should go to the stable trees.  The networking
@@ -358,8 +363,9 @@ decreasing the likelihood of your MIME-attached change being accepted.
 Exception:  If your mailer is mangling patches then someone may ask
 you to re-send them using MIME.
 
-See Documentation/email-clients.txt for hints about configuring
-your e-mail client so that it sends your patches untouched.
+See :ref:`Documentation/email-clients.txt <email_clients>`
+for hints about configuring your e-mail client so that it sends your patches
+untouched.
 
 7) E-mail size
 --------------
@@ -823,7 +829,7 @@ NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
   <https://lkml.org/lkml/2005/7/11/336>
 
 Kernel Documentation/CodingStyle:
-  <Documentation/CodingStyle>
+  :ref:`Documentation/CodingStyle <codingstyle>`
 
 Linus Torvalds's mail on the canonical patch format:
   <http://lkml.org/lkml/2005/4/7/183>
diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst
index d431a1098875..bd1399f7202a 100644
--- a/Documentation/development-process/development-process.rst
+++ b/Documentation/development-process/development-process.rst
@@ -1,3 +1,5 @@
+.. _development_process_main:
+
 A guide to the Kernel Development Process
 =========================================
 
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index 1eba72708c7f..4d82e31b7958 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -26,7 +26,9 @@ Rules on what kind of patches are accepted, and which ones are not, into the
    race can be exploited is also provided.
  - It cannot contain any "trivial" fixes in it (spelling changes,
    whitespace cleanups, etc).
- - It must follow the Documentation/SubmittingPatches rules.
+ - It must follow the
+   :ref:`Documentation/SubmittingPatches <submittingpatches>`
+   rules.
  - It or an equivalent fix must already exist in Linus' tree (upstream).
 
 
@@ -37,7 +39,8 @@ Procedure for submitting patches to the -stable tree
    submission guidelines as described in
    Documentation/networking/netdev-FAQ.txt
  - Security patches should not be handled (solely) by the -stable review
-   process but should follow the procedures in Documentation/SecurityBugs.
+   process but should follow the procedures in
+   :ref:`Documentation/SecurityBugs <securitybugs>`.
 
 For all other submissions, choose one of the following procedures
 -----------------------------------------------------------------
-- 
2.7.4

Re: [PATCH] docs-rst: add inter-document cross references

[Greg Kroah-Hartman]

On Wed, Sep 21, 2016 at 08:51:05AM -0300, Mauro Carvalho Chehab wrote:
> Add cross references for the development process documents
> that were converted to ReST:
> 	Documentation/SubmitChecklist
> 	Documentation/SubmittingDrivers
> 	Documentation/SubmittingPatches
> 	Documentation/development-process/development-process.rst
> 	Documentation/stable_kernel_rules.txt
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> 
> The changes here were at patch 29/29, that did the rename. I opted to
> split this change to just add the cross-references without the rename, as
> it makes easier if we decide to use symlinks instead of renames.
> 
> As I rebased the rename patch as well, on the top of this one, we can
> also use the rename, if people find it better.

For the stable_kernel_rules.txt portion:

Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

Re: [PATCH] docs-rst: add inter-document cross references

[Jonathan Corbet]

On Wed, 21 Sep 2016 08:51:05 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> Add cross references for the development process documents
> that were converted to ReST:
> 	Documentation/SubmitChecklist
> 	Documentation/SubmittingDrivers
> 	Documentation/SubmittingPatches
> 	Documentation/development-process/development-process.rst
> 	Documentation/stable_kernel_rules.txt

Applied, thanks.

...and now I'm thinking that's maybe about enough in docs for 4.9...:)

jon

Re: [PATCH] docs-rst: add inter-document cross references

[Mauro Carvalho Chehab]

Hi Jon,

Em Wed, 21 Sep 2016 15:44:05 -0600
Jonathan Corbet <corbet@lwn.net> 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