documentation

readme.md

@@ -1,2 +1,62 @@
-* requires mariadb
+# Serienbrief
-* required cheetah3
+
+Using this script it is possible to generate form letters from a template and an SQL query.
+
+A template file with some placeholder variables is required and an SQL query to be executed
+against a MariaDB database. The column names from the query correspond to the variable names 
+in the template.
+
+The template is processed using the Cheetah template module, so simple variable placeholder 
+are just the variable name prefixed with the dollar-sign.
+
+However, all other Cheetah template language elements, like conditions, are also available.
+
+The script will generate one output file for each row from the result of the database query.
+
+## Usage
+
+    usage: serienbrief.py [-h] [--config CONFIG] [--query QUERY]
+                        [--template TEMPLATE] [--outputPrefix OUTPUTPREFIX]
+                        [--outputSuffix OUTPUTSUFFIX] [--verbose]
+
+    Serienbrief
+
+    optional arguments:
+    -h, --help            show this help message and exit
+    --config CONFIG, -f CONFIG
+                            Config file, default is $pwd/serienbrief.ini
+    --queryFile QUERY, -q QUERY
+                            query file, default is $pwd/serienbrief.sql
+    --templateFile TEMPLATE, -t TEMPLATE
+                            template file, default is $pwd/serienbrief.tmpl
+    --outputPrefix OUTPUTPREFIX, -p OUTPUTPREFIX
+                            prefix for the output file, will be extended by an
+                            auto increment number
+    --outputSuffix OUTPUTSUFFIX, -s OUTPUTSUFFIX
+                            suffix for the output file
+    --verbose, -v         verbose output
+
+
+## Config file
+
+The configuration file at least requires the database section. However, the options
+queryFile, templateFile, outputPrefix and outputSuffix can also be set using the
+configuration file.
+
+    [database]
+    host = 172.16.10.18
+    user = hv-serienbrief
+    pass = test123
+    name = hausverwaltung
+
+    [config]
+    queryFile = example.sql
+    templateFile = example.tmpl
+    outputPrefix = jahresabrechnung
+    outputSuffix = tex
+
+
+## Required modules
+
+* mariadb
+* cheetah3

serienbrief.py

@@ -9,11 +9,11 @@ parser.add_argument('--config', '-f',
                     help='Config file, default is $pwd/serienbrief.ini', 
                     required=False,
                     default='./serienbrief.ini')
-parser.add_argument('--query', '-q',
+parser.add_argument('--queryFile', '-q',
                     help='query file, default is $pwd/serienbrief.sql', 
                     required=False,
                     default='./serienbrief.sql')
-parser.add_argument('--template', '-t',
+parser.add_argument('--templateFile', '-t',
                     help='template file, default is $pwd/serienbrief.tmpl', 
                     required=False,
                     default='./serienbrief.tmpl')