linux-kernel - [RFC PATCH 4/5] docs/doc-guide: Pull guidelines for title adornments out into subsection

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 9 Jun 2022 22:27:27 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc:     Mauro Carvalho Chehab <mchehab@...nel.org>,
        "Maciej W. Rozycki" <macro@...am.me.uk>,
        Miguel Ojeda <ojeda@...nel.org>, linux-kernel@...r.kernel.org,
        Akira Yokosawa <akiyks@...il.com>
Subject: [RFC PATCH 4/5] docs/doc-guide: Pull guidelines for title adornments
 out into subsection

As it becomes too large as an item in bullet lists, make it a
subsection of its own.

Signed-off-by: Akira Yokosawa <akiyks@...il.com>
---
 Documentation/doc-guide/sphinx.rst | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index f257c4785607..f8bbf86fa15a 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -202,7 +202,16 @@ Here are some specific guidelines for the kernel documentation:
 * Also update the content, not just the formatting, when converting
   documentation.
 
-* Please stick to this relative order of section title adornments:
+* For inserting fixed width text blocks (for code examples, use case
+  examples, etc.), use ``::`` for anything that doesn't really benefit
+  from syntax highlighting, especially short snippets. Use
+  ``.. code-block:: <language>`` for longer code blocks that benefit
+  from highlighting. For a short snippet of code embedded in the text, use \`\`.
+
+Guidelines for title adornments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please stick to this relative order of section title adornments:
 
   1. ``=`` with overline for 1st level titles::
 
@@ -225,12 +234,12 @@ Here are some specific guidelines for the kernel documentation:
        4th level title
        ~~~~~~~~~~~~~~~
 
-  Although RST doesn't mandate a specific order ("Rather than imposing a fixed
-  number and order of section title adornment styles, the order enforced will be
-  the order as encountered."), having the higher levels the same overall makes
-  it easier to follow the documents.
+Although RST doesn't mandate a specific order ("Rather than imposing a fixed
+number and order of section title adornment styles, the order enforced will be
+the order as encountered."), having the higher levels the same overall makes
+it easier to follow the documents.
 
-  .. note::
+.. note::
     - It is not easy to tell the levels (chapter, section, etc.) of title
       adornments in a particular .rst file.  A title that appears first in
       a .rst file can be at any level of document, chapter, section, or
@@ -258,7 +267,7 @@ Here are some specific guidelines for the kernel documentation:
     .. [#rstdoc] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document
     .. [#rstdirtitle] https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title
 
-  .. warning::
+.. warning::
     For existing documents, manually updating title adornments just to meet
     these guidelines is not recommended.  Such changes can be error-prone and
     may break section hierarchy without being caught by reviewers.  They may
@@ -268,12 +277,6 @@ Here are some specific guidelines for the kernel documentation:
     It would be appreciated if adjustment of those adornments could be
     automated in some way.
 
-* For inserting fixed width text blocks (for code examples, use case
-  examples, etc.), use ``::`` for anything that doesn't really benefit
-  from syntax highlighting, especially short snippets. Use
-  ``.. code-block:: <language>`` for longer code blocks that benefit
-  from highlighting. For a short snippet of code embedded in the text, use \`\`.
-
 
 the C domain
 ------------
-- 
2.25.1