<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Latex post process script</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="DocBook to LaTeX Publishing" /><link rel="up" href="sec-custom.html" title="Chapter 4. Customization" /><link rel="prev" href="sec-custom-latex.html" title="Customized LaTeX style" /><link rel="next" href="sec-specs.html" title="Dblatex Configuration File" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Latex post process script</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sec-custom-latex.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Customization</th><td width="20%" align="right"> <a accesskey="n" href="sec-specs.html">Next</a></td></tr></table><hr /></div><div class="section" title="Latex post process script"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-texpost"></a>Latex post process script</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="sec-texpost.html#idm1787712">Post latex compilations</a></span></dt><dt><span class="section"><a href="sec-texpost.html#sec-texpost-py">Post processing with a Python Plugin</a></span></dt></dl></div><p>
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.
</p><p>
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.
</p><p>
The post process script is called just before the last latex compilation, and takes one parameter, the latex file compiled by the tool.
</p><div class="section" title="Post latex compilations"><div class="titlepage"><div><div><h3 class="title"><a id="idm1787712"></a>Post latex compilations</h3></div></div></div><p>
The latex compilations done once the script is called depend on the return code
of the script:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
When the return code is 0, <span class="command"><strong>dblatex</strong></span> continues the
compilation as many times as necessary.
</p></li><li class="listitem"><p>
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.</p><p>To do so, the script can retrieve in the <code class="envar">LATEX</code> environment
variable the actual compiler used by <span class="command"><strong>dblatex</strong></span>.
</p></li><li class="listitem"><p>
When the return code is another value, an error is raised to signal
a failed post process script execution.
</p></li></ul></div><p>
</p></div><div class="section" title="Post processing with a Python Plugin"><div class="titlepage"><div><div><h3 class="title"><a id="sec-texpost-py"></a>Post processing with a Python Plugin</h3></div></div></div><p>You can use a python plugin instead of a script by prefixing
the plugin name with the string <code class="literal">"plugin:"</code>. 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
<code class="envar">PYTHONPATH</code>
environment variable, you don't need to specify a directory location.
Otherwise put the plugin directory path before the plugin name.
</p><p>Here are several plugin call examples:
</p><pre class="programlisting"># 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
</pre><p>
</p><p>The plugin must contain a <code class="function">main</code> entry point. <span class="command"><strong>Dblatex</strong></span> will pass the following parameters to the entry point: <em class="parameter"><code>latex_file</code></em> to specify the latex file to post process, and <em class="parameter"><code>stdout</code></em> to specify the output stream to use to be consistent with the dblatex verbosity.</p><div class="example"><a id="idm1972608"></a><p class="title"><strong>Example 4.4. Texpost Python Plugin Example</strong></p><div class="example-contents"><pre class="programlisting">
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)
</pre></div></div><br class="example-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sec-custom-latex.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sec-custom.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sec-specs.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Customized LaTeX style </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Dblatex Configuration File</td></tr></table></div></body></html>