manual/text.tex

   1 \chapter{Module text: \TeX/\LaTeX{} interface}
   2 \label{module: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 Instances of the class \verb|texrunner| represent a \TeX/\LaTeX{}
  22 instance. The keyword arguments of the constructor are listed in the
  23 following 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). The \verb|text|
  75 method returns a box (see chapter~\ref{module:box}), which can be inserted
  76 into a canvas instance by its \verb|insert| method to get the text.
  77
  78 \section{\TeX/\LaTeX{} settings}
  79
  80 \begin{description}
  81 \raggedright
  82 \item[Horizontal alignment:] \verb|halign.left| (default),
  83 \verb|halign.center|, \verb|halign.right|, \verb|halign(x)| (\verb|x|
  84 is a value between \verb|0| and \verb|1|)
  85 \item[Vertical box:] Usually, \TeX/\LaTeX{} expressions are handled in
  86 horizontal mode (its called LR-mode in \TeX/\LaTeX; everything goes
  87 into a single line). You may use \verb|vbox(x)|, where \verb|x| is the
  88 width of the text, to switch to a multiline mode (its called vertical
  89 mode in \TeX/\LaTeX).
  90 \begin{figure}
  91 \centerline{\includegraphics{textvalign}}
  92 \caption{valign example}
  93 \label{fig:textvalign}
  94 \end{figure}
  95 \item[Vertical alignment:] \verb|valign.top|, \verb|valign.middle|,
  96 \verb|valign.bottom|; in horizontal mode additionally
  97 \verb|valign.baseline| (default); in vertical mode additionally
  98 \verb|valign.topbaseline| (default), \verb|valign.middlebaseline|, and
  99 \verb|valign.bottombaseline|; see figure~\ref{fig:textvalign} for an
 100 example
 101 \item[Vertical shift:] \verb|vshift.char(lowerratio, heightstr="0")|
 102 (lowers the output by \verb|lowerratio| of the height of
 103 \verb|heightstr|), \verb|vshift.bottomzero=vshift.char(0)| (doesn't
 104 have an effect), \verb|vshift.middlezero=vshift.char(0.5)| (shifts
 105 down by halve of the height of a \verb|0|),
 106 \verb|vshift.topzero=vshift.char(1)| (shifts down by the height of the a
 107 \verb|0|), vshift.mathaxis (shifts down by the height of the
 108 mathematical axis)
 109 \item[Mathmode:] \verb|mathmode| switches the mathmode of \TeX/\LaTeX
 110 \item[Font size:] \verb|size.tiny|, \verb|size.scriptsize|,
 111 \verb|size.footnotesize|, \verb|size.small|, \verb|size.normalsize|
 112 (default), \verb|size.large|, \verb|size.Large|, \verb|size.LARGE|,
 113 \verb|size.huge|, \verb|size.Huge|
 114 \end{description}
 115
 116 \section{\TeX/\LaTeX{} message parsers}
 117
 118 Message parsers are used to scan the output of \TeX/\LaTeX. The output
 119 is analyzed by a sequence of message parsers. Each of them do analyze
 120 the output and remove those parts of the output, they feal responsible
 121 for. If there is nothing left in the end, the message got validated,
 122 otherwise an exception is raised reporting the problem.
 123
 124 \medskip
 125 \begin{tabular}{ll}
 126 parser name&purpose\\
 127 \hline
 128 \texttt{texmessage.load}&loading of files (accept \texttt{(file ...)})\\
 129 \texttt{texmessage.graphicsload}&loading of graphic files (accept \texttt{<file ...>})\\
 130 \texttt{texmessage.ignore}&accept everything as a valid output\\
 131 \end{tabular}
 132 \medskip
 133
 134 More specialized message parsers should become available as required.
 135 Please feal free to contribute (e.g. with ideas/problems; code is
 136 desired as well, of course). There are further message parsers for
 137 \PyX{}s internal use, but we skip them here as they are not
 138 interesting from the users point of view.
 139
 140 \section{The defaulttexrunner instance}
 141 The \verb|defaulttexrunner| is an instance of the class
 142 \verb|texrunner|, which is automatically created by the \verb|text|
 143 module. Additionally, the methods \verb|text|, \verb|preamble|, and
 144 \verb|set| are available as module functions accessing the
 145 \verb|defaulttexrunner|. This single \verb|texrunner| instance is
 146 sufficient in most cases.
 147