fix PDF rendering structure

without those changes, all of the toctree document headings do not
show up. they are considered to be "below" the last heading of the
README file.

we also remove the "Notes" section from the readme as there is only
one note, regarding the fork.

we introduce a stub "introduction" element in the toctree, otherwise
it is impossible for the PDF rendered to render the README correctly.

this is to workaround a bug in the PDF renderer.

README.rst

@@ -3,7 +3,7 @@
 .. highlight:: bash
 
 What is BorgBackup?
-===================
+-------------------
 
 BorgBackup (short: Borg) is a deduplicating backup program.
 Optionally, it supports compression and authenticated encryption.
@@ -20,7 +20,7 @@ downloaded Borg, ``docs/installation.rst`` to get started with Borg.
 .. _installation manual: https://borgbackup.readthedocs.org/en/stable/installation.html
 
 Main features
--------------
+~~~~~~~~~~~~~
 
 **Space efficient storage**
   Deduplication based on content-defined chunking is used to reduce the number
@@ -82,7 +82,7 @@ Main features
     complete license
 
 Easy to use
------------
+~~~~~~~~~~~
 
 Initialize a new backup repository and create a backup archive::
 
@@ -114,7 +114,7 @@ Now doing another backup, just to show off the great deduplication:
 For a graphical frontend refer to our complementary project `BorgWeb <https://borgweb.readthedocs.io/>`_.
 
 Checking Release Authenticity and Security Contact
-==================================================
+--------------------------------------------------
 
 `Releases <https://github.com/borgbackup/borg/releases>`_ are signed with this GPG key,
 please use GPG to verify their authenticity.
@@ -130,7 +130,7 @@ The public key can be fetched from any GPG keyserver, but be careful: you must
 use the **full fingerprint** to check that you got the correct key.
 
 Links
-=====
+-----
 
 * `Main Web Site <https://borgbackup.readthedocs.org/>`_
 * `Releases <https://github.com/borgbackup/borg/releases>`_,
@@ -144,7 +144,7 @@ Links
 * `License <https://borgbackup.readthedocs.org/en/stable/authors.html#license>`_
 
 Compatibility notes
-===================
+-------------------
 
 EXPECT THAT WE WILL BREAK COMPATIBILITY REPEATEDLY WHEN MAJOR RELEASE NUMBER
 CHANGES (like when going from 0.x.y to 1.0.0 or from 1.x.y to 2.0.0).

docs/book.rst

@@ -0,0 +1,22 @@
+.. include:: global.rst.inc
+
+Borg documentation
+==================
+
+.. when you add an element here, do not forget to add it to index.rst
+
+.. toctree::
+    :maxdepth: 3
+
+    introduction
+    installation
+    quickstart
+    usage
+    deployment
+    faq
+    support
+    resources
+    changes
+    internals
+    development
+    authors

docs/conf.py

@@ -198,7 +198,7 @@ htmlhelp_basename = 'borgdoc'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'Borg.tex', 'Borg Documentation',
+  ('book', 'Borg.tex', 'Borg Documentation',
    'The Borg Collective', 'manual'),
 ]
 

docs/index.rst

@@ -6,6 +6,8 @@ Borg Documentation
 
 .. include:: ../README.rst
 
+.. when you add an element here, do not forget to add it to book.rst
+
 .. toctree::
    :maxdepth: 2
 

docs/introduction.rst

@@ -0,0 +1,8 @@
+Introduction
+============
+
+.. this shim is here to fix the structure in the PDF
+   rendering. without this stub, the elements in the toctree of
+   index.rst show up a level below the README file included
+
+.. include:: ../README.rst