docs: style guide: add hints about section ordering ...

and information of differences between inlcude and toctree.
Renamed file to circumwent sphinx problems with include.

docs/manuals/en/style_guide/source/general.rst

@@ -169,29 +169,40 @@ Alternatively, you can reference any label (not just section titles)
 if you provide the link text ``:ref:`link text <reference-label>```.
 
 
-
 Sections
 --------
 
-From https://devguide.python.org/documenting/#sections.
-
 Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:
 
 ::
 
-   =================
+   #################
    This is a heading
-   =================
+   #################
 
-Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for the Python documentation, here is a suggested convention:
+Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this is our convention:
 
 * ``#`` with overline, for parts
-* ``*`` with overline, for chapters
-* ``=``, for sections
-* ``-``, for subsections
+* ``=`` for chapters
+* ``-``, for sections
+* ``~``, for subsections
 * ``^``, for subsubsections
-* ``"``, for paragraphs   
+* ``'``, for paragraphs
+
+This convention has be introduced from the conversion of thw original LaTex source to RST,
+as :program:`pandoc` has created RST file with this section markers (except of parts, which are not created at all).
 
+.. note::
+
+   With RST, there is no leaving out a section level.
+   If you write a chapter it is not possible to continue with a paragraph.
+   Instead the next section must be of the type section.
+
+   If you try to do it overwise (chapter 1 ``=`` -> paragraph ``'``),
+   the ''paragraph'' is treated as a section.
+   And if you continue by another chapter (in the same file) (chapter 2 ``=`` -> section ``-``),
+   :program:`sphinx-build` got confused and at least produces a warning (`Title level inconsistent`)
+   and possibly renders the result incorrectly.
 
 
 File/Directory/Path
@@ -212,11 +223,11 @@ Backslahes (Windows paths) ``\`` have to written as ``\\``:
 
 The output should look like this:
 
-.. include:: include/file.rst
+.. include:: include/file.rst.inc
 
 The formatting looks a follows:
 
-.. literalinclude:: include/file.rst
+.. literalinclude:: include/file.rst.inc
 
 
 

docs/manuals/en/style_guide/source/index.rst

@@ -17,3 +17,4 @@ Bareos Style Guide
    seldom_text
    images
    releases
+   trouble

docs/manuals/en/style_guide/source/trouble.rst

@@ -0,0 +1,32 @@
+Trouble
+=======
+
+toctree vs include
+------------------
+
+include
+"""""""
+
+If a source file add another file via **include**,
+it will be integrated into the original source file (and not handled as a seperate file).
+
+As sphinx-build scans all matchin files during the build process, it takes toctree inclusion into account, but not plain **include** statements. As result, it will see the content of the included file twice: one as included file as part of the source file, once by the scan process during the build. Sphinx will then complain about double defined heading and references.
+
+To avoid this, included files should use a different extension as the normal files (included by toctree).
+
+  * Extention of the master file and files included by **toctree**: ``*.rst``
+  * Extention of files included by **include**: ``*.rst.inc``
+
+..
+
+   does include keep the document structre as toctree does?
+
+
+toctree
+"""""""
+
+* When using (nested) toctrees, make sure to define a section header above it. Otherwise the header line of the result document will show **<no title>** in the hierarchie of headings.
+
+* All files included by toctree start at the same section level. If the sections of a document should start at a lower level, a nested toctree element is needed.
+
+* **Important**: files names of files included via toctree are part of the URL of the document. That means, they are also part of the URL of the references/sections. And the URL will change when a section is moved to another place. Therefore inclusion via **toctree should be avoided**!