[master] 98945cea5 Define a standard for RST document structure adornments

[Nils Goroll]

commit 98945cea5f3b3b98672b190dc78b1eb28769dc2c
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Thu Feb 1 14:39:54 2024 +0100

    Define a standard for RST document structure adornments
    
    ... and minor touch up of the file.
    
    No, this does not imply me checking all our RST files for adherence with
    this standard.
    
    Ref 0d663a5e7b53f52e1a2c94be4081eb47e9d7be4f

diff --git a/doc/README.WRITING_RST.rst b/doc/README.WRITING_RST.rst
index f64cab47c..21fe17a0d 100644
--- a/doc/README.WRITING_RST.rst
+++ b/doc/README.WRITING_RST.rst
@@ -1,5 +1,5 @@
 ..
-	Copyright (c) 2015-2019 Varnish Software AS
+	Copyright 2015,2016,2019,2024 UPLEX - Nils Goroll Systemoptimierung
 	SPDX-License-Identifier: BSD-2-Clause
 	See LICENSE file for full text of license
 
@@ -24,9 +24,9 @@ not follow the style:
 
 * use code blocks for::
 
-  Examples and
+    Examples and
 
-  other code
+    other code
 
 References are tricky
 ---------------------
@@ -70,6 +70,28 @@ of documentation:
 
 .. _implicit link targets: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets
 
+Document Structure
+------------------
+
+While RST supports a great deal of flexibility for adornments of
+titles and section headers, we should adhere to a consistent style to
+avoid breaking the document structure unintentially.
+
+Within the Varnish-Cache project, we should use these characters:
+
+* Over and underline ``=`` for document titles
+
+* Over and underline ``-`` for document subtitles
+
+* Underline ``=`` for sections
+
+* Underline ``-`` for subsection
+
+* Underline ``~`` for subsubsections
+
+This is in line with the example in
+https://docutils.sourceforge.io/docs/user/rst/quickstart.html#sections
+
 HISTORY
 =======
 
@@ -81,4 +103,5 @@ COPYRIGHT
 This document is licensed under the same licence as Varnish
 itself. See LICENCE for details.
 
-* Copyright 2014 UPLEX - Nils Goroll Systemoptimierung
+* Copyright 2015,2016,2019,2024 UPLEX - Nils Goroll
+  Systemoptimierung