===========================
 Graph Paper in Postscript
===========================

This is a collection of postscript programs to generate various types of
graph and ruled paper.

.. contents::

The following types are currently available:

* regular graph paper (uniform squares);
* iso paper;
* hex paper;
* pointed paper (squares marked by small points at the corner instead of
  lines);
* music paper;

customizable for paper size, design size and colours.

To allow automatic building of different variants based on saved
settings, they are distributed as jinja2_ templates, yaml_ settings
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
------------

Dependencies
~~~~~~~~~~~~

To build the postscript files from the templates and settings files you
need python3, jinja2_ and ruamel.yaml_.
Generating PDF from the PS ones requires also ps2pdf (part of
ghostscript_) and pdfjam.
There is a Makefile (tested with `GNU make`_) to build everything in an
automated way.

.. _ruamel.yaml: https://pypi.python.org/pypi/ruamel.yaml
.. _ghostscript: http://www.ghostscript.com/
.. _pdfjam: http://www2.warwick.ac.uk/fac/sci/statistics/staff/academic-research/firth/software/pdfjam
.. _`GNU make`: https://www.gnu.org/software/make/

Under Debian and derived distributions the following packages are needed::

    apt install python3-jinja2 python3-ruamel.yaml \
        ghostscript texlive-extra-utils make

Building
~~~~~~~~

Simply run ``make`` with no options to build everything: postscript, PDF
and n-up versions of PDF files smaller than A4.

Subtargets are available to build just the postscript files (``make
ps``) and PDF (``make pdf``), and can be used in case you are missing
some of the dependencies needed by the further steps.

Customizing
~~~~~~~~~~~

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
-------

Copyright (C) 2004-2017 Elena Grandi
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
* Neither the name of the author nor the names of its contributors may
  be used to endorse or promote products derived from this software
  without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.