1 \chapter{Module text:
\TeX/
\LaTeX{} interface
}
4 \section{Basic functionality
}
6 The
\verb|text| module seamlessly integrates the famous typesetting
7 technique of
\TeX/
\LaTeX{} into
\PyX. The basic procedure is:
9 \item start a
\TeX/
\LaTeX{} instance as soon as an
\TeX/
\LaTeX{}
10 preamble setting or a text creation is requested
11 \item create boxes containing the requested text and shipout those
13 \item immediately analyse the
\TeX/
\LaTeX{} output for errors; the box
14 extents are also contained in the
\TeX/
\LaTeX{} output and thus become
16 \item when your TeX installation supports the
\verb|ipc| mode and
17 \PyX{} is configured to use it, the dvi output is also analysed
18 immediately; alternatively
\PyX{} quits the
\TeX/
\LaTeX{} instance to
19 read the dvi output once PostScript needs to be written or markers are
21 \item Type1 fonts are used for the PostScript generation
24 Note that for using Type1 fonts an appropriate font mapping file has
25 to be provided. When your
\TeX{} installation is configured to use
26 Type1 fonts by default, the
\verb|psfonts.map| will contain entries
27 for the standard
\TeX{} fonts already. Alternatively, you may either
28 look for updmap used by many
\TeX{} installations to create an
29 appropriate font mapping file or you may specify some alternative
30 font mapping files like
\verb|psfonts.cmz| in the
\verb|pyxrc| or the
31 \verb|fontmaps| keyword argument of the
\verb|texrunner| constructor
32 (or the
\verb|set| method).
34 \section{The texrunner
}
35 Instances of the class
\verb|texrunner| represent a
\TeX/
\LaTeX{}
36 instance. The keyword arguments of the constructor are listed in the
40 \begin{tabularx
}{\linewidth}{l>
{\raggedright\arraybackslash}X
}
43 \texttt{mode
}&
\texttt{"tex"
} (default) or
\texttt{"latex"
}\\
44 \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.\\
45 \texttt{docclass
}&
\LaTeX{} document class; default is
\texttt{"article"
}\\
46 \texttt{docopt
}&specifies options for the
document class; default is
\texttt{None
}\\
47 \texttt{usefiles
}&access to
\TeX/
\LaTeX{} jobname files; default:
\texttt{None
}; example:
\texttt{["spam.aux", "eggs.log"
]}\\
48 \texttt{fontmaps
}&whitespace separated names of font mapping files; default
\texttt{"psfonts.map"
}\\
49 \texttt{waitfortex
}&wait this number of seconds for a
\TeX/
\LaTeX{} response; default
\texttt{60}\\
50 \texttt{showwaitfortex
}&show a message about waiting for
\TeX/
\LaTeX{} response on
\texttt{strerr
}; default
\texttt{5}\\
51 \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}\\
52 \texttt{texdebug
}&filename to store
\TeX/
\LaTeX{} commands; default
\texttt{None
}\\
53 \texttt{dvidebug
}&dvi debug messages like
\texttt{dvitype
} (boolean); default
\texttt{0}\\
54 \texttt{errordebug
}&verbose level of
\TeX/
\LaTeX{} error messages; valid values are
\texttt{0},
\texttt{1} (default),
\texttt{2}\\
55 \texttt{pyxgraphics
}&enables the usage of the graphics package without further configuration (boolean); default
1\\
56 \texttt{texmessagesstart
}&parsers for the
\TeX/
\LaTeX{} start message; default:
\texttt{[texmessage.start
]}\\
57 \texttt{texmessagesdocclass
}&parsers for
\LaTeX{}s
\texttt{\textbackslash{}documentclass
} statement; default:
\texttt{[texmessage.load
]}\\
58 \texttt{texmessagesbegindoc
}&parsers for
\LaTeX{}s
\texttt{\textbackslash{}begin\
{document\
}} statement; default:
\texttt{[texmessage.load, texmessage.noaux
]}\\
59 \texttt{texmessagesend
}&parsers for
\TeX{}s
\texttt{\textbackslash{}end
}/
\LaTeX{}s
\texttt{\textbackslash{}end\
{document\
}} statement; default:
\texttt{[texmessage.texend
]}\\
60 \texttt{texmessagesdefaultpreamble
}&default parsers for preamble statements; default:
\texttt{[texmessage.load
]}\\
61 \texttt{texmessagesdefaultrun
}&default parsers for text statements; default:
\texttt{[texmessage.loadfd, texmessage.graphicsload
]}\\
65 The default values of the parameters
\verb|fontmaps|,
\verb|waitfortex|,
66 \verb|showwaitfortex|, and
\verb|texipc| can be modified in the
\verb|text|
67 section of a
\verb|pyxrc|.
69 The
\verb|texrunner| instance provides several methods to be called by
70 the user. First there is a method called
\verb|set|. It takes the same
71 kewword arguments as the constructor and its purpose is to provide an
72 access to the
\verb|texrunner| settings for a given instance. This is
73 important for the
\verb|defaulttextunner|. The
\verb|set| method
74 fails, when a modification can't be applied anymore (e.g.
75 \TeX/
\LaTeX{} was already started).
77 The
\verb|preamble| method can be called before the
\verb|text| method
78 only (see below). It takes a
\TeX/
\LaTeX{} expression and optionally
79 a list of
\TeX/
\LaTeX{} message parsers. The preamble expressions should be
80 used to perform global settings, but should not create any
\TeX/
\LaTeX{} dvi
81 output. In
\LaTeX, the preamble expressions are inserted before the
82 \verb|
\begin{document}| statement. Note, that you can use
83 \verb|
\AtBeginDocument{...
}| to postpone the direct evaluation.
85 Finally there is a
\verb|text| method. The first two parameters are
86 the
\verb|x| and
\verb|y| position of the output to be generated. The
87 third parameter is a
\TeX/
\LaTeX{} expression. There are two further
88 keyword arguments. The first,
\verb|textattrs|, is a list of
89 \TeX/
\LaTeX{} settings as described below,
\PyX{} transformations, and
90 \PyX{} fill styles (like colors). The second keyword argument
91 \verb|texmessages| takes a list of
\TeX/
\LaTeX{} message parsers as
92 described below as well. The
\verb|text| method returns a box (see
93 chapter~
\ref{module:box
}), which can be inserted into a canvas
94 instance by its
\verb|insert| method to get the text.
96 The box returned by the
\verb|text| method has an additional method
97 \verb|marker|. You can place markers in the
\TeX/
\LaTeX{} expression
98 by the command
\verb|
\PyXMarker{<string>
}|. When calling the
99 \verb|marker| method with the same
\verb|<string>| you can get back the
100 position of the marker later on. Only digits, letters and the
\verb|@|
101 symbol are allowed within the string. Strings containing the
\verb|@|
102 symbol are not considered for end users like it is done for commands
103 including the
\verb|@| symbol in
\LaTeX{}.
105 Note that for the generation of the PostScript code the
\TeX/
\LaTeX{}
106 instance must be terminated except when
\verb|texipc| is turned on.
107 However, a
\TeX/
\LaTeX{} instance is started again when the
108 \verb|text| method is called again. A call of the
\verb|preamble|
109 method will still fail, but you can explicitly call the
\verb|reset|
110 method to allow for new
\verb|preamble| settings as well. The
111 \verb|reset| method takes a boolean parameter
\verb|reinit| which can
112 be set to run the old preamble settings.
114 \section{\TeX/
\LaTeX{} attributes
}
118 \item[Horizontal alignment:
] \verb|halign.left| (default),
119 \verb|halign.center|,
\verb|halign.right|,
\verb|halign(x)| (
\verb|x|
120 is a value between
\verb|
0| and
\verb|
1| standing for left and right,
123 \centerline{\includegraphics{textvalign
}}
124 \caption{valign example
}
125 \label{fig:textvalign
}
127 \item[Vertical box:
] Usually,
\TeX/
\LaTeX{} expressions are handled in
128 horizontal mode (so-called LR-mode in
\TeX/
\LaTeX; everything goes
129 into a single line). You may use
\verb|parbox(x)|, where
\verb|x| is the
130 width of the text, to switch to a multiline mode (so-called vertical
131 mode in
\TeX/
\LaTeX). The additional keyword parameter
\verb|baseline|
132 can be set to
\verb|parbox.top| (default),
\verb|parbox.middle|,
133 \verb|parbox.bottom| to alter the position of the baseline; see
134 figure~
\ref{fig:textvalign
} for an example
135 \item[Vertical alignment:
] \verb|valign.top|,
\verb|valign.middle|,
136 \verb|valign.bottom|,
\verb|valign.baseline| (default); see
137 figure~
\ref{fig:textvalign
} for an example
138 \item[Vertical shift:
] \verb|vshift(lowerratio, heightstr="
0")|
139 (lowers the output by
\verb|lowerratio| of the height of
140 \verb|heightstr|),
\verb|vshift.bottomzero=vshift(
0)| (doesn't have an
141 effect),
\verb|vshift.middlezero=vshift(
0.5)| (shifts down by half of
142 the height of
\verb|
0|),
\verb|vshift.topzero=vshift(
1)| (shifts down
143 by the height of
\verb|
0|),
\verb|vshift.mathaxis| (shifts down by the
144 height of the mathematical axis)
145 \item[Mathmode:
] \verb|mathmode| switches to mathmode of
\TeX/
\LaTeX{}
146 in
\verb|
\displaystyle| (
\verb|nomathmode| removes this attribute)
147 \item[Font size:
] \verb|size.tiny=size(-
4)|,
148 \verb|size.scriptsize=size(-
3)|,
\verb|size.footnotesize=size(-
2)|,
149 \verb|size.small=size(-
1)|,
\verb|size.normalsize=size(
0)|,
150 (default),
\verb|size.large=size(
1)|,
\verb|size.Large=size(
2)|,
151 \verb|size.LARGE=size(
3)|,
\verb|size.huge=size(
4)|,
152 \verb|size.Huge=size(
5)|
155 \section{Using the graphics-bundle with
\LaTeX}
157 The packages in
\LaTeX-graphics bundle (
color.sty, graphics.sty,
158 graphicx.sty,
\ldots) make extensive use of
\verb|
\special| commands.
159 Here are some notes on this topic. Please install the appropriate
160 driver file
\verb|pyx.def|, which defines all the specials, in your
161 \LaTeX-tree and add the content of both files
\verb|
color.cfg| and
162 \verb|graphics.cfg| to your personal configuration files.
\footnote{If
163 you do not know what I am talking about right now -- just ignore this
164 paragraph, but make sure not to set the
\texttt{pyxgraphics
} keyword
165 to
0.
} After you have installed the
\verb|.cfg| files please use the
166 \verb|text| module always with the
\verb|pyxgraphics| keyword set to
167 0, this switches off a hack that might be convenient for less
168 experienced
\LaTeX-users.
170 You can then import the packages of the graphics-bundle and related
171 packages (e.g.~rotating,
\ldots) with the option~
\verb|pyx|,
172 e.g.~
\verb|
\usepackage[pyx
]{color,
graphicx}|. Please note that the
173 option~
\verb|pyx| is only available with
\verb|pyxgraphics=
0| and a
174 properly installed driver file. Otherwise do not use this option, omit
175 it completely or say~
\verb|
[dvips]|.
177 When defining colours in
\LaTeX{} as one of the colour models
178 \verb|gray|,
\verb|cmyk|,
\verb|rgb|,
\verb|RGB|,
\verb|hsb| then
179 \PyX{} will use the corresponding values (one to four real numbers)
180 for output. When you use one of the
\verb|named| colors in
\LaTeX{}
181 then
\PyX{} will use the corresponding predefined colour (see module
182 \verb|
color| and the colour table at the end of the manual).
184 When importing eps-graphics in
\LaTeX{} then
\PyX{} will rotate, scale
185 and clip your file like you expect it. Note that
\PyX{} cannot import
186 other graphics files than
\verb|eps| at the moment.
188 For reference purpose, the following specials can be handled by the
189 \verb|text| module at the moment:
\medskip
195 \texttt{PyX:
color\_begin (model) (spec)
}\\
196 starts a colour. (model)~is one of
197 \
{\verb|gray|,
\verb|cmyk|,
\verb|rgb|,
\verb|hsb|,
\verb|texnamed|\
}.
198 (spec)~depends on the model: a name or some numbers.
\par
199 \texttt{PyX:
color\_end} ends a colour.
\par
200 \texttt{PyX:epsinclude file= llx= lly= urx= ury= width= height= clip=
0/
1}\\
201 includes an eps-file. The values of llx to ury are in the files' coordinate
202 system and specify the part of the graphics that should become the specified
203 width and height in the outcome. The graphics may be clipped. The last three
204 parameters are optional.
\par
205 \texttt{PyX:scale
\_begin (x) (y)
}\\
206 begins scaling from the current point.
\par
207 \texttt{PyX:scale
\_end} ends scaling.
\par
208 \texttt{PyX:rotate
\_begin (angle)
} begins rotation around the current
210 \texttt{PyX:rotate
\_end} ends rotation.
\par
214 \section{\TeX/
\LaTeX{} message parsers
}
216 Message parsers are used to scan the output of
\TeX/
\LaTeX. The output
217 is analysed by a sequence of message parsers. Each of them analyses
218 the output and remove those parts of the output, it feels responsible
219 for. If there is nothing left in the end, the message got validated,
220 otherwise an exception is raised reporting the problem.
224 parser name&purpose\\
226 \texttt{texmessage.load
}&loading of files (accept
\texttt{(file ...)
})\\
227 \texttt{texmessage.loadfd
}&loading of files (accept
\texttt{(file.fd)
})\\
228 \texttt{texmessage.graphicsload
}&loading of graphic files (accept
\texttt{<file.eps>
})\\
229 \texttt{texmessage.ignore
}&accept everything as a valid output\\
233 More specialised message parsers should become available as required.
234 Please feal free to contribute (e.g. with ideas/problems; code is
235 desired as well, of course). There are further message parsers for
236 \PyX{}s internal use, but we skip them here as they are not
237 interesting from the users point of view.
239 \section{The defaulttexrunner instance
}
240 The
\verb|defaulttexrunner| is an instance of the class
241 \verb|texrunner|, which is automatically created by the
\verb|text|
242 module. Additionally, the methods
\verb|text|,
\verb|preamble|, and
243 \verb|set| are available as module functions accessing the
244 \verb|defaulttexrunner|. This single
\verb|texrunner| instance is
245 sufficient in most cases.
249 %%% TeX-master: "manual.tex"