Extra user actions can be processed on the latex file produced by the XSL stylesheets or on its temporary working files produced by the latex compilation.
For instance, in the documents I write the cover page must display the number of pages of the document, but written in full letters (e.g. 23 is written “twenty three”). The latex post process script is then helpfull, and in this particular case it patches the .aux file.
The post process script is called just before the last latex compilation, and takes one parameter, the latex file compiled by the tool.
The latex compilations done once the script is called depend on the return code of the script:
When the return code is 0, dblatex continues the compilation as many times as necessary.
When the return code is 1, no more compilation is done by dblatex. This case is useful if the script needs to control precisely the number of compilation to apply. It is up to the script to perform the expected compilations.
To do so, the script can retrieve in the LATEX environment
variable the actual compiler used by dblatex.
When the return code is another value, an error is raised to signal a failed post process script execution.
You can use a python plugin instead of a script by prefixing
the plugin name with the string "plugin:". When using a
plugin you must not put the python suffix in the plugin name. If the plugin
is in one of the Python system directories, or in the current directory where
you call dblatex, or in one of the directories of the
PYTHONPATH
environment variable, you don't need to specify a directory location.
Otherwise put the plugin directory path before the plugin name.
Here are several plugin call examples:
# The texpost.py module is in one of the python paths dblatex -r plugin:texpost file.xml # The texpost.py module location is specified with an absolute path dblatex -r plugin:/path/to/texpost file.xml # The texpost.py module is specified through a relative path from current dir dblatex -r plugin:relative/path/from/current/dir/texpost file.xml
The plugin must contain a main entry point. Dblatex will pass the following parameters to the entry point: latex_file to specify the latex file to post process, and stdout to specify the output stream to use to be consistent with the dblatex verbosity.
Example 4.4. Texpost Python Plugin Example
import sys
import os
def main(latex_file, stdout):
"""
Texpost Plugin Entry point
"""
# Let's find out the backend used
tex_engine = os.environ["LATEX"]
# Let's log something
print >>stdout, "Plugin called on '%s' file" % (latex_file)
# Open the latex file and parse it
texfile = open(latex_file)
...
# Now decide if a new compilation must occur
if has_changed:
sys.exit(0)
else:
sys.exit(1)