lbp_print
is a small utility for processing a LombardPress valid XML text with a relevant XSLT script and compile to PDF with XeLaTeX.
The script requires Python 3.6 installed in your system. If you are on a Mac OSX machine, and you use Homebrew, you can run brew install python3
. If you do not use Homebrew, download the latest official python distribution and follow the instructions.
The simplest way to install it is via pypi:
pip3 install lbp_print
It will most likely throw an error that it cannot find a version satisfying lbppy>=0.0.0 (from lbp_print)
. You solve that by first installing lbbpy
from the Github repository:
pip3 install git+https://github.com/lombardpress/lbppy.git@master#egg=lbppy
If you want to clone the repository, notice that the xslt is included as submodule of lbp-print-xslt, so you need to clone with the --recursive
flag.
git clone --recursive https://github.com/stenskjaer/lbp_print.git
If you want to test or hack on the package, or if you would like to try out the script without installing anything permanently on your system, a virtual environment setup is the best solution.
To create a virtual environment for the project, run:
$ python3 -m venv <name>
Where <name>
is the name you want to give the venv. A typical practice is to name it .env
or something like that. It will create a directory in the root of the project directory called .env
which contains the environment.
Now activate the environment:
$ source .env/bin/activate
And install dependencies the dependencies of the script:
$ pip3 install -r requirements.txt
Now you can make the package globally available (in the virtual environment, if you want), but use the -e
flag during installation to symlink the source files and the global CLI. Then if you make any changes in the script, it is available in the global CLI. Try it with (from the base dir of the package):
pip install -e .
Now you should be able to run the script (while the virtual environment is activated) with the following command:
$ lbp_print pdf --scta http://scta.info/resource/lectio1
You should now be able to find the result in the directory output in the current working dir.
When you are done, you can reset your system to the state before testing, deactivate the virtual environment. If you never want to use the script again, remove the directory of the environment (possibly with rmvirtualenv
if you have installed virtualenvwrapper
) and remove the directory created by the git clone
command.
If you would like to install the script for general usage on you system, you should run the command
python3 setup.py install
Now try:
$ lbp_print.py pdf --scta http://scta.info/resource/lectio1
This will, as default, put the results in a directory called output
in the directory where you call the command.
Aside from Python3.6 (and other packaged dependencies), the script makes use of XeLaTeX and SaxonHE. Saxon is included in the vendor directory, but Java Runtime Environment on the system to run it. One might consider going over to the pysaxon module. You also need to have a installation of XeLaTeX.
The script has two main command tex
and pdf
, determining which type of output you want. If you want to use a local file, you should use the --local
flag and let the <file>
be the location of a local file, otherwise you can enable the --scta
flag and let the identifier be an id in the SCTA database.
To get a full overview of the options and possible commands, run lbp_print --help
. This will produce this usage guide:
Usage:
lbp_print (tex|pdf) [options] --local <file>...
lbp_print (tex|pdf) [options] --scta <id>...
lbp_print recipe <recipe> [options]
Pull LBP-compliant files from SCTA repositories or use local, convert them into
tex or pdf.
Arguments:
<file> File location of one or more objects to be processed.
<id> SCTA id of one or more objects to be processed.
Multiple arguments are separated with whitespace.
Commands:
tex Convert the xml to a tex-file.
pdf Convert the xml to a tex-file and compile it into a
pdf.
recipe <recipe> Follow recipe in config file in <recipe>.
Options:
--scta Flag. When present, the <id> should be an
expression id of the SCTA database.
--local Flag. When present, process local file indicated
by <file> argument.
--xslt <file> Use a custom xslt file in place of the default
supplied templates.
--output, -o <dir> Put results in the specified directory.
[default: .]
--cache-dir <dir> The directory where cached files should be stored.
--xslt-parameters <str> Command line parameters that will be
passed to the XSLT script. Unfortunately, this only
works with one parameter at the moment.
Example: --xslt-parameters "key=value"
--config-file <file> Location of a config file in json format.
[default: ~/.lbp_print.json]
-V, --verbosity <level> Set verbosity. Possibilities: silent, info, debug
[default: info].
-v, --version Show version and exit.
-h, --help Show this help message and exit.
Unless you specify an output directory with --output
, the script will put the resulting file in the current working directory. This means that if you are on the Desktop when calling the script from the command line, that is where the file will land after processing.
If you keep passing the same arguments to the script, for instance to your own custom xslt script, you might want to use a config file.
The config file is written in JSON format.
By default the script looks for at configuration file with the name ~/.lbp_print.json
, but if you pass another file path in the --config-file
argument, it will look in that location.
The default configuration file of the standard options looks like this:
{
"--output": ".",
"--config-file": "~/.lbp_print.json",
"--verbosity": "info"
}
The arguments must be the long form identical to the specification in the lbp_print --help
description. This means that options must have prepended --
, arguments wrapped in <>
and commands without any wrapping.
You can create full configuration files describing all relevant command line arguments for creating a specific result and pass that file along with the recipe
command.
For example, running this command:
lbp_print recipe ~/Desktop/lbp.json
Where the content of ~/Desktop/lbp.json
is
{
"--local": true,
"<file>": [
"~/Transcriptions/49-prooemium/da-49-prooemium.xml",
"~/Transcriptions/49-l1q1/da-49-l1q1.xml",
"~/Transcriptions/49-l3q15/da-49-l3q15.xml"
],
"--output": "~/Desktop/testing",
"--verbosity": "debug"
}
Is equivalent to running
lbp_print pdf --output ~/Desktop/testing --verbosity debug \
--local ~/Transcriptions/49-prooemium/da-49-prooemium.xml \
~/Transcriptions/49-l1q1/da-49-l1q1.xml \
~/Transcriptions/49-l3q15/da-49-l3q15.xml
Such recipes can be very useful when creating the same group of items with a specific configuration multiple times with good confidence that the configuration is stable.
The module includes a caching feature. It is disabled by default, but if you regularly process the same files (either from remote or local sources), this can save you a lot of waiting time.
When you configure a cache directory with the option --cache-dir
, all completed files will be stored there and reused whenever the you input an exactly identical file to be compiled with exactly the same xslt script.
It works as follows. Whenever an XML file is received, and the proper XSLT conversion script is identified, a unique hash value is computed based on the content of those two files. This means that as soon as one of those two files changes a completely new hash value is produced. Completed tex
and pdf
files are stored in the --cache-dir
(using the hash value and file extension as basename). Before any processing the script checks whether a file with the current hash value is present in the cache. If it finds something, it returns that to you and saves you the waiting time of compilation (especially tex
compilations can take annoyingly long time).
The caching system makes sure that only the most recent version of every file (based on resource id or file name) is stored to make sure it does not swell completely out of proportion. But this also means that the system will identify two files with the same filename (not full path, only the name of the file, such as Jandun, question 2.24.xml
) as the same and remove the previous of the two from the cache. This will therefore lead to redundant rebuilding and caching when you compile different files with the same basename.