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
+<https://www.trueelena.org/computers/scripts/graph_paper_in_postscript.html>`_
+
 Instructions
 ------------
 
@@ -61,7 +64,37 @@ some of the dependencies needed by the further steps.
 Customizing
 ~~~~~~~~~~~
 
-TODO
+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
+makefile.
+
+These files have the following fields.
+
+``template``:
+   selects one of the postscript templates in the ``src`` directory.
+``paper``:
+   selects one of the paper definitions from ``conf/paper``.
+``margins``:
+   selects one of the margin definitions from ``conf/margins``.
+``theme``:
+   selects one of the theme definitions from ``conf/themes``.
+``settings``:
+   selects one set of further, template specific, settings from
+   ``conf/settings/<theme name>``.
+``override``:
+   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.
 
 
 License