diff options
authorElena ``of Valhalla'' Grandi <valhalla@trueelena.org>2017-07-26 21:05:21 +0200
committerElena ``of Valhalla'' Grandi <valhalla@trueelena.org>2017-07-26 21:05:21 +0200
commit626f81eb437cedc554ca1701aca483ebaedf9fdf (patch)
parentaa281b00ac74bca625af6eb69945886e50c61a2c (diff)
README: customization instructions
1 files changed, 34 insertions, 1 deletions
diff --git a/README.rst b/README.rst
index 7ee56cb..37b011b 100644
--- a/README.rst
+++ b/README.rst
@@ -25,6 +25,9 @@ files and a python3 script to generate the target postscript files.
.. _jinja2: http://jinja.pocoo.org/
.. _yaml: http://yaml.org/
+Pregenerated PDFs for many designs are `published on my website
@@ -61,7 +64,37 @@ some of the dependencies needed by the further steps.
+Every design is described by a file in the ``designs`` directory;
+filenames should end with the paper format (currently ``a4``, ``a5`` or
+``a6``) followed by ``.yaml`` to support proper pdf generation from the
+These files have the following fields.
+ selects one of the postscript templates in the ``src`` directory.
+ selects one of the paper definitions from ``conf/paper``.
+ selects one of the margin definitions from ``conf/margins``.
+ selects one of the theme definitions from ``conf/themes``.
+ selects one set of further, template specific, settings from
+ ``conf/settings/<theme name>``.
+ this is a dict which can be used to override any value from one of
+ the files above.
+The files in ``conf/*`` define the actual variables used in the jinja2
+templates; as the names suggests ``paper``, ``margings`` and ``themes``
+are common variables used in most templates, while the ones in the
+``settings`` subdirectories are specific to the template of the same name.
+The recommended way to customize a design or create a new one is to
+start by customising the values in the ``override`` dict in the
+``design/*.yaml`` file(s), and not to change the files in ``conf/`` but,
+if needed, create new ones.