manual/text.tex

   1 \chapter{Module text: \TeX/\LaTeX{} interface}
   2 \label{text}
   3
   4 \section{Basic functionality}
   5
   6 The \verb|text| module seamlessly integrates the famous typesetting
   7 technique of \TeX/\LaTeX{} into \PyX. The basic procedure is:
   8 \begin{itemize}
   9 \item start \TeX/\LaTeX{} as soon as text creation is requested
  10 \item create boxes containing the requested text on the fly
  11 \item immediately analyze the \TeX/\LaTeX{} output for errors etc.
  12 \item boxes are written into the dvi output
  13 \item box extents are immediately available (they are contained in the
  14 \TeX/\LaTeX{} output)
  15 \item as soon as PostScript needs to be written, stop \TeX/\LaTeX{},
  16 analyse the dvi output and generate the requested PostScript
  17 \item use Type1 fonts for the PostScript generation
  18 \end{itemize}
  19
  20 \section{The texrunner}
  21 The class \verb|texrunner| represents a \TeX/\LaTeX{} instance. The
  22 keyword arguments of the constructor are listed in the following
  23 table:
  24
  25 \medskip
  26 \begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
  27 keyword&description\\
  28 \hline
  29 \texttt{mode}&\texttt{tex} (default) or \texttt{latex}\\
  30 \texttt{lfs}&Specifies a latex font size file to be used with \TeX. Those files with the suffix \texttt{.lfs} are created by \texttt{createlfs.tex}. Possible values are listed when a requested name couldn't be found.\\
  31 \texttt{docclass}&\LaTeX{} document class; default is \texttt{"article"}\\
  32 \texttt{docopt}&specifies options for the document class; default is \texttt{None}\\
  33 \texttt{usefiles}$^1$&filenames to be as jobname files for \TeX/\LaTeX{}; default: \texttt{None}\\
  34 \texttt{waitfortex}&wait this number of seconds for a \TeX/\LaTeX{} response; default \texttt{5}\\
  35 \texttt{texdebug}&\TeX/\LaTeX{} debug messages; default \texttt{0}\\
  36 \texttt{dvidebug}&dvi debug messages (like \texttt{dvitype}); default \texttt{0}\\
  37 \texttt{texmessagestart}$^{1,2}$&parsers for the \TeX/\LaTeX{} start message; default: \texttt{texmessage.start}\\
  38 \texttt{texmessagedocclass}$^{1,2}$&parsers for \LaTeX{}s \texttt{\textbackslash{}documentclass} statement; default: \texttt{texmessage.load}\\
  39 \texttt{texmessagebegindoc}$^{1,2}$&parsers for \LaTeX{}s \texttt{\textbackslash{}begin\{document\}} statement; default: \texttt{(texmessage.load, texmessage.noaux)}\\
  40 \texttt{texmessageend}$^{1,2}$&parsers for \TeX{}s \texttt{\textbackslash{}end}/ \LaTeX{}s \texttt{\textbackslash{}end\{document\}} statement; default: \texttt{texmessage.texend}\\
  41 \texttt{texmessagedefaultpreamble}$^{1,2}$&default parsers for preamble statements; default: \texttt{texmessage.load}\\
  42 \texttt{texmessagedefaultrun}$^{1,2}$&default parsers for text statements; default: \texttt{None}\\
  43 \end{tabularx}
  44 \medskip
  45
  46 $^1$
  47 The parameter might contain None, a single entry or a sequence of entries.
  48
  49 $^2$
  50 \TeX/\LaTeX{} message parsers are described in more detail below.
  51
  52 \medskip
  53 The \verb|texrunner| instance provides three methods to be called by
  54 the user. The first method is called \verb|set|. It takes the same
  55 kewword arguments as the constructor and its purpose is to provide an
  56 access to the \verb|texrunner|s settings for a given instance. This is
  57 important for the \verb|defaulttextunner|. The \verb|set| method
  58 fails, when a modification can't be applied anymore (e.g.
  59 \TeX/\LaTeX{} was already started).
  60
  61 Secondly there is a \verb|preamble| method. It takes a \TeX/\LaTeX{}
  62 expression and optionally one or several \TeX/\LaTeX{} message
  63 parsers. The preamlbe expressions should be used to perform global
  64 settings, but should not create any \TeX/\LaTeX{} dvi output. In
  65 \LaTeX, the preamble expressions are inserted before the
  66 \verb|\begin{document}| statement.
  67
  68 Last but first, there is a \verb|text| method. The first two
  69 parameters are the x, y position of the output to be generated. The
  70 third parameter is a \TeX/\LaTeX{} expression and further parameters
  71 are attributes for this command. Those attributes might be
  72 \TeX/\LaTeX{} settings as described below, \TeX/\LaTeX{} message
  73 parsers as described below as well, \PyX{} transformations (like
  74 rotations), and \PyX{} fill styles (like colors).
  75
  76 \section{\TeX/\LaTeX{} settings}
  77
  78 \section{\TeX/\LaTeX{} message parsers}
  79
  80 \section{The defaulttexrunner instance}
  81 The \verb|defaulttexrunner| is an instance of the class
  82 \verb|texrunner|, which is automatically created by the \verb|text|
  83 module. Additionally, the methods \verb|text|, \verb|preamble|, and
  84 \verb|set| are available as module functions. Usually, this single
  85 \verb|texrunner| instance is sufficient.
  86