10
What is TeX/LaTeX and why do I need it?
11
---------------------------------------
13
TeX is a high quality typesetting system developed by Donald E. Knuth which is
14
available for a wide variety of operating systems. LaTeX is a macro package
15
originally developed by Leslie Lamport which makes life with TeX easier, in
16
particular for complex typesetting tasks. The current version of LaTeX is
17
referred to as LaTeX2e and offers e.g. improved font selection as compared to
18
the long outdated LaTeX 2.09 which should no longer be used.
20
All typesetting tasks in PyX are ultimately handed over to TeX (which is the
21
default) or LaTeX, so that PyX cannot do without it. On the other hand, the
22
capabilities of TeX and LaTeX can be used for complex tasks where both graphics
23
and typesetting are needed.
27
I don't know anything about TeX and LaTeX. Where can I read something about it?
28
--------------------------------------------------------------------------------
30
Take a look at CTAN (cf. :ref:`ctan`) where in `CTAN:info
31
<http://www.ctan.org/tex-archive/info/>`_ you may be able to find some useful
32
information. There exists for example “A Gentle Introduction to TeX” by M. Doob
33
(`CTAN:gentle/gentle.pdf <http://www.ctan.org/tex-archive/gentle/gentle.pdf>`_)
34
and “The Not So Short Introduction to LaTeX2e”
35
(`CTAN:info/lshort/english/lshort.pdf
36
<http:www.ctan.org/tex-archive/info/lshort/english/lshort.pdf>`_) by T. Oetiker
37
et al. The latter has been translated into a variety of languages among them
38
korean (which you will not be able to read unless you have appropriate fonts
39
installed) and mongolian.
41
Of course, it is likely that these documents will go way beyond what you will
42
need for generating graphics with PyX so you don't have to read all of it
43
(unless you want to use TeX or LaTeX for typesetting which can be highly
46
There exists also a number of FAQs on TeX at `CTAN:help <http://www.ctan.org/tex-archive/help>`_.
53
CTAN is the *Comprehensive TeX Archive Network* where you will find almost
54
everything related to TeX and friends. The main CTAN server is `www.ctan.org
55
<http://www.ctan.org>`_ but there exists a large number of mirrors around the
56
world. You can help to reduce the load on the main server by using
57
`mirror.ctan.org <http://mirror.ctan.org>`_ which will redirect you to a mirror
58
nearby. A list of known mirrors is available at
59
`http://mirror.ctan.org/README.mirrors
60
<http://mirror.ctan.org/README.mirrors>`_.
62
In this FAQ, ``CTAN:`` refers to the root of the CTAN tree, e.g.
63
`http://www.ctan.org/tex-archive/ <http://www.ctan.org/tex-archive/>`_. The
64
links to CTAN in this document point to the main server but you might consider
65
using a server closer to you in order to reduce traffic load.
67
Is there support for ConTeXt?
68
-----------------------------
70
No, and as far as I know there no plans to provide it in the near future.
71
Given the close ties between ConTeXt and MetaPost, ConTeXt users probably
72
prefer to stick with the latter anyway.
74
TeX and LaTeX commands useful for PyX
75
=====================================
77
How do I get a specific symbol with TeX or LaTeX?
78
-------------------------------------------------
80
A list of mathematical symbols together with the appropriate command name can
81
be found at `CTAN:info/symbols/math/symbols.pdf
82
<http://www.ctan.org/tex-archive/info/symbols/math/symbols.pdf>`_. A
83
comprehensive list containing almost 6000 symbols for use with LaTeX can be
84
obtained from `CTAN:info/symbols/comprehensive/symbols-a4.pdf
85
<http://www.ctan.org/tex-archive/info/symbols/comprehensive/symbols-a4.pdf>`_.
86
In some cases it might be necessary to install fonts or packages available from
87
CTAN (cf. :ref:`ctan`).
92
.. _undefined_usepackage:
94
Undefined control sequence ``\usepackage``
95
------------------------------------------
97
The command ``\usepackage`` is specific to LaTeX. Since by default PyX
98
uses TeX, you have to specify the correct mode::
100
text.set(mode="latex")
102
Undefined control sequence ``\frac``
104
The command ``\frac`` is only available in LaTeX. The equivalent to
105
``\frac{a}{b}`` in TeX is ``{a \over b}``. As an alternative you may ask for
106
the LaTeX mode as explained in :ref:`undefined_usepackage`.
108
Missing ``$`` inserted
109
----------------------
111
You have specified TeX- or LaTeX-code which is only valid in math mode.
112
Typical examples are greek symbols, sub- and superscripts or fractions.
114
On the PyX level, you can specify math mode for the whole string by using
115
``text.mathmode`` as in ::
117
c.text(0, 0, r"{\alpha}", text.mathmode)
119
Keep also in mind that the standard Python interpretation of the backslash as
120
introducing escape sequences needs to be prevented
123
On the TeX/LaTeX level you should enclose the commands requiring math mode in
124
``$``'s. As an example, ``$\alpha_i^j$`` will produce a greek letter alpha with
125
a subscript i and a superscript j. The dollar sign thus allows you to specify
126
math mode also for substrings. There exist other ways to specify math mode in
127
TeX and LaTeX which are particularly useful for more complex typesetting tasks.
128
To learn more about it, you should consult the documentation
129
:ref:`intro_tex_latex`.
131
Why do environments like ``itemize`` or ``eqnarray`` seem not to work?
132
----------------------------------------------------------------------
134
An itemize environment might result in a LaTeX error complaining about a
135
``missing \item`` or an eqnarray might lead to a LaTeX message ``missing
136
\endgroup inserted`` even though the syntax appears to be correct. The TeXnical
137
reason is that in PyX text is typeset in left-right mode (LR mode) which does
138
not allow linebreaks to occur. There are two ways out.
140
If the text material should go in a box of given width, a parbox can be used
141
like in the following example::
143
text.set(mode="latex")
146
c.text(0, 0, r"\begin{itemize}\item a\item b\end{itemize}", [text.parbox(w)])
148
Occasionally, one would like to have the box in which the text appears to be as
149
small as possible. Then the ``fancybox`` package developed by Timothy Van Zandt
150
is useful which provides several environments like ``Bitemize`` and
151
``Beqnarray`` which can be processed in LR mode. The relevant part of the code
154
text.set(mode="latex")
155
text.preamble(r"\usepackage{fancybox}")
157
c.text(0, 0, r"\begin{Bitemize}\item a\item b\end{Bitemize}")
159
Other environments provided by the ``fancybox`` package include ``Bcenter``,
160
``Bflushleft``, ``Bflushright``, ``Benumerate``, and ``Bdescription``. For more
161
details, the documentation of the package should be consulted.
163
.. _fontshape_undefined:
165
Font shape ``OT1/xyz/m/n`` undefined
166
------------------------------------
168
You have asked to use font ``xyz`` which is not available. Make sure that you
169
have this font available in Type1 format, i.e. there should be a file
170
``xyz.pfb`` somewhere. If your TeX system is TDS compliant (TDS=TeX directory
171
structure, cf. `CTAN:tds/draft-standard/tds/tds.pdf
172
<http://www.ctan.org/tex-archive/tds/draft-standard/tds/tds.pdf>`_) you should
173
take a look at the subdirectories of ``$TEXMF/fonts/type1``.
175
File ``…`` is not available or not readable
176
-------------------------------------------
178
Such an error message might already occur when running the example file
179
``hello.py`` included in the PyX distribution. Usually, the error occurs due to
180
an overly restrictive umask setting applied when unpacking the ``tar.gz``
181
sources. This may render the file mentioned in the error message unreadable
182
because the python distutil installation package doesn't change the file
183
permissions back to readable for everyone.
185
If the file exists, the problem can be solved by changing the permissions to
188
No information for font ``cmr10`` found in font mapping file
189
------------------------------------------------------------
191
Such an error message can already be encountered by simply running the example
192
file ``hello.py`` included in the PyX distribution. The likely reason is that
193
the TeX system does not find the cmr fonts in Type1 format. PyX depends on
194
these fonts as it does not work with the traditional pk fonts which are stored
197
Therefore, the first thing to make sure is that the cmr Type1 fonts are
198
installed. In some TeX installations, the command ``kpsewhich cmr10.pfb`` will
199
return the appropriate path if the cmr fonts exist in the binary Type1 format
200
(extension ``pfb``) required by PyX. If the command does not work but the TeX
201
system is TDS compliant (:ref:`fontshape_undefined`), a look should be taken at
202
``$TEXMF/fonts/type1/bluesky/cm`` where ``$TEXMF`` is the root of the ``texmf``
205
If the Type1 fonts do not exist on the system, they may be obtained from the
206
CTAN (cf. :ref:`ctan`) at `CTAN:fonts/cm/ps-type1/bluesky
207
<http://www.ctan.org/tex-archive/fonts/cm/ps-type1/bluesky>`_). See the
208
``README`` for information about who produced these fonts and why they are
211
If the Type1 fonts exist, the next step is to take a look at ``psfonts.map``.
212
There may be several files with this name on the system, so it is important to
213
find out which one TeX is actually using. ``kpsewhich psfonts.map`` might give
216
The most likely problem is that this file does not contain a line telling TeX
217
what to do if it encounters a request for font ``cmr10``, i.e. the following
218
line may be missing ::
220
cmr10 CMR10 <cmr10.pfb
222
It is probable that the required lines (in practice, you do not just need
223
``cmr10``) are found in a file named ``psfonts.cmz`` which resides in
224
``$TEXMF/dvips/bluesky``.
226
One solution is to instruct PyX to read additional map files like
227
``psfonts.cmz`` or ``psfonts.amz``. This can be achieved by modifying the
228
appropriate ``pyxrc`` file which is either the systemwide ``/etc/pyxrc`` or
229
``.pyxrc`` in the user's home directory. Here, the names of the map files to be
230
read by PyX should be appended separated by whitespaces like in the following
234
fontmaps = psfonts.map psfonts.cmz psfonts.amz
236
The same effect can be achieved by inserting the following line into the
239
text.set(fontmaps="psfonts.map psfonts.cmz psfonts.amz")
241
Note that the default map (``psfonts.map``) has to be specified explicitly.
243
An alternative approach consists in modifying the TeX installation by inserting
244
the contents of the desired map files like ``psfonts.cmz`` into
245
``psfonts.map``. Probably, ``psfonts.map`` recommends not to do this by hand.
246
In this case the instructions given in the file should be followed. Otherwise,
247
``psfonts.cmz`` should be copied into ``psfonts.map`` while keeping a backup of
248
the old ``psfonts.map`` just in case. After these changes, PyX most likely will
249
be happy. When inserting ``psfonts.cmz`` into ``psfonts.map`` it may be a good
250
idea to include ``psfonts.amz`` as well. ``psfonts.amz`` contains information
251
about some more fonts which might be needed at some point. Making these changes
252
to ``psfonts.map`` will imply that the TeX system will use the cmr fonts in
253
Type1 format instead of pk format which is actually not a bad thing, in
254
particular if ``latex / dvips / ps2pdf`` is used to generate PDF output. With
255
fonts in pk format this will look ugly and using Type1 fonts solves this
256
problem as well. When ``pdflatex`` is used to create PDF files, Type1 fonts
262
I have Type1 fonts in ``pfa`` format. How do I obtain the corresponding ``pfb`` files needed by PyX?
263
----------------------------------------------------------------------------------------------------
267
still needs to be answered
271
I want to use a font other than computer modern roman
272
-----------------------------------------------------
274
As long as you have a font in Type1 format available, this should be no
275
problem (even though it may cost you some time to set up things properly).
277
In the simplest case, your LaTeX system contains everything needed.
278
Including the following line into your code will probably work ::
280
text.set(mode="latex")
281
text.preamble(r"\usepackage{mathptmx}")
283
and give you Times as roman font.
285
If you own one of the more common commercial fonts, take a look at `CTAN:fonts
286
<http://www.ctan.org/tex-archive/fonts/>`_ and its subdirectories as well as at
287
the web page `http://home.vr-web.de/was/fonts.html
288
<http://home.vr-web.de/was/fonts.html>`_ of Walter Schmidt. It is not unlikely
289
that somebody has already done most of the work for you and created the files
290
needed for the font to work properly with LaTeX. But remember: we are talking
291
about commercial fonts here, so do not expect to find the fonts themselves for
294
If none of these cases applies, you should spend some time reading manuals
295
about font installation, e.g. `CTAN:macros/latex/doc/fntguide.pdf
296
<http://www.ctan.org/tex-archive/macros/latex/doc/fntguide.pdf>`_ (of course, I
297
do not expect font wizards to read the last few lines).
299
Can I use a TrueType font with PyX?
300
-----------------------------------
302
Not directly as PyX only knows how to handle Type1 fonts (although it is
303
possible to get LaTeX to work with TrueType fonts). However, you may use
304
``ttf2pt1`` (from `ttf2pt1.sourceforge.net <http://ttf2pt1.sourceforge.net>`_)
305
to convert a TrueType font into a Type1 font which you then install in your TeX
306
system (cf. :ref:`other_font`). You will loose hinting information in the
307
conversion process but this should not really matter on output devices with not