Latex post process script
Prev | Chapter 4. Customization | Next

## Latex post process script

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.

### Post latex compilations

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.

### Post processing with a Python Plugin

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)

Prev | Up | Next
Customized LaTeX style | Home | Dblatex Configuration File