3.2 TEX/L^ATEX instances: the `texrunner` class

Instances of the class texrunner are responsible for executing and controling a TEX/L^ATEX instance.

class texrunner( mode="tex", lfs="10pt", docclass="article", docopt=None, usefiles=[], fontmaps=config.get("text", "fontmaps", "psfonts.map"), waitfortex=config.getint("text", "waitfortex", 60), showwaitfortex=config.getint("text", "showwaitfortex", 5), texipc=config.getboolean("text", "texipc", 0), texdebug=None, dvidebug=0, errordebug=1, pyxgraphics=1, texmessagesstart=[], texmessagesdocclass=[], texmessagesbegindoc=[], texmessagesend=[], texmessagesdefaultpreamble=[], texmessagesdefaultrun=[])

mode should the string "tex" or "latex" and defines whether TEX or L^ATEX will be used. lfs specifies an lfs file to simulate L^ATEX font size selection macros in plain TEX. PyX comes with a set of lfs files and a L^ATEX script to generate those files. For lfs being None and mode equals "tex" a list of installed lfs files is shown.

docclass is the document class to be used in L^ATEX mode and docopt are the options to be passed to the document class.

usefiles is a list of TEX/L^ATEX jobname files. PyX will take care of the creation and storing of the corresponding temporary files. A typical use-case would be usefiles=["spam.aux"], but you can also use it to access TEXs log and dvi file.

fontmaps is a string containing whitespace separated names of font mapping files. waitfortex is a number of seconds PyX should wait for TEX/L^ATEX to process a request. While waiting for TEX/L^ATEX a PyX process might seem to do not perform any work anymore. To give some feedback to the user, a messages is issued each waitfortex seconds. The texipc flag indicates whether PyX should use the -ipc option of TEX/L^ATEX for immediate dvi file access to increase the execution speed of certain operations. See the output of tex -help whether the option is available at your TEX installation.

texdebug can be set to a filename to store the commands passed to TEX/L^ATEX for debugging. The flag dvidebug enables debugging output in the dvi parser similar to dvitype. errordebug controls the amount of information returned, when an texmessage parser raises an error. Valid values are 0, 1, and 2.

pyxgraphics allows use L^ATEXs graphics package without further configuration of pyx.def.

The TEX message parsers verify whether TEX/L^ATEX could properly process its input. By the parameters texmessagesstart, texmessagesdocclass, texmessagesbegindoc, and texmessagesend you can set TEX message parsers to be used then TEX/L^ATEX is started, when the documentclass command is issued (L^ATEX only), when the \begin{document} is sent, and when the TEX/L^ATEX is stopped, respectively. The lists of TEX message parsers are merged with the following defaults: [texmessage.start] for texmessagesstart, [texmessage.load] for texmessagesdocclass, [texmessage.load, texmessage.noaux] for texmessagesbegindoc, and [texmessage.texend, texmessage.fontwarning] for texmessagesend.

Similarily texmessagesdefaultpreamble and texmessagesdefaultrun take TEX message parser to be merged to the TEX message parsers given in the preamble() and text() methods. The texmessagesdefaultpreamble and texmessagesdefaultrun are merged with [texmessage.load] and [texmessage.loaddef, texmessage.graphicsload, texmessage.fontwarning, texmessage.boxwarning], respectively.

texrunner instances provides several methods to be called by the user:

set( **kwargs): This method takes the same keyword arguments as the texrunner constructor. Its purpose is to reconfigure an already constructed texrunner instance. The most prominent use-case is to alter the configuration of the default texrunner instance defaulttexrunner which is created at the time of loading of the text module.
The set method fails, when a modification cannot be applied anymore (e.g. TEX/L^ATEX has already been started).

preamble( expr, texmessages=[]): The preamble() can be called prior to the text() method only or after reseting a texrunner instance by reset(). The expr is passed to the TEX/L^ATEX instance not encapsulated in a group. It should not generate any output to the dvi file. In L^ATEX preamble expressions are inserted prior to the \begin{document} and a typical use-case is to load packages by \usepackage. Note, that you may use \AtBeginDocument to postpone the immediate evaluation.
texmessages are TEX message parsers to handle the output of TEX/L^ATEX. They are merged with the default TEX message parsers for the preamble() method. See the constructur description for details on the default TEX message parsers.

text( x, y, expr, textattrs=[], texmessages=[])

x and y are the position where a text should be typeset and expr is the TEX/L^ATEX expression to be passed to TEX/L^ATEX.

textattrs is a list of TEX/L^ATEX settings as described below, PyX transformations, and PyX fill styles (like colors).

texmessages are TEX message parsers to handle the output of TEX/L^ATEX. They are merged with the default TEX message parsers for the text() method. See the constructur description for details on the default TEX message parsers.

The text() method returns a textbox instance, which is a special canvas instance. It has the methods width(), height(), and depth() to access the size of the text. Additionally the marker() method, which takes a string s, returns a position in the text, where the expression \PyXMarker{s} is contained in expr. You should not use @ within your strings s to prevent prevent name clashes with PyX internal macros (although we don't the marker feature internally right now).

Note that for the outout generation and the marker access the TEX/L^ATEX instance must be terminated except when texipc is turned on. However, after such a termination a new TEX/L^ATEX instance is started when the text() method is called again.

reset( reinit=0): This method can be used to manually force a restart of TEX/L^ATEX. The flag reinit will initialize the TEX/L^ATEX by repeating the preamble() calls. New set() and preamble() calls are allowed when reinit was not set only.

3.2 TEX/LATEX instances: the texrunner class

3.2 TEX/L^ATEX instances: the `texrunner` class