README

1 files changed, 94 insertions, 0 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..7ee56cb
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,94 @@
+===========================
+ 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.