[PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup

[PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

- use ReST markups for section headers;
- add cross-references to the options;
- mark code blocks;
- a few minor changes to make Sphinx happy.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/stable_kernel_rules.txt | 101 +++++++++++++++++++++++-----------
 1 file changed, 68 insertions(+), 33 deletions(-)

diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index ffd4575ec9f2..387d8a44eda2 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -1,4 +1,5 @@
-Everything you ever wanted to know about Linux -stable releases.
+Everything you ever wanted to know about Linux -stable releases
+===============================================================
 
 Rules on what kind of patches are accepted, and which ones are not, into the
 "-stable" tree:
@@ -27,7 +28,8 @@ Rules on what kind of patches are accepted, and which ones are not, into the
  - It or an equivalent fix must already exist in Linus' tree (upstream).
 
 
-Procedure for submitting patches to the -stable tree:
+Procedure for submitting patches to the -stable tree
+----------------------------------------------------
 
  - If the patch covers files in net/ or drivers/net please follow netdev stable
    submission guidelines as described in
@@ -35,56 +37,78 @@ Procedure for submitting patches to the -stable tree:
  - Security patches should not be handled (solely) by the -stable review
    process but should follow the procedures in Documentation/SecurityBugs.
 
-For all other submissions, choose one of the following procedures:
+For all other submissions, choose one of the following procedures
+-----------------------------------------------------------------
 
-   --- Option 1 ---
+.. _option_1:
+
+Option 1
+********
+
+To have the patch automatically included in the stable tree, add the tag
+
+.. code-block:: none
 
-   To have the patch automatically included in the stable tree, add the tag
      Cc: stable@vger.kernel.org
-   in the sign-off area. Once the patch is merged it will be applied to
-   the stable tree without anything else needing to be done by the author
-   or subsystem maintainer.
 
-   --- Option 2 ---
+in the sign-off area. Once the patch is merged it will be applied to
+the stable tree without anything else needing to be done by the author
+or subsystem maintainer.
 
-   After the patch has been merged to Linus' tree, send an email to
-   stable@vger.kernel.org containing the subject of the patch, the commit ID,
-   why you think it should be applied, and what kernel version you wish it to
-   be applied to.
+.. _option_2:
 
-   --- Option 3 ---
+Option 2
+********
 
-   Send the patch, after verifying that it follows the above rules, to
-   stable@vger.kernel.org.  You must note the upstream commit ID in the
-   changelog of your submission, as well as the kernel version you wish
-   it to be applied to.
+After the patch has been merged to Linus' tree, send an email to
+stable@vger.kernel.org containing the subject of the patch, the commit ID,
+why you think it should be applied, and what kernel version you wish it to
+be applied to.
 
-Option 1 is *strongly* preferred, is the easiest and most common.  Options 2 and
-3 are more useful if the patch isn't deemed worthy at the time it is applied to
-a public git tree (for instance, because it deserves more regression testing
-first).  Option 3 is especially useful if the patch needs some special handling
-to apply to an older kernel (e.g., if API's have changed in the meantime).
+.. _option_3:
 
-Note that for Option 3, if the patch deviates from the original upstream patch
-(for example because it had to be backported) this must be very clearly
-documented and justified in the patch description.
+Option 3
+********
+
+Send the patch, after verifying that it follows the above rules, to
+stable@vger.kernel.org.  You must note the upstream commit ID in the
+changelog of your submission, as well as the kernel version you wish
+it to be applied to.
+
+:ref:`option_1` is **strongly** preferred, is the easiest and most common.
+:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed
+worthy at the time it is applied to a public git tree (for instance, because
+it deserves more regression testing first).  :ref:`option_3` is especially
+useful if the patch needs some special handling to apply to an older kernel
+(e.g., if API's have changed in the meantime).
+
+Note that for :ref:`option_3`, if the patch deviates from the original
+upstream patch (for example because it had to be backported) this must be very
+clearly documented and justified in the patch description.
 
 The upstream commit ID must be specified with a separate line above the commit
 text, like this:
 
+.. code-block:: none
+
     commit <sha1> upstream.
 
 Additionally, some patches submitted via Option 1 may have additional patch
 prerequisites which can be cherry-picked. This can be specified in the following
 format in the sign-off area:
 
+.. code-block:: none
+
      Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
      Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
      Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
      Cc: <stable@vger.kernel.org> # 3.3.x
-    Signed-off-by: Ingo Molnar <mingo@elte.hu>
+     Signed-off-by: Ingo Molnar <mingo@elte.hu>
+
+The tag sequence has the meaning of:
+
+.. code-block:: none
 
-   The tag sequence has the meaning of:
      git cherry-pick a1f84a3
      git cherry-pick 1b9508f
      git cherry-pick fd21073
@@ -93,12 +117,17 @@ format in the sign-off area:
 Also, some patches may have kernel version prerequisites.  This can be
 specified in the following format in the sign-off area:
 
+.. code-block:: none
+
      Cc: <stable@vger.kernel.org> # 3.3.x-
 
-   The tag has the meaning of:
+The tag has the meaning of:
+
+.. code-block:: none
+
      git cherry-pick <this commit>
 
-   For each "-stable" tree starting with the specified version.
+For each "-stable" tree starting with the specified version.
 
 Following the submission:
 
@@ -109,7 +138,8 @@ Following the submission:
    other developers and by the relevant subsystem maintainer.
 
 
-Review cycle:
+Review cycle
+------------
 
  - When the -stable maintainers decide for a review cycle, the patches will be
    sent to the review committee, and the maintainer of the affected area of
@@ -125,17 +155,22 @@ Review cycle:
    security kernel team, and not go through the normal review cycle.
    Contact the kernel security team for more details on this procedure.
 
-Trees:
+Trees
+-----
 
  - The queues of patches, for both completed versions and in progress
    versions can be found at:
+
 	http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git
+
  - The finalized and tagged releases of all stable kernels can be found
    in separate branches per version at:
+
 	http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git
 
 
-Review committee:
+Review committee
+----------------
 
  - This is made up of a number of kernel developers who have volunteered for
    this task, and a few that haven't.
-- 
2.7.4

Re: [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup

[Greg KH]

On Mon, Sep 19, 2016 at 08:07:51AM -0300, Mauro Carvalho Chehab wrote:
> - use ReST markups for section headers;
> - add cross-references to the options;
> - mark code blocks;
> - a few minor changes to make Sphinx happy.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/stable_kernel_rules.txt | 101 +++++++++++++++++++++++-----------
>  1 file changed, 68 insertions(+), 33 deletions(-)
> 

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

[PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents

[Mauro Carvalho Chehab]

Add cross references for the documents mentioned at HOWTO and
are under the Documentation/ directory, using the ReST notation.

It should be noticed that HOWTO also mentions the /README file.
We opted to not touch it, for now, as making it build on
Sphinx would require it to be moved to a Documentation/foo
directory.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/Changes                 |  2 ++
 Documentation/CodingStyle             |  2 ++
 Documentation/HOWTO                   | 18 +++++++++---------
 Documentation/ManagementStyle         |  2 ++
 Documentation/SecurityBugs            |  2 ++
 Documentation/SubmittingDrivers       |  2 ++
 Documentation/SubmittingPatches       |  1 +
 Documentation/applying-patches.txt    |  1 +
 Documentation/kernel-docs.txt         |  2 ++
 Documentation/stable_api_nonsense.txt |  2 ++
 Documentation/stable_kernel_rules.txt |  2 ++
 11 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/Documentation/Changes b/Documentation/Changes
index 93c8e1c15844..754cd50c1bc6 100644
--- a/Documentation/Changes
+++ b/Documentation/Changes
@@ -1,3 +1,5 @@
+.. _changes:
+
 Minimal requerements to compile the Kernel
 ++++++++++++++++++++++++++++++++++++++++++
 
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 7e30da38bb3a..852253c932fe 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -1,3 +1,5 @@
+.. _codingstyle:
+
 Linux kernel coding style
 =========================
 
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index 5a85e3a8112b..31c8df5d20c7 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -90,19 +90,19 @@ required reading:
     what is necessary to do to configure and build the kernel.  People
     who are new to the kernel should start here.
 
-  Documentation/Changes
+  :ref:`Documentation/Changes <changes>`
     This file gives a list of the minimum levels of various software
     packages that are necessary to build and run the kernel
     successfully.
 
-  Documentation/CodingStyle
+  :ref:`Documentation/CodingStyle <codingstyle>`
     This describes the Linux kernel coding style, and some of the
     rationale behind it. All new code is expected to follow the
     guidelines in this document. Most maintainers will only accept
     patches if these rules are followed, and many people will only
     review code if it is in the proper style.
 
-  Documentation/SubmittingPatches and Documentation/SubmittingDrivers
+  :ref:`Documentation/SubmittingPatches <submittingpatches>` and :ref:`Documentation/SubmittingDrivers <submittingdrivers>`
     These files describe in explicit detail how to successfully create
     and send a patch, including (but not limited to):
 
@@ -124,7 +124,7 @@ required reading:
 
 		http://linux.yyz.us/patch-format.html
 
-  Documentation/stable_api_nonsense.txt
+  :ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>`
     This file describes the rationale behind the conscious decision to
     not have a stable API within the kernel, including things like:
 
@@ -137,29 +137,29 @@ required reading:
     philosophy and is very important for people moving to Linux from
     development on other Operating Systems.
 
-  Documentation/SecurityBugs
+  :ref:`Documentation/SecurityBugs <securitybugs>`
     If you feel you have found a security problem in the Linux kernel,
     please follow the steps in this document to help notify the kernel
     developers, and help solve the issue.
 
-  Documentation/ManagementStyle
+  :ref:`Documentation/ManagementStyle <managementstyle>`
     This document describes how Linux kernel maintainers operate and the
     shared ethos behind their methodologies.  This is important reading
     for anyone new to kernel development (or anyone simply curious about
     it), as it resolves a lot of common misconceptions and confusion
     about the unique behavior of kernel maintainers.
 
-  Documentation/stable_kernel_rules.txt
+  :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
     This file describes the rules on how the stable kernel releases
     happen, and what to do if you want to get a change into one of these
     releases.
 
-  Documentation/kernel-docs.txt
+  :ref:`Documentation/kernel-docs.txt <kernel_docs>`
     A list of external documentation that pertains to kernel
     development.  Please consult this list if you do not find what you
     are looking for within the in-kernel documentation.
 
-  Documentation/applying-patches.txt
+  :ref:`Documentation/applying-patches.txt <applying_patches>`
     A good introduction describing exactly what a patch is and how to
     apply it to the different development branches of the kernel.
 
diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle
index 1471df6015a2..dea2e66c9a10 100644
--- a/Documentation/ManagementStyle
+++ b/Documentation/ManagementStyle
@@ -1,3 +1,5 @@
+.. _managementstyle:
+
 Linux kernel management style
 =============================
 
diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs
index 10a1f79376a2..342d769834f6 100644
--- a/Documentation/SecurityBugs
+++ b/Documentation/SecurityBugs
@@ -1,3 +1,5 @@
+.. _securitybugs:
+
 Security bugs
 =============
 
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
index a2f30a9e28d1..2ac931645e53 100644
--- a/Documentation/SubmittingDrivers
+++ b/Documentation/SubmittingDrivers
@@ -1,3 +1,5 @@
+.. _submittingdrivers:
+
 Submitting Drivers For The Linux Kernel
 =======================================
 
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 352771b736cd..9c3dfa7babf3 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -1,3 +1,4 @@
+.. _submittingpatches:
 
 How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
 =========================================================================================
diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt
index 0e873dbf5566..bc113bff86b7 100644
--- a/Documentation/applying-patches.txt
+++ b/Documentation/applying-patches.txt
@@ -1,3 +1,4 @@
+.. _applying_patches:
 
 Applying Patches To The Linux Kernel
 ++++++++++++++++++++++++++++++++++++
diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 7ca806184426..955f5b775e69 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -1,3 +1,5 @@
+.. _kernel_docs:
+
 Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel
 =============================================================================================
 
diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt
index 9187b4ef4bac..24f5aeecee91 100644
--- a/Documentation/stable_api_nonsense.txt
+++ b/Documentation/stable_api_nonsense.txt
@@ -1,3 +1,5 @@
+.. _stable_api_nonsense:
+
 The Linux Kernel Driver Interface
 ==================================
 
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index 387d8a44eda2..1eba72708c7f 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -1,3 +1,5 @@
+.. _stable_kernel_rules:
+
 Everything you ever wanted to know about Linux -stable releases
 ===============================================================
 
-- 
2.7.4

Re: [PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents

[Greg KH]

On Mon, Sep 19, 2016 at 08:07:56AM -0300, Mauro Carvalho Chehab wrote:
> Add cross references for the documents mentioned at HOWTO and
> are under the Documentation/ directory, using the ReST notation.
> 
> It should be noticed that HOWTO also mentions the /README file.
> We opted to not touch it, for now, as making it build on
> Sphinx would require it to be moved to a Documentation/foo
> directory.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---


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