Merge branch 'more-info-about-styles-in-manual'

Closes #1052

doc/manual.rst

@@ -241,6 +241,12 @@ In general, applying a stylesheet to a structured document will output a decent
 Applying Styles
 ~~~~~~~~~~~~~~~
 
+rst2pdf applies a default set of styles to the document. This default set can be viewed using ``rst2pdf --print-stylesheet`` which prints outh ``rst2pdf/styles/styles.yaml``.
+
+Each subsequent style within each style sheet file specified the ``--stylesheets`` CLI parameter is then registered in the the list of known styles known to rst2pdf. If the name of the style is already known, then the attributes specified in the style are applied "on top" of the already registered style.
+
+rst2pdf will then resolve the ``parent`` style, which is why the order of inclusion matters per-style-name, not globally. That is, if you set the color of ``bodytext`` first in a file and then set the color of ``normal`` in a subsequent file, then the color you have set for ``bodytext`` will be the color used for paragraphs (unless overridden by a ``class`` directive. Further information on cereating stylesheet files is available in `Creating Stylesheets`_.
+
 You can style paragraphs with a style using the class directive::
 
   .. class:: special

rst2pdf/tests/input/blue_text.yaml

@@ -0,0 +1,4 @@
+---
+styles:
+  bodytext:
+    textColor: blue

rst2pdf/tests/input/green_text.yaml

@@ -0,0 +1,4 @@
+---
+styles:
+  bodytext:
+    textColor: green

rst2pdf/tests/input/red_text.yaml

@@ -0,0 +1,4 @@
+---
+styles:
+  normal:
+    textColor: red

rst2pdf/tests/input/test_multiple_stylesheet_files.cli

@@ -0,0 +1 @@
+-s a4-landscape,a4,green_text.yaml,blue_text.yaml,red_text.yaml

rst2pdf/tests/input/test_multiple_stylesheet_files.rst

@@ -0,0 +1,44 @@
+Test of multiple stylesheet files
+=================================
+
+This test ensures that multiple style files are applied as we expect.
+
+This CLI is used:
+
+.. code-block:: text
+   :include: test_multiple_stylesheet_files.cli
+
+green_text.yaml:
+
+.. code-block:: yaml
+   :include: green_text.yaml
+
+blue_text.yaml:
+
+.. code-block:: yaml
+   :include: blue_text.yaml
+
+red_text.yaml:
+
+.. code-block:: yaml
+   :include: red_text.yaml
+
+
+Page orientation
+----------------
+
+The order of ``a4-landscape`` and then ``a4`` means that the final page size set will be A4 portrait.
+
+Colours
+-------
+
+The paragraph text is blue.
+
+This is because even though ``red_text.yaml`` is applied last, it is setting the text colour of ``normal``,
+whereas ``blue_text.yaml`` sets the text colour of ``bodytext``.
+As ``bodytext`` has a ``parent`` of ``normal``, then the last file (left to right) that sets the ``bodytext``
+style, so the specification in ``green_text.yaml`` is ignored.
+
+| Note that all ``literal`` elements are red as ``literal`` has a parent of ``normal`` which is now red.
+| Also, all headings are black as their parent is ``heading`` which explicitly sets textColor to black
+  even though it has a parent of ``normal``.