docu updates

[PyX/mjg.git] / manual / text.tex

\chapter[Module \module{text}: TeX/LaTeX interface]{Module \module{text}: \TeX/\LaTeX{} interface}
\label{module:text}

\section{Basic functionality}

The \verb|text| module seamlessly integrates the famous typesetting
technique of \TeX/\LaTeX{} into \PyX. The basic procedure is:
\begin{itemize}
\item start a \TeX/\LaTeX{} instance as soon as a \TeX/\LaTeX{}
preamble setting or a text creation is requested
\item create boxes containing the requested text and shipout those
boxes to the dvi file
\item immediately analyse the \TeX/\LaTeX{} output for errors; the box
extents are also contained in the \TeX/\LaTeX{} output and thus become
available immediately
\item when your TeX installation supports the \verb|ipc| mode and
\PyX{} is configured to use it, the dvi output is also analysed
immediately; alternatively \PyX{} quits the \TeX/\LaTeX{} instance to
read the dvi output once PostScript needs to be written or markers are
accessed
\item Type1 fonts are used for the PostScript generation
\end{itemize}

Note that for using Type1 fonts an appropriate font mapping file has
to be provided. When your \TeX{} installation is configured to use
Type1 fonts by default, the \verb|psfonts.map| will contain entries
for the standard \TeX{} fonts already. Alternatively, you may either
look for updmap used by many \TeX{} installations to create an
appropriate font mapping file or you may specify some alternative
font mapping files like \verb|psfonts.cmz| in the \verb|pyxrc| or the
\verb|fontmaps| keyword argument of the \verb|texrunner| constructor
(or the \verb|set| method).

\section{The texrunner}
Instances of the class \verb|texrunner| represent a \TeX/\LaTeX{}
instance. The keyword arguments of the constructor are listed in the
following table:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
keyword&description\\
\hline
\texttt{mode}&\texttt{"tex"} (default) or \texttt{"latex"}\\
\texttt{lfs}&Specifies a latex font size file to be used with \TeX{} (not in \LaTeX). Those files (with the suffix \texttt{.lfs}) can be created by \texttt{createlfs.tex}. Possible values are listed when a requested name could not be found.\\
\texttt{docclass}&\LaTeX{} document class; default is \texttt{"article"}\\
\texttt{docopt}&specifies options for the document class; default is \texttt{None}\\
\texttt{usefiles}&access to \TeX/\LaTeX{} jobname files; default: \texttt{None}; example: \texttt{["spam.aux", "eggs.log"]}\\
\texttt{fontmaps}&whitespace separated names of font mapping files; default \texttt{"psfonts.map"}\\
\texttt{waitfortex}&wait this number of seconds for a \TeX/\LaTeX{} response; default \texttt{60}\\
\texttt{showwaitfortex}&show a message about waiting for \TeX/\LaTeX{} response on \texttt{strerr}; default \texttt{5}\\
\texttt{texipc}&use the \texttt{--ipc} option of \TeX/\LaTeX{} for immediate dvi-output access (boolean); check the output of \texttt{tex --help} if this option is available in your \TeX/\LaTeX{} installation; default \texttt{0}\\
\texttt{texdebug}&filename to store \TeX/\LaTeX{} commands; default \texttt{None}\\
\texttt{dvidebug}&dvi debug messages like \texttt{dvitype} (boolean); default \texttt{0}\\
\texttt{errordebug}&verbose level of \TeX/\LaTeX{} error messages; valid values are \texttt{0}, \texttt{1} (default), \texttt{2}\\
\texttt{pyxgraphics}&enables the usage of the graphics package without further configuration (boolean); default 1\\
\texttt{texmessagesstart}&parsers for the \TeX/\LaTeX{} start message; default: \texttt{[texmessage.start]}\\
\texttt{texmessagesdocclass}&parsers for \LaTeX{}s \texttt{\textbackslash{}documentclass} statement; default: \texttt{[texmessage.load]}\\
\texttt{texmessagesbegindoc}&parsers for \LaTeX{}s \texttt{\textbackslash{}begin\{document\}} statement; default: \texttt{[texmessage.load, texmessage.noaux]}\\
\texttt{texmessagesend}&parsers for \TeX{}s \texttt{\textbackslash{}end}/ \LaTeX{}s \texttt{\textbackslash{}end\{document\}} statement; default: \texttt{[texmessage.texend]}\\
\texttt{texmessagesdefaultpreamble}&default parsers for preamble statements; default: \texttt{[texmessage.load]}\\
\texttt{texmessagesdefaultrun}&default parsers for text statements; default: \texttt{[texmessage.loadfd, texmessage.graphicsload]}\\
\end{tabularx}
\medskip

The default values of the parameters \verb|fontmaps|, \verb|waitfortex|,
\verb|showwaitfortex|, and \verb|texipc| can be modified in the \verb|text|
section of a \verb|pyxrc|.

The \verb|texrunner| instance provides several methods to be called by
the user. First there is a method called \verb|set|. It takes the same
kewword arguments as the constructor and its purpose is to provide an
access to the \verb|texrunner| settings for a given instance. This is
important for the \verb|defaulttexrunner|. The \verb|set| method
fails, when a modification cannot be applied anymore (e.g.
\TeX/\LaTeX{} was already started).

The \verb|preamble| method can be called before the \verb|text| method
only (see below). It takes a \TeX/\LaTeX{} expression and optionally
a list of \TeX/\LaTeX{} message parsers. The preamble expressions should be
used to perform global settings, but should not create any \TeX/\LaTeX{} dvi
output. In \LaTeX, the preamble expressions are inserted before the
\verb|\begin{document}| statement. Note, that you can use
\verb|\AtBeginDocument{...}| to postpone the direct evaluation.

Finally there is a \verb|text| method. The first two parameters are
the \verb|x| and \verb|y| position of the output to be generated. The
third parameter is a \TeX/\LaTeX{} expression. There are two further
keyword arguments. The first, \verb|textattrs|, is a list of
\TeX/\LaTeX{} settings as described below, \PyX{} transformations, and
\PyX{} fill styles (like colors). The second keyword argument
\verb|texmessages| takes a list of \TeX/\LaTeX{} message parsers as
described below as well. The \verb|text| method returns a box (see
chapter~\ref{module:box}), which can be inserted into a canvas
instance by its \verb|insert| method to get the text.

The box returned by the \verb|text| method has an additional method
\verb|marker|. You can place markers in the \TeX/\LaTeX{} expression
by the command \verb|\PyXMarker{<string>}|. When calling the
\verb|marker| method with the same \verb|<string>| you can get back the
position of the marker later on. Only digits, letters and the \verb|@|
symbol are allowed within the string. Strings containing the \verb|@|
symbol are not considered for end users like it is done for commands
including the \verb|@| symbol in \LaTeX{}.

Note that for the generation of the PostScript code the \TeX/\LaTeX{}
instance must be terminated except when \verb|texipc| is turned on.
However, a \TeX/\LaTeX{} instance is started again when the
\verb|text| method is called again. A call of the \verb|preamble|
method will still fail, but you can explicitly call the \verb|reset|
method to allow for new \verb|preamble| settings as well. The
\verb|reset| method takes a boolean parameter \verb|reinit| which can
be set to run the old preamble settings.

\section[TeX/LaTeX attributes]{\TeX/\LaTeX{} attributes}

\begin{description}
\raggedright
\item[Horizontal alignment:] \verb|halign.left| (default),
\verb|halign.center|, \verb|halign.right|, \verb|halign(x)| (\verb|x|
is a value between \verb|0| and \verb|1| standing for left and right,
respectively)
\begin{figure}
\centerline{\includegraphics{textvalign}}
\caption{valign example}
\label{fig:textvalign}
\end{figure}
\item[Vertical alignment:] \verb|valign.top|, \verb|valign.middle|,
\verb|valign.bottom|, \verb|valign.baseline| (default); see the left
hand side of figure~\ref{fig:textvalign}
\item[Vertical box:] Usually, \TeX/\LaTeX{} expressions are handled in
horizontal mode (so-called LR-mode in \TeX/\LaTeX; everything goes
into a single line). You may use \verb|parbox(x)|, where \verb|x| is the
width of the text, to switch to a multiline mode (so-called vertical
mode in \TeX/\LaTeX). The additional keyword parameter \verb|baseline|
allows the user to alter the position of the baseline. It can be set
to \verb|parbox.top| (default), \verb|parbox.middle|,
\verb|parbox.bottom| (see the right hand side of
figure~\ref{fig:textvalign}). The baseline position is relevant when
the vertical alignment is set to baseline only.
\item[Vertical shift:] \verb|vshift(lowerratio, heightstr="0")|
(lowers the output by \verb|lowerratio| of the height of
\verb|heightstr|), \verb|vshift.bottomzero=vshift(0)| (doesn't have an
effect), \verb|vshift.middlezero=vshift(0.5)| (shifts down by half of
the height of \verb|0|), \verb|vshift.topzero=vshift(1)| (shifts down
by the height of \verb|0|), \verb|vshift.mathaxis| (shifts down by the
height of the mathematical axis)
\item[Mathmode:] \verb|mathmode| switches to mathmode of \TeX/\LaTeX{}
in \verb|\displaystyle| (\verb|nomathmode| removes this attribute)
\item[Font size:] \verb|size.tiny=size(-4)|,
\verb|size.scriptsize=size(-3)|, \verb|size.footnotesize=size(-2)|,
\verb|size.small=size(-1)|, \verb|size.normalsize=size(0)|,
(default), \verb|size.large=size(1)|, \verb|size.Large=size(2)|,
\verb|size.LARGE=size(3)|, \verb|size.huge=size(4)|,
\verb|size.Huge=size(5)|
\item[Phantom text:] \verb|phantom| creates an textbox with the proper
extents but without the text (\verb|nophantom| removes this attribute)
\end{description}

\section[Using the graphics-bundle with LaTeX]{Using the graphics-bundle with \LaTeX}

The packages in the \LaTeX-graphics bundle (color.sty, graphics.sty,
graphicx.sty, \ldots) make extensive use of \verb|\special| commands.
Here are some notes on this topic. Please install the appropriate
driver file \verb|pyx.def|, which defines all the specials, in your
\LaTeX-tree and add the content of both files \verb|color.cfg| and
\verb|graphics.cfg| to your personal configuration files.\footnote{If
you do not know what I am talking about right now -- just ignore this
paragraph, but make sure not to set the \texttt{pyxgraphics} keyword
to 0.} After you have installed the \verb|.cfg| files please use the
\verb|text| module always with the \verb|pyxgraphics| keyword set to
0, this switches off a hack that might be convenient for less
experienced \LaTeX-users.

You can then import the packages of the graphics-bundle and related
packages (e.g.~rotating, \ldots) with the option~\verb|pyx|,
e.g.~\verb|\usepackage[pyx]{color,graphicx}|. Please note that the
option~\verb|pyx| is only available with \verb|pyxgraphics=0| and a
properly installed driver file. Otherwise do not use this option, omit
it completely or say~\verb|[dvips]|.

When defining colours in \LaTeX{} as one of the colour models
\verb|gray|, \verb|cmyk|, \verb|rgb|, \verb|RGB|, \verb|hsb| then
\PyX{} will use the corresponding values (one to four real numbers)
for output. When you use one of the \verb|named| colors in \LaTeX{}
then \PyX{} will use the corresponding predefined colour (see module
\verb|color| and the colour table at the end of the manual).

When importing eps-graphics in \LaTeX{} then \PyX{} will rotate, scale
and clip your file like you expect it. Note that \PyX{} cannot import
other graphics files than \verb|eps| at the moment.

For reference purpose, the following specials can be handled by the
\verb|text| module at the moment:\medskip

\begingroup
\leftskip3em
\parindent-3em
\parskip0.5ex
\texttt{PyX:color\_begin (model) (spec)}\\
  starts a colour. (model)~is one of
  \{\verb|gray|, \verb|cmyk|, \verb|rgb|, \verb|hsb|, \verb|texnamed|\}.
  (spec)~depends on the model: a name or some numbers.\par
\texttt{PyX:color\_end} ends a colour.\par
\texttt{PyX:epsinclude file= llx= lly= urx= ury= width= height= clip=0/1}\\
  includes an eps-file. The values of llx to ury are in the files' coordinate
  system and specify the part of the graphics that should become the specified
  width and height in the outcome. The graphics may be clipped. The last three
  parameters are optional.\par
\texttt{PyX:scale\_begin (x) (y)}\\
  begins scaling from the current point.\par
\texttt{PyX:scale\_end} ends scaling.\par
\texttt{PyX:rotate\_begin (angle)} begins rotation around the current
  point.\par
\texttt{PyX:rotate\_end} ends rotation.\par
\endgroup


\section[TeX/LaTeX message parsers]{\TeX/\LaTeX{} message parsers}

Message parsers are used to scan the output of \TeX/\LaTeX. The output
is analysed by a sequence of message parsers. Each of them analyses
the output and removes those parts of the output, it feels responsible
for. If there is nothing left in the end, the message got validated,
otherwise an exception is raised reporting the problem.

\medskip
\begin{tabular}{ll}
parser name&purpose\\
\hline
\texttt{texmessage.load}&loading of files (accept \texttt{(file ...)})\\
\texttt{texmessage.loadfd}&loading of files (accept \texttt{(file.fd)})\\
\texttt{texmessage.graphicsload}&loading of graphic files (accept \texttt{<file.eps>})\\
\texttt{texmessage.ignore}&accept everything as a valid output\\
\end{tabular}
\medskip

More specialised message parsers should become available as required.
Please feel free to contribute (e.g. with ideas/problems; code is
desired as well, of course). There are further message parsers for
\PyX{}s internal use, but we skip them here as they are not
interesting from the users point of view.

\section{The defaulttexrunner instance}
The \verb|defaulttexrunner| is an instance of the class
\verb|texrunner|, which is automatically created by the \verb|text|
module. Additionally, the methods \verb|text|, \verb|preamble|, and
\verb|set| are available as module functions accessing the
\verb|defaulttexrunner|. This single \verb|texrunner| instance is
sufficient in most cases.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "manual.tex"
%%% End: