make all parts of the manual compile again; parts of the manual are still out of...

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

\chapter{Module tex: \TeX/\LaTeX{} interface (obsolete)}
\label{tex}
\section*{Please note: THIS MODULE IS OBSOLETE. Consider the \texttt{text} module instead.}

\section{Methods}
Text in \PyX{} is created by \TeX{} or \LaTeX. From the technical point
of view, the text is inserted as an Encapsulated PostScript file
(\verb|eps|-file). This \verb|eps|-file is generated by the module
\verb|tex| which runs \TeX{} or \LaTeX{} followed by \verb|dvips| to
create the requested text. \TeX{} is used by instances of the class
\verb|tex| while \LaTeX{} is used by \verb|latex|. Up to the
constructor and the advanced possibilities in \LaTeX{} commands both
classes \verb|tex| and \verb|latex| are identical. They provide 5
methods to the user listed in the following table:

\smallskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
method&task&allowed attributes in \texttt{*attr}\\
\hline
\texttt{text(x, y, cmd, *attr)}&print \texttt{cmd}&\texttt{style, fontsize, halign, valign, direction, color, msghandler(s)}\\
\texttt{define(cmd, *attr)}&execute \texttt{cmd}&\texttt{msghandler(s)}\\
\texttt{textwd(cmd, *attr)}&width of \texttt{cmd}&\texttt{style, fontsize, missextents, msghandler(s)}\\
\texttt{textht(cmd, *attr)}&height of \texttt{cmd}&\texttt{style, fontsize, valign, missextents, msghandler(s)}\\
\texttt{textdp(cmd, *attr)}&depth of \texttt{cmd}&\texttt{style, fontsize, valign, missextents, msghandler(s)}\\
\end{tabularx}
\smallskip

There are some common rules:
\begin{itemize}
\item \verb|cmd| stands for a \TeX{} or \LaTeX{} expression. To
prevent a backslash plague, python's raw string feature can nicely be
used. \verb|x|, \verb|y| specify a position.
\item \verb|define| can only be called before any of the other
methods. In \LaTeX{} definitions are inserted directly in front of
the \verb|\begin{document}| statement. However, this is not a
limitation, because by \verb|\AtBeginDocument{}| definitions can be
postponed.
\item The extent routines \verb|textwd|, \verb|textht|, and
\verb|textdp| return true \PyX{} length (see section~\ref{unit}).
Usually, the evaluation takes place when performing a write and the
results are stored in a file with the suffix \verb|.size|. Therefore
you have to run your file twice at first to get the correct value.
This default behaviour can be changed by the \verb|missextents|
attribute.
\item All commands are passed to \TeX{} or \LaTeX{} in the calling
order of the methods with one exception: if the same command is used
several times (for printing as well as for calculating extents), all
requests are executed at the position of the first occurrence of the
command.
\item All text is inserted into the \verb|canvas| at the position,
where the \verb|tex|- or \verb|latex|-instance itself is inserted into
the \verb|canvas|. In fact, the \verb|eps|-file created by \TeX{} or
\LaTeX{} and \verb|dvips| is just inserted.
\item The tailing \verb|*style| parameter stands for a list of
attribute parameters listed in the last column of the table. Attribute
parameters are instances of classes discussed in detail in the
following section.
\item There can be several \verb|msghandler| attributes which will be
applied sequentially. All other parameters can occure only once.
\end{itemize}


\section{Attributes}
\begin{description}
\item[\texttt{style:}] \verb|style.text| (default -- does nothing to
the command),\\\verb|style.math| (switches to math mode in
\verb|\displaystyle|)
\item[\texttt{fontsize:}] specifies the \LaTeX{} font sizes by
\verb|fontsize.xxx| where \verb|xxx| is one of
\verb|tiny|,
\verb|scriptsize|,
\verb|footnotesize|,
\verb|small|,
\verb|normalsize| (default),
\verb|large|,
\verb|Large|,
\verb|LARGE|,
\verb|huge|, or
\verb|Huge|.
\item[\texttt{halign:}] \verb|halign.left| (default),
\verb|halign.center|, \verb|halign.right|
\item[\texttt{valign:}] \verb|valign.top(length)| or
\verb|valign.bottom(length)| --- creates a vertical box with width
\verb|length|. The vertical alignment is the baseline of the first line
for \verb|top| and the last line for \verb|bottom|. The box width is
stored in the \TeX{} dimension \verb|\linewidth|.
\item[\texttt{direction:}] \verb|direction.xxx| where \verb|xxx|
stands for \verb|horizontal| (default), \verb|vertical|,
\verb|upsidedown|, or \verb|rvertical|. Additionally, any angle
\verb|angle| (in degree) is allowed in \verb|direction(angle)|.
\item[\texttt{color:}] stands for any \PyX{} color (see
section~\ref{color}), default is \verb|color.gray.black|
\item[\texttt{missextents:}] provides a routine, which is called when a
requested extent is not yet available. In the following table a list
of choises for this parameter is described:

\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
missextents&description\\
\hline
\texttt{missextents.returnzero}&returns zero (default)\\
\texttt{missextents.returnzeroquiet}&as above, but does not return a
warning via \texttt{atexit}\\
\texttt{missextents.raiseerror}&raise \texttt{TexMissExtentError}\\
\texttt{missextents.createextent}&run \TeX{} or \LaTeX{} immediately to
get the requested size\\
\texttt{missextents.createallextent}&run \TeX{} or \LaTeX{} immediately
to get the hight, width, and depth of the given text at once\\
\end{tabularx}
\item[\texttt{msghandler:}] provides a filter for \TeX{} and \LaTeX{}
messages and defines, which messages are hidden. In the following table
the predefined message handlers are described:

\smallskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
msghandler&description\\
\hline
\texttt{msghandler.showall}&shows all messages\\
\texttt{msghandler.hideload}&Hides messages which are written when loading
packages and including other files. They look like \texttt{(file...)}
where \texttt{file} is a readable file and \texttt{...} stands for any
text. This message handler is the default handler.\\
\texttt{msghandler.hidegraphicsload}&Hides messages which are written by
\texttt{includegraphics} of the \texttt{graphicx} package. They look like
\texttt{<file>} where \texttt{file} is a readable file.\\
\texttt{msghandler.hidefontwarning}&Hides \LaTeX{} font warnings. They
look like \texttt{LaTeX Font Warning:} and are followed by lines starting
with \texttt{(Font)}.\\
\texttt{msghandler.hidebuterror}&Hides messages except those
with a line which starts with ``\texttt{! }''.\\
\texttt{msghandler.hideall}&hides all messages\\
\end{tabularx}
\end{description}


\section{Constructors}
Named parameters of the constructor are used to set global options for
the instances of the classes \verb|tex| and \verb|latex|.
There are some common options for both classes listed in the following
table.

\smallskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
parameter name&default value&description\\
\hline
\texttt{defaultmsghandler}&\texttt{msghandler.hideload}&default
message handler (tuple of message handlers is possible)\\
\texttt{defaultmissextents}&\texttt{missextents.returnzero}&default missing extent handler\\
\texttt{texfilename}&\texttt{None}&Filename used for running \TeX{} or
\LaTeX. If \texttt{None}, a temporary name is used and the files are
removed automatically. It can be used to trace errors.\\
\end{tabularx}
\smallskip

Additionally, the class \verb|tex| has another option described in
the following table.

\smallskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
parameter name&default value&description\\
\hline
\texttt{lts}&\texttt{"10pt"}&Specifies a latex font size file. Those
files with the suffix \texttt{.lfs} can be created by
\texttt{createlfs.tex}. Possible values are listed when a requested
name couldn't be found.\\
\end{tabularx}
\smallskip

Instead of the option listed in the table above, for the class
\verb|latex| the options described in the following table are
available (additionally to the common available options).

\smallskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
parameter name&default value&description\\
\hline
\texttt{docclass}&\texttt{"article"}&specifies the document class\\
\texttt{docopt}&\texttt{None}&specifies options to the document class\\
\texttt{auxfilename}&\texttt{None}&Specifies a filename for storing the \LaTeX{}
\texttt{aux} file. This is needed when using labels and references.\\
\end{tabularx}

\section{Examples}
\subsection{Example 1}
\begin{quote}
\begin{verbatim}
from pyx import *

c = canvas.canvas()
t = c.insert(tex.tex())

t.text(0, 0, "Hello, world!")

print "width:", t.textwd("Hello, world!")
print "height:", t.textht("Hello, world!")
print "depth:", t.textdp("Hello, world!")

c.writetofile("tex1")
\end{verbatim}
\end{quote}

The output of this program is:
\begin{quote}
\begin{verbatim}
width: (0.019535 t + 0.000000 u + 0.000000 v + 0.000000 w) m
height: (0.002441 t + 0.000000 u + 0.000000 v + 0.000000 w) m
depth: (0.000683 t + 0.000000 u + 0.000000 v + 0.000000 w) m
\end{verbatim}
\end{quote}

The file \verb|tex1.eps| is created and looks like:
\begin{quote}
\includegraphics{tex1}
\end{quote}

\subsection{Example 2}
\begin{quote}
\begin{verbatim}
from pyx import *

c = canvas.canvas()
t = c.insert(tex.tex())

t.text(0, 0, "Hello, world!")
t.text(0, -0.5, "Hello, world!", tex.fontsize.large)
t.text(0, -1.5,
       r"\sum_{n=1}^{\infty} {1\over{n^2}} = {{\pi^2}\over 6}",
       tex.style.math)
c.stroke(path.line(5, -0.5, 9, -0.5))
c.stroke(path.line(5, -1, 9, -1))
c.stroke(path.line(5, -1.5, 9, -1.5))
c.stroke(path.line(7, -1.5, 7, 0))

t.text(7, -0.5, "left aligned") # default is tex.halign.left
t.text(7, -1, "center aligned", tex.halign.center)
t.text(7, -1.5, "right aligned", tex.halign.right)

c.stroke(path.line(0, -4, 2, -4))
c.stroke(path.line(0, -2.5, 0, -5.5))
c.stroke(path.line(2, -2.5, 2, -5.5))

t.text(0, -4,
       "a b c d e f g h i j k l m n o p q r s t u v w x y z",
       tex.valign.top(2))

c.stroke(path.line(2.5, -4, 4.5, -4))
c.stroke(path.line(2.5, -2.5, 2.5, -5.5))
c.stroke(path.line(4.5, -2.5, 4.5, -5.5))

t.text(2.5, -4,
       "a b c d e f g h i j k l m n o p q r s t u v w x y z",
       tex.valign.bottom(2))

c.stroke(path.line(5, -4, 9, -4))
c.stroke(path.line(7, -5.5, 7, -2.5))

t.text(7, -4, "horizontal")
t.text(7, -4, "vertical", tex.direction.vertical)
t.text(7, -4, "rvertical", tex.direction.rvertical)
t.text(7, -4, "upsidedown", tex.direction.upsidedown)

t.text(7.5, -3.5, "45", tex.direction(45))
t.text(6.5, -3.5, "135", tex.direction(135))
t.text(6.5, -4.5, "225", tex.direction(225))
t.text(7.5, -4.5, "315", tex.direction(315))

t.text(0, -6, "red", color.rgb.red)
t.text(3, -6, "green", color.rgb.green)
t.text(6, -6, "blue", color.rgb.blue)

c.writetofile("tex2")
\end{verbatim}
\end{quote}

The file \verb|tex2.eps| is created and looks like:
\begin{quote}
\includegraphics{tex2}
\end{quote}

\section{Known bugs}
\begin{itemize}
\item The end of the last paragraph in a vertical box
(\verb|valign.top| and \verb|valign.bottom|) must be explictly
written (by the command \verb|\par| or an empty line) when a paragraph
formating parameter is changed locally (like the \verb|\baselineskip|
when changing the font size).  Otherwise, the information is thrown
away due to a closing of the block before the paragraph formatting is
performed.
\item Due to \verb|dvips| the bounding box is wrong for rotated text.
The rotation is just ignored in the bounding box calculation.
\item Analysing \TeX{} messages is a difficult subject and the message
handlers provided with \PyX{} are not at all perfect in that sense.
For the message handlers \verb|msghandler.hideload| and
\verb|msghandler.hidegraphicsload| it is known, that they do not
correctly handle long filenames splited on several lines by \TeX.
\end{itemize}

\section{Future of the module tex}
While we will certainly keep this module working at least for a while,
it is likely that another \TeX{} interface will occure soon. The idea
is to get rid of \verb|dvips| and integrate \TeX{} more directly into
\PyX. The replacement module called \verb|text| becomes available for
the first time in \PyX{} 0.3.