a few new questions

[PyX/mjg.git] / faq / pyxfaq.tex

% $Id$
\documentclass[11pt,DIV14]{scrartcl}
\usepackage[latin1]{inputenc}
\usepackage{url}
\usepackage{mathptmx}
%\usepackage[all,comments]{glifaq}
\usepackage[answered]{glifaq}
\usepackage[pdftex]{hyperref}
\hypersetup{pdftitle={PyX FAQ}%
            ,pdfauthor={\textcopyright\ Gert-Ludwig Ingold
                       <gert.ingold@physik.uni-augsburg.de>}%
            ,colorlinks=true%
            ,linkcolor=blue}
\def\pyxversion{\input{pyxversion}}
\begin{document}

\begin{center}
\LARGE\sffamily Some frequently and\\ 
not so frequently asked questions\\ 
about \PyX
\par
{\small\sffamily (version \pyxversion)}\\[1truecm]
\large
Gert-Ludwig Ingold \par
\href{mailto:gert.ingold@physik.uni-augsburg.de}{\url{<gert.ingold@physik.uni-augsburg.de>}}
\end{center}
\toc

\vspace{2truecm}
\section*{Acknowledgements}
The following persons have in one way or the other, e.g.\ by asking good 
questions or providing answers, contributed to this FAQ:\\ 
Walter Brisken, Pierre Joyot, Jörg Lehmann, John Owens, Michael Schindler, 
Gerhard Schmid, Andr{\'e} Wobst.
\newpage

\section{General aspects of \PyX}
\question{a}{The name of the game}
{}
{Originally, the name \PyX{} was constructed as a combination of 
\textbf{P}ostscript, i.e.\ the first output format supported by \PyX{}, 
P\textbf{y}thon, i.e.\ the language in which \PyX{} is written, and 
Te\textbf{X}, i.e.\ the program which \PyX{} uses for typesetting purposes. 
Actually, the title of this question is a tribute to \TeX{} because it is
taken from the first chapter of the \TeX{}book\footnote{D.~Knuth, \textit{The
\TeX{}book} (Addison-Wesley, 1984)} where the origin of the name \TeX{} and its 
pronunciation are explained.

Despite the ties between \TeX{} and \PyX{}, their pronunciation is quite
different. According to the developers of \PyX{}, it should be pronounced as 
\tipagraph{[pYks]}{tipapyks}. Please do not pronounce it as 
\tipagraph{[pYx]}{tipapyx} or \tipagraph{[pY\c c]}{tipapych}.
}

\question{a}{Where do I get the latest version of \PyX?}
{}
{\label{q:where_do_I_get_PyX}
The current release of \PyX{} (as well as older ones) is freely available 
from \url{http://pyx.sourceforge.net} where also a CVS repository with the 
latest patches can be found. Possibly older versions of \PyX{} are
also available as package for
various Linux distributions: see, for instance,  
\url{http://packages.debian.org/testing/python/python-pyx.html} for
information on the \PyX{} package in Debian GNU/Linux, 
\url{http://packages.gentoo.org/ebuilds/?pyx-0.7.1} for a Gentoo Linux
ebuild, and
\url{http://www.novell.com/products/linuxpackages/professional/python-pyx.html}
for the \PyX{} package in the SUSE LINUX professional distribution.
}

\question{c}{How can I determine the version of \PyX{} running on my 
machine?}
{}
{Start a python session (usually by typing \texttt{python} at the system 
prompt) and then type the following two commands (\texttt{>>>} is the python 
prompt)
\begin{progcode}
>>> import pyx\\
>>> pyx.\us\us{}version\us\us
\end{progcode}
}

\question{a}{How can I access older versions of \PyX?}
{}
{As at present it is not guaranteed that \PyX{} is backward compatible, it may
be desirable to access an older version of \PyX{} instead of adapting older 
code to the current version of \PyX. In order to do that, one needs the 
corresponding \PyX{} package (see \uaref{q:where_do_I_get_PyX} if you need to
download it), which should be unpacked below a directory, e.g.\ 
\texttt{/home/xyz/Python},  where you want to keep the various \PyX{} versions.
This will result in a subdirectory with a name like \texttt{PyX-0.8} which
contains the contents of the corresponding package. You can then ask Python to 
first look in the appropriate directory before looking for the current version 
of \PyX{} by inserting the following code (appropriately modified according 
to your needs) at the beginning of your program before importing the \PyX{} 
module:
\begin{progcode}
import sys\\
sys.path.insert(0, "/home/xyz/Python/PyX-0.8")
\end{progcode}
Including appropriate lines even if the current version of \PyX{} is used, 
might turn out to be helpful when the current version has become an old 
version (unless you have no difficulties determining the \PyX{} version by 
looking at your code).

If your operating system supports path expansion, you might use as an
alternative:
\begin{progcode}
import sys, os\\
sys.path.insert(0, os.path.expanduser("\char126/Python/PyX-0.8"))
\end{progcode}
which will expand the tilde to your home directory.
}

\question{c}{Does \PyX{} run under my favorite operating system?}
{}
{Yes, if you have installed Python (\uaref{q:what_is_python})
and \TeX{} (\uaref{q:what_is_tex}). Both are available for
a large variety of operating systems so chances are pretty good that you will 
get \PyX{} to work on your system.
}

\question{c}{Under which versions of Python will \PyX{} run?}
{}
{\PyX{} is supposed to work with Python 2.1 and above. However, most of the
development takes place under the current production version of Python
(2.4.1 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 Python 2.1 and above using the latest bugfix
releases. \PyX{} will not work with earlier Python versions due
to missing language features. 

The version of your Python interpreter can be determined by calling 
it with the option \texttt{-V}. Alternatively, you can simply start the 
interpreter and take a look at the startup message. Note that there may be 
different versions of Python installed on your system at the same time. The
default Python version need not be the same for all users.
}

\question{a}{Does \PyX{} provide a GUI to view the produced image?}
{}
{No, \PyX{} itself does not provide a means to view the produced image. The 
result of a \PyX{} run is an EPS (= Encapsulated PostScript) file, a
PS (= PostScript) file or a PDF (= Portable Document Format) file, which can
be viewed, printed or imported into other applications.

There are several means of viewing PS and EPS files. A common way
would be to use \texttt{ghostview} which provides a user interface to
the PostScript interpreter \texttt{ghostscript}. More information
about this software, which is available for a variety of platforms,
can be found at \url{http://www.cs.wisc.edu/~ghost/}. If you do not
own a printer which is capable of printing PostScript files directly,
\texttt{ghostscript} may also be useful to translate PS and EPS files
produced by \PyX{} into something your printer will understand.

PDF files can be viewed by means of the \texttt{Adobe
Reader\textsuperscript{\textregistered}} 
available from
\url{http://www.adobe.com/products/acrobat/readstep2.html}. On systems
running X11, \texttt{xpdf} might be an alternative. It is available from
\url{http://www.foolabs.com/xpdf/}.}

\question{a}{Where can I get help if my question is not answered in this
FAQ?}
{}
{The \PyX{} sources contain a reference manual which is also available
online at \url{http://pyx.sourceforge.net/manual/}. Furthermore, there
exists a set of examples demonstrating various features of \PyX, which is
available in the sources or can be browsed at \url{http://pyx.sourceforge.net/examples.html}. 
If the feature you are looking for is among them, using the appropriate part 
of the example code or adapting it for your purposes may help.

There is also a user discussion list about \PyX{} which you can subscribe to
at \url{http://lists.sourceforge.net/lists/listinfo/pyx-user}. The archive of
the discussion list is available at \url{http://sourceforge.net/mailarchive/forum.php?forum_id=23700}.

Finally, it might be worth checking \url{http://pyx.sourceforge.net/pyxfaq.pdf}
for an updated version of this FAQ.
}

\section{Python}

\question{c}{What is Python?}
{}
{\label{q:what_is_python}
From \url{www.python.org}:
\begin{quote}
Python is an \textit{interpreted, interactive, object-oriented} programming 
language. It is often compared to Tcl, Perl, Scheme or Java.

Python combines remarkable power with very clear syntax. It has modules, 
classes, exceptions, very high level dynamic data types, and dynamic typing. 
There are interfaces to many system calls and libraries, as well as to various 
windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules are easily 
written in C or C++. Python is also usable as an extension language for 
applications that need a programmable interface.

The Python implementation is portable: it runs on many brands of UNIX, on 
Windows, OS/2, Mac, Amiga, and many other platforms. If your favorite system 
isn't listed here, it may still be supported, if there's a C compiler for it. 
Ask around on \href{news:comp.lang.python}{news:comp.lang.python} --- or just 
try compiling Python yourself.

The Python implementation is 
\href{http://www.python.org/doc/Copyright.html}{copyrighted} 
but \textbf{freely usable and distributable, even for commercial use}.
\end{quote}
}

\question{a}{Where can I learn more about Python?}
{}
{The place to start is \url{www.python.org} where you will find plenty of
information on Python including tutorials.
}

\question{c}{What do I need to import in order to use \PyX?}
{}
{It is recommended to begin your Python code with 
\begin{progcode}
from pyx import *
\end{progcode}
when using \PyX. This allows you for example to write simply 
\texttt{graph.graphxy}
instead of \texttt{pyx.graph.graphxy}. The following modules will be loaded:
\texttt{attr}, \texttt{box}, \texttt{bitmap}, \texttt{canvas}, \texttt{color}, \texttt{connector},
\texttt{deco}, \texttt{deformer}, \texttt{document}, \texttt{epsfile}, \texttt{graph}, \texttt{path},
\texttt{pattern}, \texttt{style}, \texttt{trafo},  \texttt{text}, and \texttt{unit}.

For convenience, you might import specific objects of a module like in
\begin{progcode}
from graph import graphxy
\end{progcode}
which allows you to write \texttt{graphxy()} instead of \texttt{graph.graphxy()}.

All code segments in this document assume that the import line mentioned in
the first code snippet is present.
}

\question{a}{What is a raw string and why should I know about it when
  using \PyX?}
{}
{\label{q:raw_string}
The backslash serves in standard Python strings to start an escape sequence.
For example {\cs n} corresponds to a newline character. On the other hand,
\TeX{} and \LaTeX{}, which do the typesetting in \PyX, use the backslash to
indicate the start of a command. In order to avoid the standard interpretation,
the string should be marked as a raw string by prepending it by an \texttt{r} 
like in
\begin{progcode}
c.text(0, 0, r"\${\cs alpha}{\cs beta}{\cs gamma}\$")
\end{progcode}
}

\section{General aspects of plotting with \PyX}

\question{a}{How do I generate multipage output?}
{}
{
With versions 0.8 and higher it is possible to produce multipage output,
i.e. a Postscript or PDF file containing more than one page. In order to
achieve this, one creates pages by drawing on a canvas as usual and 
appends them in the desired order to a document from which Postscript or
PDF output is produced. The following example serves as an illustration:
\begin{progcode}
from pyx import *\\
\\
d = document.document()\\
for i in range(3):\\
~~~~c = canvas.canvas()\\
~~~~c.text(0, 0, "page \%i" \% (i+1))\\
~~~~d.append(document.page(c, paperformat=document.paperformat.A4,\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~margin=3*unit.t\_cm,\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~fittosize=1))\\
d.writePSfile("multipage")
\end{progcode}
Here, \texttt{d} is the document into which pages are inserted by means
of the \texttt{append} method. When converting from a canvas to a document
page, the page properties like the paperformat are specified. In the last 
line, output is produced from document \texttt{d}.
}

\section{Plotting of graphs}

\subsection{General aspects}

\question{c}{How do I generate a graph from data as simply as possible?}
{}
{\label{q:mingraphdata}
Suppose that you have a data file \texttt{x.dat} containing values for
$x$ and $y$ in two columns. Then the following code will do the job
\begin{progcode}
from pyx import *\\
\\
g = graph.graphxy(width=10)\\
g.plot(graph.data.file("x.dat", x=1, y=2))\\
g.writeEPSfile("x")
\end{progcode}
\texttt{graphxy} creates a canvas (called \texttt{g} in this example) onto 
which the graph will be drawn and it sets the default behavior including the 
axis. There is, however, no default value for the width of the graph. In 
\texttt{plot} you have to specify the name of the data file and the columns 
from which the data should be taken. Finally, \texttt{writeEPSfile} will 
generate the postscript file \texttt{x.eps} which you can view or print.

A minimal example is also provided in the \PyX{} distribution as 
\path{examples/graphs/minimal.py}.
}

\question{a}{How do I generate a graph of a function as simply as possible?}
{}
{\label{q:mingraphfunc}
The following example will draw a parabola:
\begin{progcode}
from pyx import *\\
\\
g = graph.graphxy(width=10,\\
~~~~~~~~~~~~~~~~~~x=graph.axis.linear(min=-2, max=2)\\
~~~~~~~~~~~~~~~~~~)\\
\\
g.plot(graph.data.function("y(x)=x**2"))\\
\\
g.writeEPSfile("x")
\end{progcode}
Most of the code has been explained in \uaref{q:mingraphdata}. The main 
difference is that here you need to specify minimum and maximum for the 
$x$-axis so that \PyX{} knows in which range to evaluate the function.

Another, slightly more complex, example is also provided in the \PyX{} 
distribution as \path{examples/graphs/piaxis.py}.
}

\question{a}{How can I stack graphs?}
{}
{\PyX{} always needs a canvas to draw on. One possibility therefore consists
in creating a new canvas with
\begin{progcode}
c = canvas.canvas()
\end{progcode}
and inserting the graphs into this canvas with \texttt{c.insert(...)}. Here,
\texttt{...} has to be replaced by the name of the graph. Alternatively, the
canvas created with \texttt{graph.graphxy} for one of the graphs can be used
to insert the other graphs even if they will be positioned outside the
first graph.

The second issue to address is positioning of the graphs. By specifying
\texttt{xpos} and \texttt{ypos} when calling \texttt{graphxy}, you can
define the position of a graph. Later on, the position and size of a 
graph \texttt{g} can be referred to as \texttt{g.xpos}, \texttt{g.ypos},
\texttt{g.width}, and \texttt{g.height} even if for example the height has 
never been specified explicitly but is only defined by a \PyX{} default. 

The following example shows how to put graph \texttt{gupper} above graph 
\texttt{glower} on a canvas \texttt{c}:
\begin{progcode}
from pyx import *\\
from graph import graphxy\\
\\
c = canvas.canvas()\\
\\
glower = graphxy(width=10)\\
glower.plot(...)\\
c.insert(glower)\\
\\
gupper = graphxy(width=10, ypos=glower.ypos+glower.height+2)\\
gupper.plot(...)\\
\\
c.insert(gupper)\\
c.writeEPSfile(...)
\end{progcode}
where \texttt{...} has to be replaced by the appropriate information like
data and symbol specifications and the name of the output file. Here,
\texttt{c.insert} is used to actually insert the subcanvasses 
for the graphs into the main canvas \texttt{c} and \texttt{c.writeEPSfile}
in the last line requests to write the contents of this canvas to a file.

%In order to suppress the labels of the $x$-axis of the upper graph, use
%\begin{progcode}
%myaxispainter = graph.axispainter(labelattrs=None)
%
%gupper = graph.graphxy(...,
%                       x=graph.axis.linear(...,
%                                      part=graph.linpart(),
%                                       painter=myaxispainter)
%                       )
%\end{progcode}
}

\question{a}{How can I plot grid data?}
{}
{\PyX{} offers support for plotting three-dimensional data as two-dimensional
color plots or grey-scale plots and of vector fields by providing ways to
plot rectangles and arrows in graphs. 

We start by considering the task of creating a two-dimensional color plot by 
plotting a number of filled rectangles. One first needs to create a data set 
which consists of five entries per data point. These are the lower left corner 
$(x_\mathrm{min},y_\mathrm{min})$ and the upper right corner 
$(x_\mathrm{max},y_\mathrm{max})$ of the triangle and a value between 0 and 1 
determining the color via a \PyX{} color palette. The following code gives an 
idea of how to proceed:
\begin{progcode}
g.plot(graph.data.file("datafile.dat"), xmin=1, xmax=2, ymin=3, ymax=4, color=5),\\
~~~~~~~[graph.style.rect(color.palette.ReverseRainbow)]\\
~~~~~~)\\
g.dodata()
\end{progcode}
Here, we assume that the data are stored in \texttt{datafile.dat} and the
columns contain $x_\mathrm{min}$, $x_\mathrm{max}$, $y_\mathrm{min}$,
$y_\mathrm{max}$, and the color value in this order. The columns are
numbered from 1, since the 0th column contains the line number. To
determine the color, we use the \texttt{ReverseRainbow} palette. The
last line instructs \PyX{} to plot the rectangles before plotting the
axes. Otherwise, the axes might be covered partially by the rectangles
and, in particular, the ticks might not be visible. Gray-scale plots
can easily be generated by specifying the palette \texttt{Gray} or
\texttt{ReverseGray} (cf.\ appendix C of the manual for a list of
predefined palettes).

At first sight, it seems surprising that plotting of grid data requires
the specification of four coordinates for the rectangle. The reason is that
this allows to draw rectangles of varying sizes which may help to reduce the
size of the postscript file by combining rectangles of the same color in 
horizontal or vertical direction. For example, it may be sufficient to plot
a grey-scale image in a small number of grey shades and then combining
rectangles may be appropriate. Note, though, that this step is part of the
data creation and not preformed by \PyX{}. Another advantage of fully
specifying each rectangle is that it is straightforward to leave parts of the
graph blank.

The same ideas as for the color plot can be applied to plot vector fields where
each data point is represented by an arrow. In this case a data point is 
specified by the position of the arrow, its size and its direction as indicated
in the following code snippet:
\begin{progcode}
g.plot(graph.data.file("datafile.dat"), x=1, y=2, size=3, angle=4),\\
~~~~~~~[graph.style.arrow()]\\
~~~~~~)
\end{progcode}

Complete code examples can be found in \path{examples/graphs/mandel.py} and
\path{examples/graphs/arrows.py}\,.
}

\question{a}{How can I access points in problem coordinates of a graph?}
{}
{\label{q:problemcoord}
Sometimes it may be necessary to add graphical elements to a graph in addition
to the data or function(s) which have been plotted as described in 
\uaref{q:mingraphdata} and \uaref{q:mingraphfunc}. For a graph instance 
\texttt{g} the positioning can easily be done in canvas coordinates by making
use of the origin (\texttt{g.xpos}, \texttt{g.ypos}) and the width 
(\texttt{g.width}) and height (\texttt{g.height}) of the graph. 

Occasionally, it may be more convenient to specify the position of the 
additional material in terms of problem coordinates. However, this requires
that the mapping from problem coordinates to canvas coordinates is known.
By default this is not the case before the content of the canvas is written
to the output which is too late for our purpose. One therefore needs to 
explicitly instruct \PyX{} to determine this mapping. One possibility is to 
ask \PyX{} to finish the graph by means of \texttt{g.finish()}. Now, problem
coordinates can be used to insert additional material which will end up in
front of the graph. If this is not desired, one should only fix the layout
of the graph by means of \texttt{g.dolayout()}. Then, the additional material
can be put onto the canvas before the graph is drawn and it will therefore
appear behind the graph.

The conversion of problem coordinates (\texttt{px}, \texttt{py}) to canvas
coordinates (\texttt{x}, \texttt{y}) is performed as follows:
\begin{progcode}
x, y = g.pos(px, py)
\end{progcode}
By default, the problem coordinates will refer to the ranges of the $x$ and $y$
axes. If several axes with different ranges exist, the
instances of the desired axes should be passed to the \texttt{pos} method by 
means of the keyword arguments \texttt{xaxis} and \texttt{yaxis}.

We remark that the drawing of lines parallel to one of the axes at specific
problem coordinates can also be done by adapting the method described in
\uaref{q:zeroline}.
}

\question{t}{I would like a key for only some of my data sets. How do I do
that?}
{}
{
}

\subsection{Axis properties}

\question{a}{How do I specify the tick increment?}
{}
{In the partition of a linear axis, the increments associated with ticks,
subticks etc.\ can be specified as argument of \texttt{parter.linear}. In the
following example, ticks will be drawn at even values while subticks will
be drawn at all integers:
\begin{progcode}
from pyx.graph import axis\\
tg = graph.graphxy(width=10,\\
~~~~~~~~~~~~~~~~~~~x=axis.linear(min=1, max=10,\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~parter=axis.parter.linear(tickdist=[2,1]))\\
~~~~~~~~~~~~~~~~~~~)
\end{progcode}
}

\question{a}{How do I plot the zero line?}
{}
{
\label{q:zeroline}
\PyX{} releases before 0.6 offered the possibility to stroke a zero line by 
specifying \texttt{zeropathattrs} in the painter constructor. In more recent 
releases, one proceeds as follows. First one has to fix the layout information 
of the graph by means of the \texttt{finish} or \texttt{dolayout} method (see 
\ref{q:problemcoord} for a more detailed explanation). Then, the 
\texttt{xgridpath} or \texttt{ygridpath} method of a graph will return a grid 
path parallel to the $y$ or $x$ axis, respectively, at the specified $y$ value. 
As an example, a zero line in $x$ direction can be drawn as follows:
\begin{progcode}
g.finish()\\
g.stroke(g.ygridpath(0))
\end{progcode}
}

\question{a}{How can I add grid lines to a graph?}
{}
{
Specifying \texttt{gridattrs} for the painter of an axis will generate grid
lines orthogonal to this axis. At least an empty list is needed like in
\begin{progcode}
g = graph.graphxy(width=10,\\
~~~~~~~~~~~~~~~~~~x=graph.axis.linear(painter=graph.axis.painter.regular(gridattrs=[])),\\
~~~~~~~~~~~~~~~~~~y=graph.axis.linear()\\
~~~~~~~~~~~~~~~~~~)
\end{progcode}
where grid lines in vertical direction are drawn in default style.

Occassionally, one might want to draw grid lines corresponding to ticks and
subticks in a different style. This can be achieved by specifiying
changeable attributes using \texttt{changelist}. The following code
\begin{progcode}
my\_xpainter = graph.axis.painter.regular(gridattrs=\\
~~~~~~~~~~~~~~~~~~~~[attr.changelist([style.linestyle.solid, style.linestyle.dashed])]\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~)\\
my\_ypainter = graph.axis.painter.regular(gridattrs=\\
~~~~~~~~~~~~~~~~~~~~[attr.changelist([color.rgb.red, color.rgb.blue])]\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~)\\
\\
g = graph.graphxy(width=10,\\
~~~~~~~~~~~~~~~~~~x=graph.axis.linear(painter=my\_xpainter),\\
~~~~~~~~~~~~~~~~~~y=graph.axis.linear(painter=my\_ypainter)\\
~~~~~~~~~~~~~~~~~~)
\end{progcode}
will create vertical solid and dashed grid lines for ticks and subticks, 
respectively. The horizontal grid lines will be red for ticks and blue for
subticks. The changeable attributes are applied in a cyclic manner. Therefore, 
in this example grid lines at subsubticks would be plotted in the same style 
as for ticks. If this is not desired, the list of attributes should be extended 
by an appropriate third style. The keyword \texttt{None} will switch off
the respective level of grid lines in case you want to draw them only e.g.\
for ticks but not subticks.
}

\subsection{Data properties}

\question{a}{How do I choose the symbol and its attributes? \changed}
{}
{\label{q:choose_symbol}
Suppose a graph called \texttt{g} has been initialized, e.g.\ by using
\texttt{graph.graphxy}. Then, data and the style of their representation
in the graph are defined by calling \texttt{g.plot} like in the following
example in which filled circles are requested:
\begin{progcode}
g.plot(graph.data.file("test.dat"),\\
~~~~~~~[graph.style.symbol(graph.style.symbol.circle, symbolattrs=[deco.filled])]\\
~~~~~~~)
\end{progcode}
As another example, if the linewidth of the symbol is too thin for your 
purposes, you could use something like:
\begin{progcode}
[graph.style.symbol(graph.style.symbol.plus, 
   symbolattrs=[style.linewidth.Thick])]\\
\end{progcode}
}

\question{a}{How do I choose the color of the symbols?}
{}
{Colors are not properties of the symbol as such and can therefore not
be specified in \texttt{symbolattrs} directly. The color is rather related
to the plotting of the symbol as defined by \texttt{deco.stroked} or
\texttt{deco.filled}. With
\begin{progcode}
graph.style.symbol(graph.style.symbol.circle,\\
~~~~~~~~~~~~~~~~~~~symbolattrs=[deco.stroked([color.rgb.red]),\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~deco.filled([color.rgb.green])]\\
~~~~~~~~~~~~~~~~~~~)
\end{progcode}
you will obtain a circle filled in green with a red borderline.
}

\question{a}{How do I choose the line style?}
{}
{If you do not want to use symbols, you can set the line style as in this
example
\begin{progcode}
g.plot(graph.data.file("test.dat"),\\
~~~~~~~[graph.style.line([style.linewidth.Thin])]\\
~~~~~~~)
\end{progcode}
where the linewidth is set.

If you also want to use symbols, you can combine the symbol and the
line style as in
\begin{progcode}
g.plot(graph.data.file("test.dat"),\\
~~~~~~~[graph.style.line(lineattrs=[style.linewidth.Thin,\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~style.linestyle.dashed]),\\
~~~~~~~~graph.style.symbol(graph.style.symbolline.circle,\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~symbolattrs=[deco.filled])
~~~~~~~]
~~~~~~)
\end{progcode}
to plot the symbols on top of a thin, dashed line. You may alter the
order of the styles to plot the line on top of the symbols.
}

\question{a}{How can I change the color of symbols or lines according to a
palette? \new}
{}
{If several data sets should be plotted in different colors, one can specify
in \texttt{symbolattrs} and/or \texttt{lineattrs} a palette like 
\texttt{color.palette.Rainbow}. Equidistant colors are chosen spanning the 
palette from one end to the other.
}

\question{a}{How can I specify changing colors (or other attributes) for 
symbols or lines? \new}
{}
{In \texttt{symbolattrs} and/or \texttt{lineattrs} so-called changelist can
be used. As an example
\begin{progcode}
mystyle = graph.style.symbol(symbolattrs=\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~[attr.changelist([color.rgb.red, color.rgb.green])])\\
g.plot(graph.data.file("x.dat", x=1, y=2), [mystyle])\\
g.plot(graph.data.file("y.dat", x=1, y=2), [mystyle])\\
g.plot(graph.data.file("z.dat", x=1, y=2), [mystyle])
\end{progcode}
will switch between red and green symbols each time a new data set is 
plotted. Several changelists can be specified. They are cycled independently 
and need not be of the same length. It may be necessary to repeat attributes
in order that several changelists cooperate to produce the desired result.
A common situation is that one would like to cycle through a list of symbols
which should be used in alternating colors. This can be achieved with
the following code:
\begin{progcode}
mystyle = graph.style.symbol(\\
~~~~~~~~~~~~~~~~graph.style.symbol.changetriangletwice,\\
~~~~~~~~~~~~~~~~symbolattrs=[attr.changelist([color.rgb.red, color.rgb.green])])
\end{progcode}
which will produce a red triangle, a green triangle, a red circle, a green
circle and so on for diamond and square because \texttt{changetriangletwice}
lists each symbol twice. If instead of changing between colors
one would like to change between filled and open symbols, one can make use of
a predefined changelist
\begin{progcode}
mystyle = graph.style.symbol(\\
~~~~~~~~~~~~~~~~graph.style.symbol.changetriangletwice,\\
~~~~~~~~~~~~~~~~symbolattrs=[graph.style.symbol.changefilledstroked])
\end{progcode}
}

\section{Other plotting tasks}

\question{a}{How can I rotate text?}
{}
{Text can be written at an arbitrary angle by specifying the appropriate 
transformation as an attribute. The command
\begin{progcode}
c.text(0, 0, "Text", [trafo.rotate(60)])
\end{progcode}
will write at an angle of 60 degrees relative to the horizontal axis. If no
pivot is specified (like in this example), the text is rotated around the
reference point given in the first two arguments of \texttt{text}. In the
following example, the pivot coincides with the center of the text:
\begin{progcode}
c.text(0, 0, "Text", [text.halign.center,text.valign.middle,trafo.rotate(60)])
\end{progcode}
}

\question{a}{How can I clip a canvas? \new}
{}
{In order to use only a part of a larger canvas, one may want to clip it. This
can be done by creating a clipping object which is used when creating a canvas
instance:
\begin{progcode}
clippath = path.circle(0.,0.,1.)\\
clipobject = canvas.clip(clippath)\\
c = canvas.canvas([clipobject])
\end{progcode}
In this example, the clipping path used to define the clipping object is a 
circle.
}
\section{\TeX{} and \LaTeX{}}

\subsection{General aspects}

\question{a}{What is \TeX/\LaTeX{} and why do I need it?}
{}
{\label{q:what_is_tex}
\TeX{} is a high quality typesetting system developed by Donald E. Knuth 
which is available for a wide variety of operating systems. \LaTeX{} is a 
macro package originally developed by Leslie Lamport which makes life with 
\TeX{} easier, in particular for complex typesetting tasks. The current 
version of \LaTeX{} is referred to as \LaTeXe{} and offers e.g.\ improved 
font selection as compared to the older \LaTeX{} 2.09 which should no longer 
be used. 

All typesetting tasks in \PyX{} are finally handed over to \TeX{} (which is the
default) or \LaTeX{}, so that \PyX{} cannot do without it. On the other hand,
the capabilities of \TeX{} and \LaTeX{} can be used for complex tasks where
both graphics and typesetting are needed.
}

\question{a}{I don't know anything about \TeX{} and \LaTeX{}. Where can I read 
something about it?}
{}
{\label{q:intro_tex_latex}
Take a look at CTAN (\uaref{q:ctan}) where in \ctan{info}
you may be able to find some useful information. There exists for example 
``A Gentle Introduction to \TeX'' by M.~Doob (\ctan{gentle/gentle.pdf}) and
``The Not So Short Introduction to \LaTeXe'' 
(\ctan{info/lshort/english/lshort.pdf}) by T.~Oetiker et al. The latter has
been translated into a variety of languages among them korean (which you will
not be able to read unless you have appropriate fonts installed) and mongolian.

Of course, it is likely that these documents will go way beyond what you 
will need for generating graphics with \PyX{} so you don't have to read all
of it (unless you want to use \TeX{} or \LaTeX{} for typesetting which can be
highly recommended). 

There exists also a number of FAQs on \TeX{} at \ctan{help}.
}

\question{a}{What is CTAN?}
{}
{\label{q:ctan}
CTAN is the Comprehensive TeX Archive Network where you will find almost
everything related to \TeX{} and friends. The main CTAN servers are 
\url{tug.ctan.org}, \url{dante.ctan.org}, and \url{cam.ctan.org}. A list of 
FTP mirrors can be found at \ctan{CTAN.sites}. 

In this FAQ, \texttt{CTAN:} refers to the root of an anonymous ftp CTAN tree, 
e.g.\  \url{ftp://ctan.tug.org/tex-archive/}, 
\url{ftp://ftp.dante.de/tex-archive/},
and \url{ftp://ftp.tex.ac.uk/tex-archive/}. The links to CTAN in this document
point to one of these servers but you might consider using a FTP mirror closer
to you in order to reduce traffic load.
}

\question{a}{Is there support for Con\TeX{}t?}
{}
{No, and as far as I know there no plans to provide it in the near future. 
Given the close ties between Con\TeX{}t and Meta\-Post, Con\TeX{}t users 
probably prefer to stick with the latter anyway.
}

\subsection{\TeX{} and \LaTeX{} commands useful for \PyX}

\question{a}{How do I get a specific symbol with \TeX{} or \LaTeX?}
{}
{A list of mathematical symbols together with the appropriate command name
can be found at \ctan{info/symbols/math/symbols.ps}. A comprehensive list
containing more than 2500 symbols for use with \LaTeX{} can be obtained from 
\ctan{info/symbols/comprehensive/symbols-a4.pdf}. In some cases it might be 
necessary to install fonts or packages available from CTAN 
(\uaref{q:ctan}).
}

\subsection{\TeX{} and \LaTeX{} errors}

\question{a}{Undefined control sequence \cs{usepackage}}
{}
{\label{q:undefined_usepackage}
The command \cs usepackage is specific to \LaTeX{}. Since by default \PyX{}
uses \TeX{}, you have to specify the correct mode:
\begin{progcode}
text.set(mode="latex")
\end{progcode}
}

\question{a}{Undefined control sequence \cs{frac}}
{}
{\label{q:undefined_frac}
The command \cs frac is only available in \LaTeX{}. In \TeX{} you should
use \texttt{\cb{a\cs over b}} in math mode to produce ${a\over b}$. As an 
alternative you may ask for the \LaTeX{} mode as explained in 
\ref{q:undefined_usepackage}.
}

\question{a}{Missing \$ inserted}
{}
{You have specified \TeX- or \LaTeX-code which is only valid in math mode. 
Typical examples are greek symbols, sub- and superscripts or fractions. 

On the \PyX{} level, you can specify math mode for the whole string by using
\texttt{text.mathmode} as in
\begin{progcode}
c.text(0, 0, r"{\cs alpha}", text.mathmode)
\end{progcode}
Keep also in mind that the standard Python interpretation of the backslash as 
introducing escape sequences needs to be prevented 
\uaref{q:raw_string}.

On the \TeX/\LaTeX{} level you should enclose the commands requiring math
mode in \$'s. As an example, \texttt{\$\cs alpha\us i\hat j\$} will produce 
$\alpha_i^j$. This allows you to specify math mode also for substrings. There 
exist other ways to specify math mode in \TeX{} and \LaTeX{} which are 
particularly useful for more complex typesetting tasks. To learn more about 
it, you should consult the documentation 
\uaref{q:intro_tex_latex}. 
}

\question{a}{Why do environments like itemize or eqnarray seem not to work?}
{}
{An itemize environment might result in a \LaTeX{} error complaining about
a ``\texttt{missing \cs item}'' or an eqnarray might lead to a \LaTeX{} message
``\texttt{missing \cs endgroup inserted}'' even though the syntax appears to be
correct. The \TeX{}nical reason is that in \PyX{} text is typeset in left-right 
mode (LR mode) which does not allow linebreaks to occur. There are two ways out.

If the text material should go in a box of given width, a parbox can be used
like in the following example:
\begin{progcode}
text.set(mode="latex")\\
c = canvas.canvas()\\
w = 2\\
c.text(0, 0, r"\cs begin\cb{itemize}\cs item a\cs item b\cs end\cb{itemize}", [text.parbox(w)])
\end{progcode}

Occasionally, one would like to have the box in which the text appears to be as
small as possible. Then the \texttt{fancybox} package developed by Timothy Van
Zandt is useful which provides several environments like \texttt{Bitemize} and 
\texttt{Beqnarray} which can be processed in LR mode. The relevant part of the 
code could look like:
\begin{progcode}
text.set(mode="latex")\\
text.preamble(r"\cs usepackage\cb{fancybox}")\\
c = canvas.canvas()\\
c.text(0, 0, r"\cs begin\cb{Bitemize}\cs item a\cs item b\cs end\cb{Bitemize}")
\end{progcode}
Other environments provided by the \texttt{fancybox} package include 
\texttt{Bcenter}, \texttt{Bflushleft}, \texttt{Bflushright}, 
\texttt{Benumerate}, and \texttt{Bdescription}. For more details, the 
documentation of the package should be consulted.
}

\question{a}{Font shape `OT1/xyz/m/n' undefined}
{}
{\label{q:fontshape_undefined}
You have asked to use font \texttt{xyz} which is not available. Make sure that
you have this font available in Type1 format, i.e.\ there should be a 
file \texttt{xyz.pfb} somewhere. If your \TeX{} system is TDS compliant 
(TDS=\TeX{} directory structure, cf.\ \ctan{tds/draft-standard/tds/tds.pdf}) 
you should take a look at the subdirectories of 
\path{TEXMF/fonts/type1}.
}

\question{a}{File \dots\ is not available or not readable}
{}
{\label{q:no_lfs}
Such an error message might already occur when running the example file 
\texttt{hello.py} included in the \PyX{} distribution. Usually, the error 
occurs due to an overly restrictive umask setting applied when unpacking the 
\texttt{tar.gz} sources. This may render the file mentioned in the error 
message unreadable because the python distutil installation package doesn't 
change the file permissions back to readable for everyone. 

If the file exists, the problem can be solved by changing the permissions to 
allow read access.}

\question{a}{No information for font `cmr10' found in font mapping 
file}
{}
{\label{q:no_cmr10}
Such an error message can already be encountered by simply running the example
file \texttt{hello.py} included in the \PyX{} distribution. The likely reason
is that the \TeX{} system does not find the cmr fonts in Type1 format.
\PyX{} depends on these fonts as it does not work with the traditional
pk fonts which are stored as bitmaps.

Therefore, the first thing to make sure is that the cmr Type1 fonts are
installed. In some \TeX{} installations, the command \texttt{kpsewhich 
cmr10.pfb} will return the appropriate path if the cmr fonts exist in the 
binary Type1 format (extension \texttt{pfb}) required by \PyX. If the command 
does not work but the TeX{} system is TDS compliant 
(\uaref{q:fontshape_undefined}), a look should be taken at 
\path{TEXMF/fonts/type1/bluesky/cm} where \texttt{TEXMF} is the root of the 
\texttt{texmf} tree.

If the Type1 fonts do not exist on the system, they may be obtained from
the CTAN \uaref{q:ctan} at \ctan{fonts/cm/ps-type1/bluesky}. See the 
\texttt{README} for information about who produced these fonts and why they
are freely available.

If the Type1 fonts exist, the next step is to take a look at 
\texttt{psfonts.map}. There may be several files with this name on the system, 
so it is important to find out which one TeX is actually using. 
\texttt{kpsewhich psfonts.map} might give this information.

The most likely problem is that this file does not contain a line telling TeX
what to do if it encounters a request for font \texttt{cmr10}, i.e. the 
following line 
may be missing
\begin{progcode}
~~~cmr10~~~~~~~~~~~CMR10~~~~~~~~~~~<cmr10.pfb
\end{progcode}
It is probable that the required lines (in practice, you do not just need 
\texttt{cmr10}) are found in a file named \texttt{psfonts.cmz} which resides in 
\path{TEXMF/dvips/bluesky}. 

One solution is to instruct \PyX{} to read additional map files like 
\texttt{psfonts.cmz} or \texttt{psfonts.amz}. This can be achieved by modifying 
the appropriate \texttt{pyxrc} file which is either the systemwide 
\texttt{/etc/pyxrc} or \texttt{.pyxrc} in the user's home directory. Here, the 
names of the map files to be read by \PyX{} should be appended separated by 
whitespaces like in the following example:
\begin{progcode}
[text]\\
fontmaps = psfonts.map psfonts.cmz psfonts.amz
\end{progcode}
The same effect can be achieved by inserting the following line into the
\PyX{} code:
\begin{progcode}
text.set(fontmaps="psfonts.map psfonts.cmz psfonts.amz")
\end{progcode}
Note that the default map (psfonts.map) has to be specified explicitly.

An alternative approach consists in modifying the \TeX{} installation by 
inserting the contents of the desired map files like \texttt{psfonts.cmz} into 
\texttt{psfonts.map}. Probably, \texttt{psfonts.map} recommends not to do this 
by hand. In this case the instructions given in the file should be followed.  
Otherwise, \texttt{psfonts.cmz} should be copied into \texttt{psfonts.map} while 
keeping a backup of the old \texttt{psfonts.map} just in case. After these 
changes, \PyX{} most likely will be happy. When inserting \texttt{psfonts.cmz} 
into \texttt{psfonts.map} it may be a good idea to include \texttt{psfonts.amz} 
as well. \texttt{psfonts.amz} contains information about some more fonts which 
might be needed at some point. Making these changes ot \texttt{psfonts.map} 
will imply that the \TeX{} system will use the cmr fonts in Type1 format 
instead of pk format which is actually not a bad thing, in particular if 
\texttt{latex}~/ \texttt{dvips}~/ \texttt{ps2pdf} is used to generate PDF 
output. With fonts in pk format this will look ugly and using Type1 fonts 
solves this problem as well. When \texttt{pdflatex} is used to create PDF files, 
Type1 fonts will be used anyway.
}

\subsection{Fonts}

\question{t}{I have Type1 fonts in \texttt{pfa} format. How do I obtain the 
corresponding \texttt{pfb} files needed by \PyX?}
{}
{
}

\question{a}{I want to use a font other than computer modern roman}
{}
{\label{q:other_font}
As long as you have a font in Type1 format available, this should be no
problem (even though it may cost you some time to set up things properly).

In the simplest case, your \LaTeX{} system contains everything needed. 
Including the following line into your code will probably work
\begin{progcode}
text.set(mode="latex")\\
text.preamble(r"\cs{usepackage}\cb{mathptmx}")
\end{progcode}
and give you Times as roman font. 

If you own one of the more common commercial fonts, take a look at
\ctan{fonts} and its subdirectories as well as at the web page
\url{http://home.vr-web.de/was/fonts.html} of Walter Schmidt. It is not
unlikely that somebody has already done most of the work for you and created
the files needed for the font to work properly with \LaTeX. But remember:
we are talking about commercial fonts here, so do not expect to find the fonts
themselves for free.

If none of these cases applies, you should spend some time reading
manuals about font installation, e.g.\ \ctan{macros/latex/doc/fntguide.pdf}
(of course, I do not expect font wizards to read the last few lines).
}

\question{a}{Can I use a TrueType font with \PyX?}
{}
{Not directly as \PyX{} only knows how to handle Type1 fonts (although it is
possible to get \LaTeX{} to work with TrueType fonts). However, you may use
\texttt{ttf2pt1} (from \url{http://ttf2pt1.sourceforge.net}) to convert a 
TrueType font into a Type1 font which you then install in your \TeX{} system 
\uaref{q:other_font}. You will loose hinting information 
in the conversion process but this should not really matter on output devices 
with not too low resolution.
}

\end{document}