2 \documentclass[11pt,DIV14
]{scrartcl
}
3 \usepackage[latin1]{inputenc}
6 %\usepackage[all,comments]{glifaq}
7 \usepackage[answered
]{glifaq
}
8 \usepackage[pdftex
]{hyperref
}
9 \hypersetup{pdftitle=
{PyX FAQ
}%
10 ,pdfauthor=
{\textcopyright\ Gert-Ludwig Ingold
11 <gert.ingold@physik.uni-augsburg.de>
}%
14 \def\pyxversion{\input{pyxversion
}}
18 \LARGE\sffamily Some frequently and\\
19 not so frequently asked questions\\
22 {\small\sffamily (version
\pyxversion)
}\\
[1truecm
]
24 Gert-Ludwig Ingold
\par
25 \href{mailto:gert.ingold@physik.uni-augsburg.de
}{\url{<gert.ingold@physik.uni-augsburg.de>
}}
30 \section*
{Acknowledgements
}
31 The following persons have in one way or the other, e.g.\ by asking good
32 questions or providing answers, contributed to this FAQ:\\
33 Walter Brisken, Jörg Lehmann, Michael Schindler, Andr
{\'e
} Wobst.
36 \section{General aspects of
\PyX}
37 \question{a
}{The name of the game
}
39 {Originally, the name
\PyX{} was constructed as a combination of
40 \textbf{P
}ostscript, i.e.\ the first output format supported by
\PyX{},
41 P
\textbf{y
}thon, i.e.\ the language in which
\PyX{} is written, and
42 Te
\textbf{X
}, i.e.\ the program which
\PyX{} uses for typesetting purposes.
43 Actually, the title of this question is a tribute to
\TeX{} because it is
44 taken from the first chapter of the
\TeX{}book
\footnote{D.~Knuth,
\textit{The
45 \TeX{}book
} (Addison-Wesley,
1984)
} where the origin of the name
\TeX{} and its
46 pronunciation are explained.
48 Despite the ties between
\TeX{} and
\PyX{}, their pronunciation is quite
49 different. According to the developers of
\PyX{}, it should be pronounced as
50 \tipagraph{[pYks
]}{tipa1.pdf
}. Please do not pronounce it as
51 \tipagraph{[pYx
]}{tipa2.pdf
} or
\tipagraph{[pY
\c c
]}{tipa3.pdf
}.
54 \question{a
}{Where do I get the latest version of
\PyX?
}
56 {\label{q:where_do_I_get_PyX
}
57 The current release of
\PyX{} (as well as older ones) is freely available
58 from
\url{http://pyx.sourceforge.net
} where also a CVS repository with the
59 latest patches can be found. Possibly older versions of
\PyX{} are
60 also available as package for
61 various Linux distributions: see, for instance,
62 \url{http://packages.debian.org/testing/python/python-pyx.html
} for
63 information on the
\PyX{} package in Debian GNU/Linux,
64 \url{http://packages.gentoo.org/ebuilds/?pyx-
0.3.1} for a Gentoo Linux
66 \url{http://www.suse.de/en/private/products/suse_linux/i386/packages_professional/python-pyx.html
}
67 for the
\PyX{} package in the SUSE LINUX professional distribution.
70 \question{c
}{How can I determine the version of
\PyX{} running on my
73 {Start a python session (usually by typing
\texttt{python
} at the system
74 prompt) and then type the following two commands (
\texttt{>>>
} is the python
78 >>> pyx.
\us\us{}version
\us\us
82 \question{a
}{How can I access older versions of
\PyX?
\new}
84 {As at present it is not guaranteed that
\PyX{} is backward compatible, it may
85 be desirable to access an older version of
\PyX{} instead of adapting older
86 code to the current version of
\PyX. In order to do that, one needs the
87 corresponding
\PyX{} package (see
\uaref{q:where_do_I_get_PyX
} if you need to
88 download it), which should be unpacked below a directory, e.g.\
89 \texttt{/home/xyz/Python
}, where you want to keep the various
\PyX{} versions.
90 This will result in a subdirectory with a name like
\texttt{PyX-
0.6.3} which
91 contains the contents of the corresponding package. You can then ask Python to
92 first look in the appropriate directory before looking for the current version
93 of
\PyX{} by inserting the following code (appropriately modified according
94 to your needs) at the beginning of your program before importing the
\PyX{}
98 sys.path
[:
0]~=~
["/home/xyz/Python/PyX-
0.6.3"
]
100 Including appropriate lines even if the current version of
\PyX{} is used,
101 might turn out to be helpful when the current version has become an old
102 version (unless you have no difficulties determining the
\PyX{} version by
103 looking at your code).
105 If your operating system supports path expansion, you might use as an
109 sys.path
[:
0]~=~
[os.path.expanduser("
\char126/Python/PyX-
0.6.3")
]
111 which will expand the tilde to your home directory.
114 \question{c
}{Does
\PyX{} run under my favorite operating system?
}
116 {Yes, if you have installed Python (
\uaref{q:what_is_python
})
117 and
\TeX{} (
\uaref{q:what_is_tex
}). Both are available for
118 a large variety of operating systems so chances are pretty good that you will
119 get
\PyX{} to work on your system.
122 \question{c
}{Under which versions of Python will
\PyX{} run?
}
124 {\PyX{} is supposed to work with Python
2.0 and above. However, most of the
125 development takes place under the current production version of Python (
2.3.3
126 by the time of this writing) and thus
\PyX{} is better tested with this version. On the other hand, the examples and tests are verified to run with all Python
127 versions
2.x.
\PyX{} will not work with Python
1.x due to missing language
130 The version of your Python interpreter can be determined by calling
131 it with the option
\texttt{-V
}. Alternatively, you can simply start the
132 interpreter and take a look at the startup message. Note that there may be
133 different versions of Python installed on your system at the same time. The
134 default Python version need not be the same for all users.
137 \question{a
}{Does
\PyX{} provide a GUI to view the produced image?
}
139 {No,
\PyX{} itself does not provide a means to view the produced image. The
140 result of a
\PyX{} run is an EPS (= Encapsulated PostScript) file which can
141 be viewed, printed or imported into other applications. There are several
142 means of viewing EPS files. A common way would be to use
\texttt{ghostview
}
143 which provides a user interface to the PostScript interpreter
144 \texttt{ghostscript
}. More information about this software, which is
145 available for a variety of platforms, can be found at
146 \url{http://www.cs.wisc.edu/~ghost/
}. If you do not own a printer which is
147 capable of printing PostScript files directly,
\texttt{ghostscript
} may
148 also be useful to translate the EPS file produced by
\PyX{} into something
149 your printer will understand.
}
151 \question{a
}{Where can I get help if my question is not answered in this
154 {The
\PyX{} sources contain a reference manual which is also available
155 online at
\url{http://pyx.sourceforge.net/manual/
}. Furthermore, there
156 exists a set of examples demonstrating various features of
\PyX, which is
157 available in the sources or can be browsed at
\url{http://pyx.sourceforge.net/examples.html
}.
158 If the feature you are looking for is among them, using the appropriate part
159 of the example code or adapting it for your purposes may help.
161 There is also a user discussion list about
\PyX{} which you can subscribe to
162 at
\url{http://lists.sourceforge.net/lists/listinfo/pyx-user
}. The archive of
163 the discussion list is available at
\url{http://sourceforge.net/mailarchive/forum.php?forum_id=
23700}.
165 Finally, it might be worth checking
\url{http://pyx.sourceforge.net/pyxfaq.pdf
}
166 for an updated version of this FAQ.
171 \question{c
}{What is Python?
}
173 {\label{q:what_is_python
}
174 From
\url{www.python.org
}:
176 Python is an
\textit{interpreted, interactive, object-oriented
} programming
177 language. It is often compared to Tcl, Perl, Scheme or Java.
179 Python combines remarkable power with very clear syntax. It has modules,
180 classes, exceptions, very high level dynamic data types, and dynamic typing.
181 There are interfaces to many system calls and libraries, as well as to various
182 windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules are easily
183 written in C or C++. Python is also usable as an extension language for
184 applications that need a programmable interface.
186 The Python implementation is portable: it runs on many brands of UNIX, on
187 Windows, OS/
2, Mac, Amiga, and many other platforms. If your favorite system
188 isn't listed here, it may still be supported, if there's a C compiler for it.
189 Ask around on
\href{news:comp.lang.python
}{news:comp.lang.python
} --- or just
190 try compiling Python yourself.
192 The Python implementation is
193 \href{http://www.python.org/doc/Copyright.html
}{copyrighted
}
194 but
\textbf{freely usable and distributable, even for commercial use
}.
198 \question{a
}{Where can I learn more about Python?
}
200 {The place to start is
\url{www.python.org
} where you will find plenty of
201 information on Python including tutorials.
204 \question{c
}{What do I need to import in order to use
\PyX?
}
206 {It is recommended to begin your Python code with
210 when using
\PyX. This allows you for example to write simply
211 \texttt{graph.graphxy
}
212 instead of
\texttt{pyx.graph.graphxy
}. The following modules will be loaded:
213 \texttt{attr
},
\texttt{box
},
\texttt{canvas
},
\texttt{color},
\texttt{connector
},
\texttt{data
},
214 \texttt{deco
},
\texttt{epsfile
},
\texttt{graph
},
\texttt{path
},
215 \texttt{style
},
\texttt{trafo
},
\texttt{text
}, and
\texttt{unit
}.
217 For convenience, you might import specific objects of a module like in
219 from graph import graphxy
221 which allows you to write
\texttt{graphxy()
} instead of
\texttt{graph.graphxy()
}.
223 All code segments in this
document assume that the import line mentioned in
224 the first code snippet is present.
227 \question{a
}{What is a raw string and why should I know about it when
230 {\label{q:raw_string
}
231 The backslash serves in standard Python strings to start an escape sequence.
232 For example
{\cs n
} corresponds to a newline character. On the other hand,
233 \TeX{} and
\LaTeX{}, which do the typesetting in
\PyX, use the backslash to
234 indicate the start of a command. In order to avoid the standard interpretation,
235 the string should be marked as a raw string by prepending it by an
\texttt{r
}
238 c.text(
0,
0, r"\$
{\cs alpha
}{\cs beta
}{\cs gamma
}\$")
242 \section{Plotting of graphs
}
244 \subsection{General aspects
}
246 \question{c
}{How do I generate a graph from data as simply as possible?
}
248 {\label{q:mingraphdata
}
249 Suppose that you have a data file
\texttt{x.dat
} containing values for
250 $x$ and $y$ in two columns. Then the following code will do the job
254 g = graph.graphxy(width=
10)\\
255 g.plot(graph.data.file("x.dat", x=
1, y=
2))\\
258 \texttt{graphxy
} creates a canvas (called
\texttt{g
} in this example) onto
259 which the graph will be drawn and it sets the default behavior including the
260 axis. There is, however, no default value for the width of the graph. In
261 \texttt{plot
} you have to specify the name of the data file and the columns
262 from which the data should be taken. Finally,
\texttt{writeEPSfile
} will
263 generate the postscript file
\texttt{x.eps
} which you can view or print.
265 A minimal example is also provided in the
\PyX{} distribution as
266 \path{examples/graphs/minimal.py
}.
269 \question{a
}{How do I generate a graph of a function as simply as possible?
}
271 {\label{q:mingraphfunc
}
272 The following example will draw a parabola:
276 g = graph.graphxy(width=
10,\\
277 ~~~~~~~~~~~~~~~~~~x=graph.axis.linear(min=-
2, max=
2)\\
278 ~~~~~~~~~~~~~~~~~~)\\
280 g.plot(graph.data.function("y=x**
2"))\\
284 Most of the code has been explained in
\uaref{q:mingraphdata
}. The main
285 difference is that here you need to specify minimum and maximum for the
286 $x$-axis so that
\PyX{} knows in which range to evaluate the function.
288 Another, slightly more complex, example is also provided in the
\PyX{}
289 distribution as
\path{examples/graphs/piaxis.py
}.
292 \question{a
}{How can I stack graphs?
}
294 {\PyX{} always needs a canvas to draw on. One possibility therefore consists
295 in creating a new canvas with
299 and inserting the graphs into this canvas with
\texttt{c.insert(...)
}. Here,
300 \texttt{...
} has to be replaced by the name of the graph. Alternatively, the
301 canvas created with
\texttt{graph.graphxy
} for one of the graphs can be used
302 to insert the other graphs even if they will be positioned outside the
305 The second issue to address is positioning of the graphs. By specifying
306 \texttt{xpos
} and
\texttt{ypos
} when calling
\texttt{graphxy
}, you can
307 define the position of a graph. Later on, the position and size of a
308 graph
\texttt{g
} can be referred to as
\texttt{g.xpos
},
\texttt{g.ypos
},
309 \texttt{g.width
}, and
\texttt{g.height
} even if for example the height has
310 never been specified explicitly but is only defined by a
\PyX{} default.
312 The following example shows how to put graph
\texttt{gupper
} above graph
313 \texttt{glower
} on a canvas
\texttt{c
}:
316 from graph import graphxy\\
318 c = canvas.canvas()\\
320 glower = graphxy(width=
10)\\
324 gupper = graphxy(width=
10, ypos=glower.ypos+glower.height+
2)\\
330 where
\texttt{...
} has to be replaced by the appropriate information like
331 data and symbol specifications and the name of the output file. Here,
332 \texttt{c.insert
} is used to actually insert the subcanvasses
333 for the graphs into the main canvas
\texttt{c
} and
\texttt{c.writeEPSfile
}
334 in the last line requests to write the contents of this canvas to a file.
336 %In order to suppress the labels of the $x$-axis of the upper graph, use
338 %myaxispainter = graph.axispainter(labelattrs=None)
340 %gupper = graph.graphxy(...,
341 % x=graph.axis.linear(...,
342 % part=graph.linpart(),
343 % painter=myaxispainter)
348 \question{a
}{How can I plot grid data?
}
350 {\PyX{} offers support for plotting three-dimensional data as two-dimensional
351 color plots or grey-scale plots and of vector fields by providing ways to
352 plot rectangles and arrows in graphs.
354 We start by considering the task of creating a two-dimensional
color plot by
355 plotting a number of filled rectangles. One first needs to create a data set
356 which consists of five entries per data point. These are the lower left corner
357 $(x_
\mathrm{min
},y_
\mathrm{min
})$ and the upper right corner
358 $(x_
\mathrm{max
},y_
\mathrm{max
})$ of the triangle and a value between
0 and
1
359 determining the
color via a
\PyX{} color palette. The following code gives an
360 idea of how to proceed:
362 g.plot(graph.data.file("datafile.dat"), xmin=
1, xmax=
2, ymin=
3, ymax=
4,
color=
5),\\
363 ~~~~~~~
[graph.style.rect(
color.palette.ReverseRainbow)
]\\
367 Here, we assume that the data are stored in
\texttt{datafile.dat
} and the
368 columns contain $x_
\mathrm{min
}$, $x_
\mathrm{max
}$, $y_
\mathrm{min
}$,
369 $y_
\mathrm{max
}$, and the
color value in this order. The columns are
370 numbered from
1, since the
0th column contains the line number. To
371 determine the
color, we use the
\texttt{ReverseRainbow
} palette. The
372 last line instructs
\PyX{} to plot the rectangles before plotting the
373 axes. Otherwise, the axes might be covered partially by the rectangles
374 and, in particular, the ticks might not be visible. Gray-scale plots
375 can easily be generated by specifying the palette
\texttt{Gray
} or
376 \texttt{ReverseGray
} (cf.\ appendix C of the manual for a list of
377 predefined palettes).
379 At first sight, it seems surprising that plotting of grid data requires
380 the specification of four coordinates for the rectangle. The reason is that
381 this allows to draw rectangles of varying sizes which may help to reduce the
382 size of the postscript file by combining rectangles of the same
color in
383 horizontal or vertical direction. For example, it may be sufficient to plot
384 a grey-scale image in a small number of grey shades and then combining
385 rectangles may be appropriate. Note, though, that this step is part of the
386 data creation and not preformed by
\PyX{}. Another advantage of fully
387 specifying each rectangle is that it is straightforward to leave parts of the
390 The same ideas as for the
color plot can be applied to plot vector fields where
391 each data point is represented by an arrow. In this case a data point is
392 specified by the position of the arrow, its size and its direction as indicated
393 in the following code snippet:
395 g.plot(graph.data.file("datafile.dat"), x=
1, y=
2, size=
3, angle=
4),\\
396 ~~~~~~~
[graph.style.arrow()
]\\
400 Complete code examples can be found in
\path{examples/graphs/mandel.py
} and
401 \path{examples/graphs/arrows.py
}\,.
404 \question{a
}{How can I access points in problem coordinates of a graph?
}
406 {\label{q:problemcoord
}
407 Sometimes it may be necessary to add graphical elements to a graph in addition
408 to the data or function(s) which have been plotted as described in
409 \uaref{q:mingraphdata
} and
\uaref{q:mingraphfunc
}. For a graph instance
410 \texttt{g
} the positioning can easily be done in canvas coordinates by making
411 use of the origin (
\texttt{g.xpos
},
\texttt{g.ypos
}) and the width
412 (
\texttt{g.width
}) and height (
\texttt{g.height
}) of the graph.
414 Occasionally, it may be more convenient to specify the position of the
415 additional material in terms of problem coordinates. However, this requires
416 that the mapping from problem coordinates to canvas coordinates is known.
417 By default this is not the case before the content of the canvas is written
418 to the output which is too late for our purpose. One therefore needs to
419 explicitly instruct
\PyX{} to determine this mapping. One possibility is to
420 ask
\PyX{} to finish the graph by means of
\texttt{g.finish()
}. Now, problem
421 coordinates can be used to insert additional material which will end up in
422 front of the graph. If this is not desired, one should only fix the layout
423 of the graph by means of
\texttt{g.dolayout()
}. Then, the additional material
424 can be put onto the canvas before the graph is drawn and it will therefore
425 appear behind the graph.
427 The conversion of problem coordinates (
\texttt{px
},
\texttt{py
}) to canvas
428 coordinates (
\texttt{x
},
\texttt{y
}) is performed as follows:
432 By default, the problem coordinates will refer to the ranges of the $x$ and $y$
433 axes. If several axes with different ranges exist, the
434 instances of the desired axes should be passed to the
\texttt{pos
} method by
435 means of the keyword arguments
\texttt{xaxis
} and
\texttt{yaxis
}.
437 We remark that the drawing of lines parallel to one of the axes at specific
438 problem coordinates can also be done by adapting the method described in
442 \question{t
}{I would like a key for only some of my data sets. How do I do
448 \subsection{Axis properties
}
450 \question{a
}{How do I specify the tick increment?
}
452 {In the partition of a linear axis, the increments associated with ticks,
453 subticks etc.\ can be specified as argument of
\texttt{parter.linear
}. In the
454 following example, ticks will be drawn at even values while subticks will
455 be drawn at all integers:
457 from pyx.graph import axis\\
458 tg = graph.graphxy(width=
10,\\
459 ~~~~~~~~~~~~~~~~~~~x=axis.linear(min=
1, max=
10,\\
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~parter=axis.parter.linear(tickdist=
[2,
1]))\\
465 \question{a
}{How do I plot the zero line?
}
469 \PyX{} releases before
0.6 offered the possibility to stroke a zero line by
470 specifying
\texttt{zeropathattrs
} in the painter constructor. In more recent
471 releases, one proceeds as follows. First one has to fix the layout information
472 of the graph by means of the
\texttt{finish
} or
\texttt{dolayout
} method (see
473 \ref{q:problemcoord
} for a more detailed explanation). Then, the
474 \texttt{xgridpath
} or
\texttt{ygridpath
} method of a graph will return a grid
475 path parallel to the $y$ or $x$ axis, respectively, at the specified $y$ value.
476 As an example, a zero line in $x$ direction can be drawn as follows:
479 g.stroke(g.ygridpath(
0))
483 \question{a
}{How can I add grid lines to a graph?
}
486 Specifying
\texttt{gridattrs
} for the painter of an axis will generate grid
487 lines orthogonal to this axis. At least an empty list is needed like in
489 g = graph.graphxy(width=
10,\\
490 ~~~~~~~~~~~~~~~~~~x=graph.axis.linear(painter=graph.axis.painter.regular(gridattrs=
[])),\\
491 %~~~~~~~~~~~~~~~~~~~~~~~~~~painter=graph.axis.painter.regular(gridattrs=[])\\
492 %~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~),\\
493 ~~~~~~~~~~~~~~~~~~y=graph.axis.linear()\\
496 where grid lines in vertical direction are drawn in default style.
498 Occassionally, one might want to draw grid lines corresponding to ticks and
499 subticks in a different style. This can be achieved by specifiying
500 changeable attributes using
\texttt{changelist
}. The following code
502 my
\_xpainter = graph.axis.painter.regular(gridattrs=\\
503 ~~~~~~~~~~~~~~~~~~~~
[attr.changelist(
[style.linestyle.solid, style.linestyle.dashed
])
]\\
504 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~)\\
505 my
\_ypainter = graph.axis.painter.regular(gridattrs=\\
506 ~~~~~~~~~~~~~~~~~~~~
[attr.changelist(
[color.rgb.red,
color.rgb.blue
])
]\\
507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~)\\
509 g = graph.graphxy(width=
10,\\
510 ~~~~~~~~~~~~~~~~~~x=graph.axis.linear(painter=my
\_xpainter),\\
511 ~~~~~~~~~~~~~~~~~~y=graph.axis.linear(painter=my
\_ypainter)\\
514 will create vertical solid and dashed grid lines for ticks and subticks,
515 respectively. The horizontal grid lines will be red for ticks and blue for
516 subticks. The changeable attributes are applied in a cyclic manner. Therefore,
517 in this example grid lines at subsubticks would be plotted in the same style
518 as for ticks. If this is not desired, the list of attributes should be extended
519 by an appropriate third style. The keyword
\texttt{None
} will switch off
520 the respective level of grid lines in case you want to draw them only e.g.\
521 for ticks but not subticks.
524 \subsection{Data properties
}
526 \question{a
}{How do I choose the symbol?
}
528 {\label{q:choose_symbol
}
529 Suppose a graph called
\texttt{g
} has been initialized, e.g.\ by using
530 \texttt{graph.graphxy
}. Then, data and the style of their representation
531 in the graph are defined by calling
\texttt{g.plot
} like in the following
532 example in which filled circles are requested:
534 g.plot(graph.data.file("test.dat"),\\
535 ~~~~~~~
[graph.style.symbol(graph.style.symbol.circle, symbolattrs=
[deco.filled
])
]\\
540 \question{a
}{How do I choose the
color of the symbols?
}
542 {Colors are not properties of the symbol as such and can therefore not
543 be specified in
\texttt{symbolattrs
} directly. The
color is rather related
544 to the plotting of the symbol as defined by
\texttt{deco.stroked
} or
545 \texttt{deco.filled
}. With
547 graph.style.symbol(graph.style.symbol.circle,\\
548 ~~~~~~~~~~~~~~~~~~~symbolattrs=
[deco.stroked(
[color.rgb.red
]),\\
549 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~deco.filled(
[color.rgb.green
])
]\\
552 you will obtain a circle filled in green with a red borderline.
555 \question{a
}{How do I choose the line style?
}
557 {If you do not want to use symbols, you can set the line style as in this
560 g.plot(graph.data.file("test.dat"),\\
561 ~~~~~~~
[graph.style.line(
[style.linewidth.Thin
])
]\\
564 where the linewidth is set.
566 If you also want to use symbols, you can combine the symbol and the
569 g.plot(graph.data.file("test.dat"),\\
570 ~~~~~~~
[graph.style.line(lineattrs=
[style.linewidth.Thin,\\
571 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~style.linestyle.dashed
]),\\
572 ~~~~~~~~graph.style.symbol(graph.style.symbolline.circle,\\
573 ~~~~~~~~~~~~~~~~~~~~~~~~~~~symbolattrs=
[deco.filled
])
577 to plot the symbols on top of a thin, dashed line. You may alter the
578 order of the styles to plot the line on top of the symbols.
581 \section{\TeX{} and
\LaTeX{}}
583 \subsection{General aspects
}
585 \question{a
}{What is
\TeX/
\LaTeX{} and why do I need it?
}
587 {\label{q:what_is_tex
}
588 \TeX{} is a high quality typesetting system developed by Donald E. Knuth
589 which is available for a wide variety of operating systems.
\LaTeX{} is a
590 macro package originally developed by Leslie Lamport which makes life with
591 \TeX{} easier, in particular for complex typesetting tasks. The current
592 version of
\LaTeX{} is referred to as
\LaTeXe{} and offers e.g.\ improved
593 font selection as compared to the older
\LaTeX{} 2.09 which should no longer
596 All typesetting tasks in
\PyX{} are finally handed over to
\TeX{} (which is the
597 default) or
\LaTeX{}, so that
\PyX{} cannot do without it. On the other hand,
598 the capabilities of
\TeX{} and
\LaTeX{} can be used for complex tasks where
599 both graphics and typesetting are needed.
602 \question{a
}{I don't know anything about
\TeX{} and
\LaTeX{}. Where can I read
605 {\label{q:intro_tex_latex
}
606 Take a look at CTAN (
\uaref{q:ctan
}) where in
\ctan{info
}
607 you may be able to find some useful information. There exists for example
608 ``A Gentle Introduction to
\TeX'' by M.~Doob (
\ctan{gentle/gentle.pdf
}) and
609 ``The Not So Short Introduction to
\LaTeXe''
610 (
\ctan{info/lshort/english/lshort.pdf
}) by T.~Oetiker et al. The latter has
611 been translated into a variety of languages among them korean (which you will
612 not be able to read unless you have appropriate fonts installed) and mongolian.
614 Of course, it is likely that these documents will go way beyond what you
615 will need for generating graphics with
\PyX{} so you don't have to read all
616 of it (unless you want to use
\TeX{} or
\LaTeX{} for typesetting which can be
619 There exists also a number of FAQs on
\TeX{} at
\ctan{help
}.
622 \question{a
}{What is CTAN?
}
625 CTAN is the Comprehensive TeX Archive Network where you will find almost
626 everything related to
\TeX{} and friends. The main CTAN servers are
627 \url{tug.ctan.org
},
\url{dante.ctan.org
}, and
\url{cam.ctan.org
}. A list of
628 FTP mirrors can be found at
\ctan{CTAN.sites
}.
630 In this FAQ,
\texttt{CTAN:
} refers to the root of an anonymous ftp CTAN tree,
631 e.g.\
\url{ftp://ctan.tug.org/tex-archive/
},
632 \url{ftp://ftp.dante.de/tex-archive/
},
633 and
\url{ftp://ftp.tex.ac.uk/tex-archive/
}. The links to CTAN in this
document
634 point to one of these servers but you might consider using a FTP mirror closer
635 to you in order to reduce traffic load.
638 \question{a
}{Is there support for Con
\TeX{}t?
}
640 {No, and as far as I know there no plans to provide it in the near future.
641 Given the close ties between Con
\TeX{}t and Meta\-Post, Con
\TeX{}t users
642 probably prefer to stick with the latter anyway.
645 \subsection{\TeX{} and
\LaTeX{} commands useful for
\PyX}
647 \question{a
}{How do I get a specific symbol with
\TeX{} or
\LaTeX?
}
649 {A list of mathematical symbols together with the appropriate command name
650 can be found at
\ctan{info/symbols/math/symbols.ps
}. A comprehensive list
651 containing more than
2500 symbols for use with
\LaTeX{} can be obtained from
652 \ctan{info/symbols/comprehensive/symbols-a4.pdf
}. In some cases it might be
653 necessary to install fonts or packages available from CTAN
657 \subsection{\TeX{} and
\LaTeX{} errors
}
659 \question{a
}{Undefined control sequence
\cs{usepackage
}}
661 {\label{q:undefined_usepackage
}
662 The command
\cs usepackage is specific to
\LaTeX{}. Since by default
\PyX{}
663 uses
\TeX{}, you have to specify the correct mode:
665 text.set(mode="latex")
669 \question{a
}{Undefined control sequence
\cs{frac
}}
671 {\label{q:undefined_frac
}
672 The command
\cs frac is only available in
\LaTeX{}. In
\TeX{} you should
673 use
\texttt{\cb{a
\cs over b
}} in math mode to produce $
{a
\over b
}$. As an
674 alternative you may ask for the
\LaTeX{} mode as explained in
675 \ref{q:undefined_usepackage
}.
678 \question{a
}{Missing \$ inserted
}
680 {You have specified
\TeX- or
\LaTeX-code which is only valid in math mode.
681 Typical examples are greek symbols, sub- and superscripts or fractions.
683 On the
\PyX{} level, you can specify math mode for the whole string by using
684 \texttt{text.mathmode
} as in
686 c.text(
0,
0, r"
{\cs alpha
}", text.mathmode)
688 Keep also in mind that the standard Python interpretation of the backslash as
689 introducing escape sequences needs to be prevented
690 \uaref{q:raw_string
}.
692 On the
\TeX/
\LaTeX{} level you should enclose the commands requiring math
693 mode in \$'s. As an example,
\texttt{\$
\cs alpha
\us i
\hat j\$
} will produce
694 $
\alpha_i^j$. This allows you to specify math mode also for substrings. There
695 exist other ways to specify math mode in
\TeX{} and
\LaTeX{} which are
696 particularly useful for more complex typesetting tasks. To learn more about
697 it, you should consult the documentation
698 \uaref{q:intro_tex_latex
}.
701 \question{a
}{Why do environments like itemize or eqnarray seem not to work?
}
703 {An itemize environment might result in a
\LaTeX{} error complaining about
704 a ``
\texttt{missing
\cs item
}'' or an eqnarray might lead to a
\LaTeX{} message
705 ``
\texttt{missing
\cs endgroup inserted
}'' even though the syntax appears to be
706 correct. The
\TeX{}nical reason is that in
\PyX{} text is typeset in left-right
707 mode (LR mode) which does not allow linebreaks to occur. There are two ways out.
709 If the text material should go in a box of given width, a parbox can be used
710 like in the following example:
712 text.set(mode="latex")\\
713 c = canvas.canvas()\\
715 c.text(
0,
0, r"
\cs begin
\cb{itemize
}\cs item a
\cs item b
\cs end
\cb{itemize
}",
[text.parbox(w)
])
718 Occasionally, one would like to have the box in which the text appears to be as
719 small as possible. Then the
\texttt{fancybox
} package developed by Timothy Van
720 Zandt is useful which provides several environments like
\texttt{Bitemize
} and
721 \texttt{Beqnarray
} which can be processed in LR mode. The relevant part of the
722 code could look like:
724 text.set(mode="latex")\\
725 text.preamble(r"
\cs usepackage
\cb{fancybox
}")\\
726 c = canvas.canvas()\\
727 c.text(
0,
0, r"
\cs begin
\cb{Bitemize
}\cs item a
\cs item b
\cs end
\cb{Bitemize
}")
729 Other environments provided by the
\texttt{fancybox
} package include
730 \texttt{Bcenter
},
\texttt{Bflushleft
},
\texttt{Bflushright
},
731 \texttt{Benumerate
}, and
\texttt{Bdescription
}. For more details, the
732 documentation of the package should be consulted.
735 \question{a
}{Font shape `OT1/xyz/m/n' undefined
}
737 {\label{q:fontshape_undefined
}
738 You have asked to use font
\texttt{xyz
} which is not available. Make sure that
739 you have this font available in Type1 format, i.e.\ there should be a
740 file
\texttt{xyz.pfb
} somewhere. If your
\TeX{} system is TDS compliant
741 (TDS=
\TeX{} directory structure, cf.\
\ctan{tds/draft-standard/tds/tds.pdf
})
742 you should take a look at the subdirectories of
743 \path{TEXMF/fonts/type1
}.
746 \question{a
}{File
\dots\ is not available or not readable
}
749 Such an error message might already occur when running the example file
750 \texttt{hello.py
} included in the
\PyX{} distribution. Usually, the error
751 occurs due to an overly restrictive umask setting applied when unpacking the
752 \texttt{tar.gz
} sources. This may render the file mentioned in the error
753 message unreadable because the python distutil installation package doesn't
754 change the file permissions back to readable for everyone.
756 If the file exists, the problem can be solved by changing the permissions to
759 \question{a
}{No information for font `cmr10' found in font mapping
763 Such an error message can already be encountered by simply running the example
764 file
\texttt{hello.py
} included in the
\PyX{} distribution. The likely reason
765 is that the
\TeX{} system does not find the cmr fonts in Type1 format.
766 \PyX{} depends on these fonts as it does not work with the traditional
767 pk fonts which are stored as bitmaps.
769 Therefore, the first thing to make sure is that the cmr Type1 fonts are
770 installed. In some
\TeX{} installations, the command
\texttt{kpsewhich
771 cmr10.pfb
} will return the appropriate path if the cmr fonts exist in the
772 binary Type1 format (extension
\texttt{pfb
}) required by
\PyX. If the command
773 does not work but the TeX
{} system is TDS compliant
774 (
\uaref{q:fontshape_undefined
}), a look should be taken at
775 \path{TEXMF/fonts/type1/bluesky/cm
} where
\texttt{TEXMF
} is the root of the
778 If the Type1 fonts do not exist on the system, they may be obtained from
779 the CTAN
\uaref{q:ctan
} at
\ctan{fonts/cm/ps-type1/bluesky
}. See the
780 \texttt{README
} for information about who produced these fonts and why they
781 are freely available.
783 If the Type1 fonts exist, the next step is to take a look at
784 \texttt{psfonts.map
}. There may be several files with this name on the system,
785 so it is important to find out which one TeX is actually using.
786 \texttt{kpsewhich psfonts.map
} might give this information.
788 The most likely problem is that this file does not contain a line telling TeX
789 what to do if it encounters a request for font
\texttt{cmr10
}, i.e. the
793 ~~~cmr10~~~~~~~~~~~CMR10~~~~~~~~~~~<cmr10.pfb
795 It is probable that the required lines (in practice, you do not just need
796 \texttt{cmr10
}) are found in a file named
\texttt{psfonts.cmz
} which resides in
797 \path{TEXMF/
dvips/bluesky
}.
799 One solution is to instruct
\PyX{} to read additional map files like
800 \texttt{psfonts.cmz
} or
\texttt{psfonts.amz
}. This can be achieved by modifying
801 the appropriate
\texttt{pyxrc
} file which is either the systemwide
802 \texttt{/etc/pyxrc
} or
\texttt{.pyxrc
} in the user's home directory. Here, the
803 names of the map files to be read by
\PyX{} should be appended separated by
804 whitespaces like in the following example:
807 fontmaps = psfonts.map psfonts.cmz psfonts.amz
809 The same effect can be achieved by inserting the following line into the
812 text.set(fontmaps="psfonts.map psfonts.cmz psfonts.amz")
814 Note that the default map (psfonts.map) has to be specified explicitly.
816 An alternative approach consists in modifying the
\TeX{} installation by
817 inserting the contents of the desired map files like
\texttt{psfonts.cmz
} into
818 \texttt{psfonts.map
}. Probably,
\texttt{psfonts.map
} recommends not to do this
819 by hand. In this case the instructions given in the file should be followed.
820 Otherwise,
\texttt{psfonts.cmz
} should be copied into
\texttt{psfonts.map
} while
821 keeping a backup of the old
\texttt{psfonts.map
} just in case. After these
822 changes,
\PyX{} most likely will be happy. When inserting
\texttt{psfonts.cmz
}
823 into
\texttt{psfonts.map
} it may be a good idea to include
\texttt{psfonts.amz
}
824 as well.
\texttt{psfonts.amz
} contains information about some more fonts which
825 might be needed at some point. Making these changes ot
\texttt{psfonts.map
}
826 will imply that the
\TeX{} system will use the cmr fonts in Type1 format
827 instead of pk format which is actually not a bad thing, in particular if
828 \texttt{latex
}~/
\texttt{dvips}~/
\texttt{ps2pdf
} is used to generate PDF
829 output. With fonts in pk format this will look ugly and using Type1 fonts
830 solves this problem as well. When
\texttt{pdflatex
} is used to create PDF files,
831 Type1 fonts will be used anyway.
836 \question{t
}{I have Type1 fonts in
\texttt{pfa
} format. How do I obtain the
837 corresponding
\texttt{pfb
} files needed by
\PyX?
}
842 \question{a
}{I want to use a font other than computer modern roman
}
844 {\label{q:other_font
}
845 As long as you have a font in Type1 format available, this should be no
846 problem (even though it may cost you some time to set up things properly).
848 In the simplest case, your
\LaTeX{} system contains everything needed.
849 Including the following line into your code will probably work
851 text.set(mode="latex")\\
852 text.preamble(r"
\cs{usepackage
}\cb{mathptmx
}")
854 and give you Times as roman font.
856 If you own one of the more common commercial fonts, take a look at
857 \ctan{fonts
} and its subdirectories as well as at the web page
858 \url{http://home.vr-web.de/was/fonts.html
} of Walter Schmidt. It is not
859 unlikely that somebody has already done most of the work for you and created
860 the files needed for the font to work properly with
\LaTeX. But remember:
861 we are talking about commercial fonts here, so do not expect to find the fonts
864 If none of these cases applies, you should spend some time reading
865 manuals about font installation, e.g.\
\ctan{macros/latex/doc/fntguide.pdf
}
866 (of course, I do not expect font wizards to read the last few lines).
869 \question{a
}{Can I use a TrueType font with
\PyX?
}
871 {Not directly as
\PyX{} only knows how to handle Type1 fonts (although it is
872 possible to get
\LaTeX{} to work with TrueType fonts). However, you may use
873 \texttt{ttf2pt1
} (from
\url{http://ttf2pt1.sourceforge.net
}) to convert a
874 TrueType font into a Type1 font which you then install in your
\TeX{} system
875 \uaref{q:other_font
}. You will loose hinting information
876 in the conversion process but this should not really matter on output devices
877 with not too low resolution.