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

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

TODO


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.