From 5f740a09f89c87af919104622096c3b9e3ba08d7 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Andr=C3=A9=20Wobst?= Date: Wed, 24 Mar 2004 15:27:43 +0000 Subject: [PATCH] convert manual to python documentation style git-svn-id: https://pyx.svn.sourceforge.net/svnroot/pyx/trunk/pyx@1522 069f4177-920e-0410-937b-c2a4a81bcd90 --- manual/.cvsignore | 2 +- manual/Makefile | 46 ++- manual/axis.tex | 1 + manual/graph.py | 4 + manual/graph.tex | 957 ----------------------------------------------------- manual/graph2.py | 5 + manual/manual.tex | 101 +++--- manual/runlatex.sh | 18 - manual/tex.tex | 303 ----------------- manual/tex1.py | 15 - manual/tex2.py | 51 --- 11 files changed, 105 insertions(+), 1398 deletions(-) create mode 100644 manual/axis.tex create mode 100755 manual/graph.py delete mode 100644 manual/graph.tex create mode 100755 manual/graph2.py rewrite manual/manual.tex (78%) delete mode 100755 manual/runlatex.sh delete mode 100644 manual/tex.tex delete mode 100755 manual/tex1.py delete mode 100755 manual/tex2.py diff --git a/manual/.cvsignore b/manual/.cvsignore index 8546ebf6..4c579e61 100644 --- a/manual/.cvsignore +++ b/manual/.cvsignore @@ -1 +1 @@ -*.out *.aux *.log *.dvi *.toc *.size *.eps *.ps *.pdf pyxversion.tex +*.eps *.png *.dat *.aux manual.dvi manual.ps manual.pdf manual mkhowto pyxversion.tex diff --git a/manual/Makefile b/manual/Makefile index c55beb8b..c5a0af2a 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -1,30 +1,54 @@ -default: manual.dvi +# You need mkhowto from the python distribution for creating this manual. +# Get a copy of a current python source archive and make a symbolic link +# from /Python-x.x.x/Doc/tools/mkhowto into this directory. +# Furthermore you need tex, latex2html and a few other things to build +# the manual (see the python documentation about creating documentations +# for details). + +default:dvi clean: - -rm -f manual.dvi manual.ps manual.pdf *.eps *.aux *.out *.toc *.log + -rm -fr manual.dvi manual.ps manual.pdf *.eps *.png manual all: make clean + make html make pdf + make dvi + make ps + +src=$(wildcard *.tex) pyxversion.tex -pdf: manual.pdf -ps: manual.ps -dvi: manual.dvi +dvi:manual.dvi +ps:manual.ps +pdf:manual.pdf +html:manual/manual.html -manual.pdf: manual.ps - ps2pdf -sPAPERSIZE=a4 manual.ps +manual.pdf: $(src) png + #for index-with-own-hyperrefs debugging, anybody interested? + #./mkhowto --a4 --pdf --keep manual.tex + ./mkhowto --a4 --pdf manual.tex manual.ps: manual.dvi dvips -o manual.ps manual.dvi -manual.dvi: $(wildcard *.tex) eps pyxversion.tex - ./runlatex.sh manual.tex - -rm -f manual.ps manual.pdf +manual.dvi: $(src) eps + ./mkhowto --a4 --dvi manual.tex + +manual/manual.html: $(src) eps + ./mkhowto --image-type png --favicon "/pyx.ico" \ + --up-link "/" --up-title "PyX homepage" \ + --html manual.tex pyxversion.tex: ../pyx/version.py - python -c "import sys;sys.path[:0]=[\"..\"];import pyx.version;print pyx.version.version" > pyxversion.tex + python -c "import sys;sys.path[:0]=[\"..\"];import pyx.version;print pyx.version.version+'%'" > pyxversion.tex eps: $(patsubst %.py, %.eps, $(wildcard *.py)) +png: $(patsubst %.py, %.png, $(wildcard *.py)) %.eps: %.py export PYTHONPATH=$(PWD)/.. ; python $^ + +%.png: %.eps + gs -dEPSCrop -dNOPAUSE -dQUIET -dBATCH -sDEVICE=png16m -sOutputFile=$@ -r600 $^ + diff --git a/manual/axis.tex b/manual/axis.tex new file mode 100644 index 00000000..4448af32 --- /dev/null +++ b/manual/axis.tex @@ -0,0 +1 @@ +\chapter{Axes\label{axis}} diff --git a/manual/graph.py b/manual/graph.py new file mode 100755 index 00000000..1f2929e1 --- /dev/null +++ b/manual/graph.py @@ -0,0 +1,4 @@ +from pyx import * +g = graph.graphxy(width=10) +g.plot(graph.data.file("graph.dat", x=1, y=2)) +g.writeEPSfile("graph") diff --git a/manual/graph.tex b/manual/graph.tex deleted file mode 100644 index 507bf602..00000000 --- a/manual/graph.tex +++ /dev/null @@ -1,957 +0,0 @@ -\chapter{Module graph: graph plotting} -\label{graph} -\section{Introductory notes} - -The graph module is considered to be in constant, gradual development. -For the moment we concentrate ourself on standard 2d xy-graphs taking -all kind of possible specialties into account like any number of axes. -Architectural decisions play the most substantial role at the moment -and have hopefully already been done that way, that their flexibility -will suffice for future usage in quite different graph applications, -\emph{e.g.} circular 2d graphs or even 3d graphs. We will describe -those parts of the graph module here, which are in a totally usable -state already and are hopefully not to be changed later on. However, -future developments certainly will cause some incompatibilities. At -least be warned: Nobody knows the hole list of things that will break. -At the moment, keeping backwards compatibility in the graph module is -not at all an issue. Although we do not yet claim any backwards -compatibility for the future at all, the graph module is certainly one -of the biggest construction sites within \PyX. - -The task of drawing graphs is splitted in quite some subtasks, which -are implemented by classes of its own. We tried to make those -components as independend as it is usefull and possible in order to -make them reuseable for different graph types. They are also -replaceable by the user to get more specialized graph drawing tasks -done without needing to implement a hole graph system. A major -abstraction layer are the so-called graph coordinates. Their range is -generally fixed to $[0;1]$. Only the graph does know about the -conversion between these coordinates and the position at the canvas -(the graph itself is its canvas, that can be inserted into another -canvas). By that, all other components can be reused for different -graph geometries. The interfaces between the components are documented -in docstrings of interface classes in the source. The interface -technique is used for documentation purposes only. For the user, the -most important informations (as described in the following) are the -parameters of the constructors of the various implementations of those -interface. They are documented in docstrings of the constructors of -the classes. While effort of clearing and documenting is still in -progress, some parts are already nicely documented as you may see by -using \verb|pydoc|. - -\section{Axes} -\label{graph:axes} - -A common feature of a graph are axes. An axis is responsible for the -conversion of values to graph coordinates. There are predefined axis -types, namely: -\begin{center} -\begin{tabular}{ll} -axis type&description\\ -\hline -\texttt{linaxis}&linear axis\\ -\texttt{logaxis}&logarithmic axis\\ -\end{tabular} -\end{center} - -Further axes types are available to support axes splitting and bar -graphs (other axes types might be added in the future as well), but -they behave quite different from the generic case and are thus -described separately below. - -You may use axes even without a graph, but drawing them along an -arbitrary path using the \verb|pathaxis| function. This function takes -an path and an axis as its first two arguments and the result can be -inserted into a canvas. The optional keyword argument \verb|direction| -can be set to \verb|1|(default) or \verb|-1| to place the labels to -the right (default) or left side of the path, respectively. - -\subsection{Axes properties} - -Global properties of an axis are set as named parameters in the axis -constructor. Both, the \verb|linaxis| and the \verb|logaxis|, have the -same set of named parameters listed in the following table: - -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -argument name&description\\ -\hline -\texttt{title}&axis title\\ -\texttt{min}&fixes axis minimum; if not set, it is automatically determined, but this might fail, for example for the $x$-range of functions, when it is not specified there\\ -\texttt{max}&as above, but for the maximum\\ -\texttt{reverse}&boolean; exchange minimum and maximum (might be used without setting minimum and maximum); if min>max and reverse is set, they cancel each other\\ -\texttt{divisor}&numerical divisor for the axis partitioning; default: \texttt{1}\\ -\texttt{suffix}&a suffix to indicate the divisor within an automatic axis labeling\\ -\texttt{density}&density parameter for the axis partition rating\\ -\texttt{maxworse}&number of trials with worse tick rating before giving up; default: \texttt{2}\\ -\texttt{manualticks}&a list of ticks (described below)\\ -\texttt{painter}&axis painter (described below)\\ -\texttt{texter}&texter for the axis labels (described below)\\ -\texttt{parter}&axis partitioner (described below)\\ -\texttt{rater}&partition rater (described below)\\ -\end{tabularx} -\medskip - -\subsection{Partitioning of axes} - -The definition of ticks and labels appropriate to an axis range is -called partitioning. The axis partioning within \PyX{} uses rational -arithmetics, which avoids any kind of rounding problems to the cost of -performance. The class \verb|frac| supplies a rational number. It can -be initialized by another \verb|frac| instance, a tuple of integers -(called enumerator and denominator), a float (which gets converted -into a frac with a finite resolution \verb|floatprecision| of 10 -digits per default) or a string with infinite precision (like -"1.2345e-100" or even "1/3"). However, a partitioning is composed out -of a sorted list of ticks, where the class \verb|tick| is derived from -\verb|frac| and has additional properties called \verb|ticklevel|, -\verb|labellevel|, \verb|label|, and \verb|labelattrs|. When the -\verb|ticklevel| or the \verb|labellevel| is \verb|None|, it just -means not present, \verb|0| means tick or label, respectively, -\verb|1| means subtick or sublevel and so on. When \verb|labellevel| -is not \verb|None|, a \verb|label| might be explicitly given, which -will get used as the text of that label. Otherwise the axis painter -has to create an appropriate text for the label. The \verb|labelattrs| -might specify some attributes for the label to be used by the -\verb|text| method of an \verb|texrunner| instance. - -You can pass a list of \verb|tick| instance to the \verb|manualticks| -argument of an axis. By that you can place ticks whereever you want. -Additionally you can use a partitioner to create ticks appropriate to -the axis range. This can be done by manually specifying distances -between ticks, subticks and so on. Alternatively there are automatic -axis partitioners available, which provide different partitions and -the rating of those different partitions by the \verb|rater| become -crucial. Note, that you can combine manually set ticks and a -partitioner. - -\subsubsection{Partitioning of linear axes} - -The class \verb|linpart| creates a linear partition as described by -named parameters of the constructor: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{tickdist}&\texttt{None}&distance between ticks, subticks, etc. (see comment below); when the parameter is \texttt{None}, ticks will get placed at labels\\ -\texttt{labeldist}&\texttt{None}&distance between labels, sublabels, etc. (see comment below); when the parameter is \texttt{None}, labels will get placed at ticks\\ -\texttt{labels}&\texttt{None}&set the text for the labels manually\\ -\texttt{extendtick}&\texttt{0}&allow for a range extention to include the next tick of the given level\\ -\texttt{extendlabel}&\texttt{None}&as above, but for labels\\ -\texttt{epsilon}&\texttt{1e-10}&allow for exceeding the range by that relative value\\ -\end{tabularx} -\medskip - -The \verb|ticks| and \verb|labels| can either be a list or just a -single entry. When a list is provided, the first entry stands for -the tick or label, respectively, the second for the subtick or -sublabel, and so on. The entries are passed to the constructor of a -frac instance, e.g. there can be tuples (enumerator, denominator), -strings, floats, etc. - -\subsubsection{Partitioning of logarithmic axes} - -The class \verb|logpart| create a logarithmic partition. The -parameters of the constructor of the class \verb|logpart| are quite -simular to the parameters of \verb|linpart| discussed above. Instead -of the parameters \verb|tickdist| and \verb|labeldist| the parameters -\verb|tickpos| and \verb|labelpos| are present. All other parameters -of \verb|logpart| do not differ in comparision to \verb|linpart|. The -\verb|tickdist| and \verb|labeldist| parameters take either a single -\verb|preexp| instance or a list of \verb|preexp| instances, where the -first stands for the ticks (labels), the second for subticks -(sublabels) and so on. A \verb|preexp| instance contains a list of -\verb|pres|, which are \verb|frac| instances defining some positions, -say $p_i$. Furthermore there is a \verb|frac| instance called -\verb|exp|, say $e$. Valid tick and label positions are then given by -$s^np_i$, where $n$ is an integer. - -\begin{center} -\begin{tabular}{ll} -name&values it descibes\\ -\hline -\texttt{pre1exp5}&1 and multiple of $10^5$\\ -\texttt{pre1exp4}&1 and multiple of $10^4$\\ -\texttt{pre1exp3}&1 and multiple of $10^3$\\ -\texttt{pre1exp2}&1 and multiple of $10^2$\\ -\texttt{pre1exp}&1 and multiple of $10$\\ -\texttt{pre125exp}&1, 2, 5 and multiple of $10$\\ -\texttt{pre1to9exp}&1, 2, \dots, 9 and multiple of $10$\\ -\end{tabular} -\end{center} - -\subsubsection{Automatic partitioning of linear axes} - -When no explicit axis partitioner is given in the constructor argument -\verb|part| of an linear axis, it is initialized with an automatic -partitioning scheme for linear axes. This scheme is provided by the -class \verb|autolinpart|, where the constructor takes the following -arguments: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{variants}&\texttt{defaultvariants}&list of possible values for the ticks parameter of \texttt{linpart} (labels are placed at the position of ticks)\\ -\texttt{extendtick}&\texttt{0}&allow for a range extention to include the next tick of the given level\\ -\texttt{epsilon}&\texttt{1e-10}&allow for exceeding the range by that relative value\\ -\end{tabularx} -\medskip - -The default value for the argument \verb|variants|, namely -\verb|defaultvariants|, is defined as a class variable of -\verb|autolinpart| and has the value \texttt{((frac(1, 1), frac(1, -2)), (frac(2, 1), frac(1, 1)), (frac(5, 2), frac(5, 4)), (frac(5, 1), -frac(5, 2)))}. This implies, that the automatic axis partitioning -scheme allows for partitions using (ticks, subticks) with at distances -(1, 1/2), (2, 1), (5/2, 5/4), (5, 5/2). This list must be sorted by -the number of ticks the entries will lead to. The given fractions are -automatically multiplied or divided by 10 in order to fit better to -the axis range. Therefore those additional partitioning possibilities -(infinte possibilities) must not be given explicitly. - -\subsubsection{Automatic partitioning of logarithmic axes} - -When no explicit axis partitioning is given in the constructor -argument \verb|part| of an logarithmic axis, it is initialized with an -automatic partitioning schemes for logarithmic axes. This scheme is -provided by the class \verb|autologpart|, where the constructor takes -the following arguments: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{variants}&\texttt{defaultvariants}&list of pairs with possible values for the ticks and labels parameters of \texttt{logpart}\\ -\texttt{extendtick}&\texttt{0}&allow for a range extention to include the next tick of the given level\\ -\texttt{extendlabel}&\texttt{None}&as above, but for labels\\ -\texttt{epsilon}&\texttt{1e-10}&allow for exceeding the range by that relative value\\ -\end{tabularx} -\medskip - -The default value for the argument \verb|variants|, namely -\verb|defaultvariants|, is defined as a class variable of -\verb|autologpart| and has the value: -\begin{verbatim} -(((pre1exp, pre1to9exp), # ticks & subticks, - (pre1exp, pre125exp)), # labels & sublevels - ((pre1exp, pre1to9exp), None), # ticks & subticks, labels=ticks - ((pre1exp2, pre1exp), None), # ticks & subticks, labels=ticks - ((pre1exp3, pre1exp), None), # ticks & subticks, labels=ticks - ((pre1exp4, pre1exp), None), # ticks & subticks, labels=ticks - ((pre1exp5, pre1exp), None)) # ticks & subticks, labels=ticks -\end{verbatim} -As for the \verb|autolinaxis|, this list must be sorted by the number -of ticks the entries will lead to. - -\subsubsection{Rating of axes partitionings} - -When an axis partitioning scheme returns several partitioning -possibilities, the partitions are rated by an instance of a rater -class provided as the parameter \verb|rater| at the axis constructor. -It is used to calculate a positive rating number for a given axis -partitioning. In the end, the lowest rated axis partitioning gets -used. - -The rating consists of two steps. The first takes into account only -the number of ticks, subticks, labels and so on in comparison to an -optimal number. Additionally, the transgression of the axis range by -ticks and labels is taken into account. This rating leads to a -preselection of possible partitions. In the second step the layout of -a partition gets acknowledged by rating the distance of the labels to -each other. Thereby partitions with overlapping labels get quashed -out. - -The class \verb|axisrater| implements a rating with quite some -parameters specifically adjusted to linear and logarithmic axes. A -detailed description of the hole system goes beyond the scope of that -manual. Take your freedom and have a look at the \PyX{} source code if -you wish to adopt the rating to personal preferences. - -The overall optimal partition properties, namely the density of ticks -and labels, can be easily adjusted by the single parameter -\verb|density| of the axis constructor. The rating is -adjusted to the default densitiy value of \verb|1|, but modifications -of this parameter in the range of 0.5 (for less ticks) to 2 or even 3 -(for more ticks) might be usefull. - -\subsection{Creating label text} - -When a partition is created, the typical situation is that some of the -ticks have a \verb|labellevel| not equal to \verb|None| but there is -no \verb|label| (a string) defined to be printed at this tick. The -task of a \verb|texter| is to create those label strings for a given -list of ticks. There are different \verb|texter| classes creating -different label strings. - -\subsubsection{Decimal numbers} - -The class \verb|decimaltexter| creates decimal labels. The format of -the labels can be configured by numerous arguments of the constructor -listed in the following table: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{prefix}&\texttt{""}&string to be inserted in front of the number\\ -\texttt{infix}&\texttt{""}&string to be inserted between the plus or minus sign and the number\\ -\texttt{suffix}&\texttt{""}&string to be inserted after the number\\ -\texttt{equalprecision}&\texttt{0}&forces a common number of digits after the comma\\ -\texttt{decimalsep}&\texttt{"."}&decimal separator\\ -\texttt{thousandsep}&\texttt{""}&thousand separator\\ -\texttt{thousandthpartsep}&\texttt{""}&thousandth part separator\\ -\texttt{plus}&\texttt{""}&plus sign\\ -\texttt{minus}&\texttt{"-"}&minus sign\\ -\texttt{period}&\texttt{r"\textbackslash overline\{\%s\}"}&format string to indicate a period\\ -\texttt{labelattrs}&\texttt{text.mathmode}&a single attribute or a list of attributes to be added to the labelattrs\\ -\end{tabularx} -\medskip - -\subsubsection{Decimal numbers with an exponential} - -The class \verb|exponentialtexter| creates decimal labels with an -exponent. The format of the labels can be configured by numerous -arguments of the constructor listed in the following table: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{plus}&\texttt{""}&plus sign for the exponent\\ -\texttt{minus}&\texttt{"-"}&minus sign for the exponent\\ -\texttt{mantissaexp}&\texttt{r"\{\{\%s\}\textbackslash cdot10\textasciicircum\{\%s\}\}"}&format string for manissa and exponent\\ -\texttt{skipexp0}&\texttt{r"\{\%s\}}&format string for manissa, when exponent is \texttt{0}; use \texttt{None} to turn off this feature\\ -\texttt{skipexp1}&\texttt{None}&as \texttt{skipexp0}, but for exponent \texttt{1}\\ -\texttt{nomantissaexp}&\texttt{r"\{10\textbackslash\{\%s\}\}"}&format string when skipping a manissa equals 1\\ -\texttt{minusnomantissaexp}&\texttt{r"\{-1\textbackslash\{\%s\}\}"}&format string when skipping a manstissa equals -1\\ -\texttt{mantissamin}&\texttt{frac((1, 1))}&minimal value for the mantissa\\ -\texttt{mantissamax}&\texttt{frac((10, 1))}&maximal value for the mantissa\\ -\texttt{skipmantissa1}&\texttt{0}&skip mantissa equals 1\\ -\texttt{skipallmantissa1}&\texttt{1}&skip mantissa when its always 1\\ -\texttt{mantissatexter}&\texttt{decimaltexter()}&texter for the mantissa\\ -\end{tabularx} -\medskip - -\subsubsection{Decimal numbers without or with an exponential} - -The class \verb|defaulttexter| creates decimal labels without or -with an exponent. As the name says, its used as the default texter. -The texter splits the tick list into two lists, one to be passed to a -decimal texter and another to be passed to an exponential texter. This -splitting is based on the two properties \verb|smallestdecimal| and -\verb|biggestdecimal|. See the following table for all available -arguments: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{smallestdecimal}&\texttt{frac((1, 1000))}&the smallest number (ignoring the sign) where the decimal texter should be used\\ -\texttt{biggestdecimal}&\texttt{frac((9999, 1))}&as above, but for the biggest number\\ -\texttt{equaldecision}&\texttt{1}&either use the \texttt{decimaltexter} or the \texttt{exponentialtexter}\\ -\texttt{decimaltexter}&\texttt{decimaltexter()}&texter withoud an exponential\\ -\texttt{exponentialtexter}&\texttt{exponentialtexter()}&exponential with an exponential\\ -\end{tabularx} -\medskip - -\subsubsection{Rational numbers} - -The class \verb|rationaltexter| creates rational labels. The format of -the labels can be configured by numerous arguments of the constructor -listed in the following table: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{prefix}&\texttt{""}&string to be inserted in front of the rational\\ -\texttt{infix}&\texttt{""}&string to be inserted between the plus or minus sign and the rational\\ -\texttt{suffix}&\texttt{""}&string to be inserted after the rational\\ -\texttt{enumprefix}&\texttt{""}&as \texttt{prefix} but for the enumerator\\ -\texttt{enuminfix}&\texttt{""}&as \texttt{infix} but for the enumerator\\ -\texttt{enumsuffix}&\texttt{""}&as \texttt{suffix} but for the enumerator\\ -\texttt{denomprefix}&\texttt{""}&as \texttt{prefix} but for the denominator\\ -\texttt{denominfix}&\texttt{""}&as \texttt{infix} but for the denominator\\ -\texttt{denomsuffix}&\texttt{""}&as \texttt{suffix} but for the denominator\\ -\texttt{plus}&\texttt{""}&plus sign\\ -\texttt{minus}&\texttt{"-"}&minus sign\\ -\texttt{minuspos}&\texttt{0}&position of the minus: \texttt{0} -- in front of the fraction, \texttt{1} -- in front of the enumerator, \texttt{-1} -- in front of the denominator\\ -\texttt{over}&\texttt{r"\{\{\%s\}\textbackslash over\{\%s\}\}"}&format string for the fraction\\ -\texttt{equaldenom}&\texttt{0}&usually, the enumerator and the denominator are canceled; if set, take the least common multiple of all denominators\\ -\texttt{skip1}&\texttt{1}&skip printing the fraction for \texttt{1} when there is a \texttt{prefix}, \texttt{infix}, or \texttt{suffix}\\ -\texttt{skipenum0}&\texttt{1}&print \texttt{0} instead of a fraction when the enumerator is 0\\ -\texttt{skipenum1}&\texttt{1}&as \texttt{skip1} but for the enumerator\\ -\texttt{skipdenom1}&\texttt{1}&skip the denominator when it is \texttt{1} and there is no \texttt{denomprefix}, \texttt{denominfix}, or \texttt{denomsuffix}\\ -\texttt{labelattrs}&\texttt{text.mathmode}&a single attribute or a list of attributes to be added to the labelattrs\\ -\end{tabularx} -\medskip - -\subsection{Painting of axes} - -A major task for an axis is its painting. It is done by instances of -\verb|axispainter|, provided to the constructor of an axis as its -\verb|painter| argument. The constructor of the axis painter receives -a numerous list of named parameters to modify the axis look. A list of -parameters is provided in the following table: - -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -argument name&description\\ -\hline -\texttt{innerticklengths}$^{1,4}$&tick length of inner ticks (visual length);\newline default: \texttt{axispainter.defaultticklengths}\\ -\texttt{outerticklengths}$^{1,4}$&as before, but for outer ticks; default: \texttt{None}\\ -\texttt{tickattrs}$^{2,4}$&stroke attributes for ticks; default: \texttt{()}\\ -\texttt{gridattrs}$^{2,4}$&stroke attributes for grid paths; default: \texttt{None}\\ -\texttt{zeropathattrs}$^{3,4}$&stroke attributes for a grid path at axis value 0; default: \texttt{()}\\ -\texttt{basepathattrs}$^{3,4}$&stroke attributes for the axis base path;\newline default: \texttt{canvas.linecap.square}\\ -\texttt{labeldist}&label distance from axis (visual length); default: \texttt{"0.3 cm"}\\ -\texttt{labelattrs}$^{2,4}$&text attributes for labels;\newline default: \texttt{(text.halign.center, text.vshift.mathaxis)}\\ -\texttt{labeldirection}$^4$&relative label direction (see below); default: \texttt{None}\\ -\texttt{labelhequalize}&set width of labels to its maximum (boolean); default: \texttt{0}\\ -\texttt{labelvequalize}&set height and depth of labels to their maxima (boolean); default: \texttt{1}\\ -\texttt{titledist}&title distance from labels (visual length); default: \texttt{"0.3 cm"}\\ -\texttt{titleattrs}$^{3,4}$&text attributes for title; default: \texttt{(text.halign.center, text.vshift.mathaxis)}\\ -\texttt{titledirection}$^4$&relative title direction (see below);\newline default: \texttt{paralleltext}\\ -\texttt{titlepos}&title position in graph coordinates; default: \texttt{0.5}\\ -\end{tabularx} -\medskip - -$^1$ -The parameter should be a list, where the entries are attributes -for the different levels. When the level is larger then the list -length, \verb|None| is assumed. When the parameter is not a list, -it is applied to all levels.\\ -$^2$ -The parameter should be a list of lists, where the entries are -attributes for the different levels. When the level is larger then the -list length, \verb|None| is assumed. When the parameter is not a -list of lists, it is applied to all levels.\\ -$^3$ -The parameter should be a list. When the parameter is not a -list, the parameter is interpreted as a list with a single -entry.\\ -$^4$ -The feature can be turned off by the value \verb|None|. Within -lists or lists of lists, the value \verb|None| might be -used to turn off the feature for some levels selectively. -\medskip - -Relative directions for labels (\verb|labeldirection|) and titles -(\verb|titledirection|) are instances of \verb|rotatetext|. By that -the text direction is calculated relatively to the tick direction of -the axis and is added as an attribute of the text. The relative -direction provided by instances of the class \verb|rotatetext| prevent -upside down text by flipping it by 180 degrees. For convenience, the -two self-explanatory values \verb|rotatetext.parallel| and -\verb|rotatetext.orthogonal| are available, which are just instances of -rotatetext initializes by \verb|-90| degree and \verb|0|, -respectively. - -\subsection{Linked axes} - -Linked axes can be used whenever an axis should be repeated within a -single graph or even between different graphs although the intrinsic -meaning is to have only one axis plotted several times. Almost all -properties of a linked axis are supplied by the axis it is linked to -(you may call it the base axis), but some properties and methods might -be different. For the typical case (implemented by \verb|linkaxis|) -only the painter of the axis is exchanged together with some -simplified behaviour when finishing the axis (there is no need to -recalculate the axis partition etc.). The constructor of -\verb|linkaxis| takes the axis to be linked to as the first parameter -and in the named parameter \verb|painter| a new painter for the axis. -By default, \verb|linkaxispainter| is used, which differs from the -standard \verb|axispainter| by some default values for the arguments -only. Namely, the arguments \verb|zeropathattrs|, \verb|labelattrs|, -and \verb|titleattrs| are set to \verb|None| turing off these -features. - -The standard \verb|linkaxis| can be used for a \verb|linaxis| or -\verb|logaxis|, other axes might have different \verb|linkaxis| -classes, \emph{e.g. \texttt{linksplitaxis} and \texttt{linkbaraxis}}. -While those linked axes might be used by graphs to plot the same axis -at both sides of the graph (when appropriate), every axis has a -\verb|createlinkaxis| method, which returns a standard linked axis. - -\subsection{Special purpose axes} - -\subsubsection{Splitable axes} - -Axes with breaks are created by instances of the class -\verb|splitaxis|. Its constructor takes the following parameters: - -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -argument name&description\\ -\hline -(axis list)&a list of axes to be used as subaxes (this is the first parameter of the constructor; it has no name)\\ -\texttt{splitlist}&a single number or a list split points of the possitions of the axis breaks in graph coordinates; the value \texttt{None} forces \texttt{relsizesplitdist} to be used; default: \texttt{0.5}\\ -\texttt{splitdist}&gap of the axis break; default: \texttt{0.1}\\ -\texttt{relsizesplitdist}&used when \texttt{splitlist} entries are \texttt{None}; gap of the axis break in values of the surrounding axes (on logarithmic axes, a decade corresponds to 1); the split position is adjusted to give both surrounding axes the same scale (thus, their range must be completely fixed); default: \texttt{1}\\ -\texttt{title}&axis title\\ -\texttt{painter}&axis painter; default: \texttt{splitaxispainter()} (described below)\\ -\end{tabularx} -\medskip - -A split axis is build up from a list of ``subaxes''. Those subaxes -have to provide some range information needed to identify the subaxis -to be used out of a plain number (thus all axes minima and maxima has -to be set except for the two subaxes at the egde, where for the first -only the maximum is needed, while for the last only the minimum is -needed). The only point left is the description of the specialized -\verb|splitaxispainter|, where the constructor takes the following -parameters: - -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -argument name&description\\ -\hline -\texttt{breaklinesdist}&(visual) distance between the break lines; default: \texttt{0.05}\\ -\texttt{breaklineslength}&(visual) length of break lines; default: \texttt{0.5}\\ -\texttt{breaklinesangle}&angle of the breakline with respect to the axis; default: \texttt{-60}\\ -\texttt{breaklinesattrs}&stroke attributes for the break lines (\texttt{None} to turn off the break lines, otherwise a single value or a tuple); default: \texttt{()}\\ -\end{tabularx} - -Additionally, the painter takes parameters for the axis title -formatting like the standard axis painter class \verb|axispainter|. -(There is a common base class \verb|titleaxispainter| for that.) The -parameters are \verb|titledist|, \verb|titleattrs|, -\verb|titledirection|, and \verb|titlepos|. - -\subsubsection{Bar axes} - -Axes appropriate for bar graphs are created by instances of the class -\verb|baraxis|. Its constructor takes the following parameters: - -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -argument name&description\\ -\hline -\texttt{subaxis}&baraxis can be recursive by having another axis as its subaxis; default: \texttt{None}\\ -\texttt{multisubaxis}&contains another baraxis instance to be used to construct a new subaxes for each item (by that a nested bar axis with a different number of subbars at each bar can be created) ; default: \texttt{None}\\ -\texttt{title}&axis title\\ -\texttt{dist}&distance between bars (relative to the bar width); default: \texttt{0.5}\\ -\texttt{firstdist}&distance of the first bar to the border; default: \texttt{0.5*dist}\\ -\texttt{lastdist}&as before but for the last bar\\ -\texttt{names}&tuple of name identifiers for bars; when set, no other identifiers are allowed; default: \texttt{None}\\ -\texttt{texts}&dictionary translating names into label texts (otherwise just the names are used); default: \texttt{\{\}}\\ -\texttt{painter}&axis painter; default: \texttt{baraxispainter} (described below)\\ -\end{tabularx} -\medskip - -In contrast to other axes, a bar axis uses name identifiers to -calculate a position at the axis. Usually, a style appropriate to a -bar axis (this is right now just the bar style) set those names out of -the data it recieves. However, the names can be forced and fixed. - -Bar axes can be recursive. Thus for a given value, an appropriate -subaxis is choosen (usually another bar axis). Usually only a single -subaxis is needed, because it doesn't need to be painted and for each -value the same recursive subaxis transformation has to be applied. -This is achieved by using the parameter \verb|subaxis|. Alternatively -you may use the \verb|multisubaxis|. Here only a bar axis can be used. -Then the subaxes (note axes instead of axis) are painted as well -(however their painter can be set to not paint anything). For that, -duplications of the subaxis are created for each name. By that, each -subaxis can have different names, in particular different number of -names. - -The only point left is the description of the specialized -\verb|baraxispainter|. It works quite similar to the -\verb|axispainter|. Thus the constructors have quite some parameters -in common, namely \verb|titledist|, \verb|titleattrs|, -\verb|titledirection|, \verb|titlepos|, and \verb|basepathattrs|. -Furthermore the parameters \verb|innerticklength| and -\verb|outerticklength| work like their counterparts in the -\verb|axispainter|, but only plain values are allowed there (no -lists). However, they are both \verb|None| by default and no ticks -get plotted. Then there is a hole bunch of name -attribute identifiers, namely \verb|namedist|, \verb|nameattrs|, -\verb|namedirection|, \verb|namehequalize|, \verb|namevequalize| which -are identical to their counterparts called \verb|label...| instead of -\verb|name...|. Last but not least, there is a parameter \verb|namepos| -which is analogous to \verb|titlepos| and set to \verb|0.5| by -default. - -\section{Data} -\label{graph:data} - -\subsection{List of points} - -Instances of the class \verb|data| link together a \verb|datafile| (or -another instance of a class from the module \verb|data|) and a -\verb|style| (see below; default is \verb|symbol|). The link object is -needed in order to be able to plot several data from a singe file -without reading the file several times. However, for easy usage, it is -possible to provide just a filename instead of a \verb|datafile| -instance as the first argument to the constructor of the class -\verb|data| thus hiding the underlying \verb|datafile| instance -completely from view. This is the preferable solution as long as the -datafile gets used only once. - -The additional parameters of the constructor of the class \verb|data| -are named parameters. The values of those parameters describe data -columns which are linked to the names of the parameters within the -style. The data columns can be identified directly via their number or -title, or by means of mathematical expression (as in the addcolumn -method of the class \verb|data| in the module \verb|data|; see -chapter~\ref{module:data}; indeed a addcolumn call takes place to -evaluate mathematical expressions once and for all). - -The constructors keyword argument \verb|title| however does not -refer to a parameter of a style, but instead sets the title to be used -in the graph key. It might be set to \verb|None| to exclude the data -and style from the the graph key. - -\subsection{Functions} - -The class \verb|function| provides data generation out of a functional -expression. The default style for function plotting is \verb|line|. -The constructor of \verb|function| takes an expression as the first -parameter. The expression must be a string with exactly one equal sign -(\verb|=|). At the left side the result axis identifier must be placed -and at the right side the expression must depend on exactly one -variable axis identifier. Hence, a valid expression looks like -\verb|"y=sin(x)"|. You can access own variables and functions by -providing them as a dictionary to the constructors \verb|context| -keyword argument. - -Additional named parameters of the constructor are: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{min}&\texttt{None}&minimal value for the variable parameter; when \texttt{None}, the axis data range will be used\\ -\texttt{max}&\texttt{None}&as above, but for the maximum\\ -\texttt{points}&\texttt{100}&number of points to be calculated\\ -\texttt{parser}&\texttt{mathtree.parser()}&parser for the mathematical expression\\ -\texttt{context}&\texttt{None}&dictionary of extern variables and functions\\ -\texttt{title}&equal to the expression&title to be used in the graph key\\ -\end{tabularx} -\medskip - -The expression evaluation takes place at a linear raster on the -variable axis. More advanced methods (detection of rapidely changing -functions, handling of divergencies) are likely to be added in future -releases. - -\subsection{Parametric functions} - -The class \verb|paramfunction| provides data generation out of a -parametric representation of a function. The default style for -parametric function plotting is \verb|line|. The parameter list of the -constructor of \verb|paramfunction| starts with three parameters -describing the function parameter. The first parameter is a string, -namely the variable name. It is followed by a minimal and maximal -value to be used for that parameter. The next parameter contains an -expression assigning functions to the axis identifiers in a quite -pythonic tuple notation. As an example, such an expression could look -like \verb|"x, y = sin(k), cos(3*k)"|. - -Additionally, the named parameters \verb|points|, \verb|parser|, -\verb|context|, and \verb|title| behave like their equally named -counterparts in \verb|function|. - -\section{Styles} -\label{graph:styles} - -Styles are used to draw data at a graph. A style determines what is -painted and how it is painted. Due to this powerfull approach there -are already some different styles available and the possibility to -introduce other styles opens even more prospects. - -\subsection{Symbols} - -The class \verb|symbol| can be used to plot symbols, errorbars and lines -configurable by parameters of the constructor. Providing \verb|None| -to attributes hides the according component. - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{symbol}&\texttt{changesymbol.cross()}&symbol to be used (see below)\\ -\texttt{size}&\texttt{"0.2 cm"}&size of the symbol (visual length)\\ -\texttt{symbolattrs}&\texttt{deco.stroked}&draw attributes for the symbol\\ -\texttt{errorscale}&\texttt{0.5}&size of the errorbar caps (relative to the symbol size)\\ -\texttt{errorbarattrs}&\texttt{()}&stroke attributes for the errorbars\\ -\texttt{lineattrs}&\texttt{None}&stroke attributes for the line\\ -\end{tabularx} -\medskip - -The parameter \verb|symbol| has to be a routine, which returns a path to -be drawn (e.g. stroked or filled). There are several such routines -already available in the class \verb|symbol|, namely \verb|cross|, -\verb|plus|, \verb|square|, \verb|triangle|, \verb|circle|, and -\verb|diamond|. Furthermore, changeable attributes might be used here -(like the default value \verb|changesymbol.cross|), see -section~\ref{graph:changeattrs} for details. - -The attributes are available as class variables after plotting the -style for outside usage. Additionally, the variable \verb|path| -contains the path of the line (even when it wasn't plotted), which -might be used to get crossing points, fill areas, etc. - -Valid data names to be used when providing data to symbols are listed -in the following table. The character \verb|X| stands for axis names -like \verb|x|, \verb|x2|, \verb|y|, etc. - -\begin{center} -\begin{tabular}{ll} -data name&description\\ -\hline -\texttt{X}&position of the symbol\\ -\texttt{Xmin}&minimum for the errorbar\\ -\texttt{Xmax}&maximum for the errorbar\\ -\texttt{dX}&relative size of the errorbar: \texttt{Xmin, Xmax = X-dX, X+Xd}\\ -\texttt{dXmin}&relative minimum \texttt{Xmin = X-dXmin}\\ -\texttt{dXmax}&relative maximum \texttt{Xmax = X+dXmax}\\ -\end{tabular} -\end{center} - -\subsection{Lines} - -The class \verb|line| is inherited from the class \verb|symbol| and -restricted itself to line drawing. The constructor takes only the -\verb|lineattrs| keyword argment, which is by default set to -\verb|(changelinestyle(), style.linejoin.round)|. The other features -of the symbol style are turned off. - -\subsection{Rectangles} - -The class \verb|rect| draws filled rectangles into a graph. The size -and the position of the rectangles to be plotted can be provided by -the same data names like for the errorbars of the class \verb|symbol|. -Indeed, the class \verb|symbol| reuses most of the symbol code by -inheritance, while modifying the errorbar look into a colored filled -rectangle and turing off the symbol itself. - -The color to be used for the filling of the rectangles is taken from a -palette provided to the constructor by the named parameter -\verb|palette| (default is \verb|color.palette.Gray|). The data -name \verb|color| is used to select the color out of this palette. - -\subsection{Texts} - -Another style to be used within graphs is the class \verb|text|, which -adds the output of text to the class \verb|symbol|. The text -position relative to the symbol is defined by the two named -parameters \verb|textdx| and \verb|textdy| having a default of -\verb|"0 cm"| and \verb|"0.3 cm"|, respectively, which are by default -interpreted as visual length. A further named parameter -\verb|textattrs| may contain a list of text attributes (or just a -single attribute). The default for this parameter is -\verb|text.halign.center|. Furthermore the constructor of this class -allows all other attributes of the class \verb|symbol|. - -\subsection{Arrows} - -The class \verb|arrow| can be used to plot small arrows into a graph -where the size and direction of the arrows has to be given within the -data. The constructor of the class takes the following parameters: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{linelength}&\texttt{"0.2 cm"}&length of a the arrow line (visual length)\\ -\texttt{arrowattrs}&\texttt{()}&stroke attributes\\ -\texttt{arrowsize}&\texttt{"0.1 cm"}&size of the arrow (visual length)\\ -\texttt{arrowdict}&\texttt{\{\}}&attributes to be used in the \texttt{earrow} constructor\\ -\texttt{epsilon}&1e-10&smallest allowed arrow size factor for a arrow to become plotted (avoid numerical instabilities)\\ -\end{tabularx} -\medskip - -The arrow allows for data names like the symbol and introduces -additionally the data names \verb|size| for the arrow size (as an -multiplicator for the sizes provided to the constructor) and -\verb|angle| for the arrow direction (in degree). - -\subsection{Bars} - -The class \verb|bar| must be used in combination with an -\verb|baraxis| in order to create bar plots. The constructor takes the -following parameters: - -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -argument name&description\\ -\hline -\texttt{fromzero}&bars start at zero (boolean); default: \texttt{1}\\ -\texttt{stacked}&stack bars (boolean/integer); for values bigger than 1 it is the number of bars to be stacked; default: \texttt{0}\\ -\texttt{skipmissing}&skip entries in the bar axis, when datapoints are missing; default: \texttt{1}\\ -\texttt{xbar}&bars parallel to the graphs x-direction (boolean); default: \texttt{0}\\ -\texttt{barattrs}&fill attributes; default: \texttt{(deco.stroked(color.gray.black), changecolor.Rainbow())}\\ -\end{tabularx} - -Additionally, the bar style takes two data names appropriate to the -graph (like \verb|x|, \verb|x2|, and \verb|y|). - -\subsection{Iterateable style attributes} -\label{graph:changeattrs} - -The attributes provided to the constructors of styles can usually -handle so called iterateable attributes, which are changing itself -when plotting several data sets. Iterateable attributes can be easily -written, but there are already some iterateable attributes available -for the most common cases. For example a color change is done by -instances of the class \verb|colorchange|, where the constructor takes -a palette. Applying this attribute to a style and using this style at -a list of data, the color will get changed lineary along the -palette from one end to the other. The class \verb|colorchange| -includes inherited classes as class variables, which are called like -the color palettes shown in appendix~\ref{palettename}. For them the -default palette is set to the appropriate color palette. - -Another attribute changer is called \verb|changesequence|. The -constructor takes a list of attributes and the attribute changer -cycles through this list whenever a new attribute is requested. -This attribute changer is used to implement the following attribute -changers: - -\begin{center} -\begin{tabular}{ll} -attribute changer&description\\ -\hline -\texttt{changelinestyle}&iterates linestyles solid, dashed, dotted, dashdotted\\ -\texttt{changestrokedfilled}&iterates \texttt{(deco.stroked, deco.filled)}\\ -\texttt{changefilledstroked}&iterates \texttt{(deco.filled, deco.stroked)}\\ -\end{tabular} -\end{center} - -The class \verb|changesymbol| can be used to cycle throu symbols and it -provides already various specialized classes as class variables. To -loop over all available symbols (cross, plus, square, triangle, -circle, and diamond) the equal named class variables can be used. They -start at that symbol they are named of. Thus \verb|changesymbol.cross()| -cycles throu the list starting at the cross symbol. Furthermore -there are four class variables called \verb|squaretwice|, -\verb|triangletwice|, \verb|circletwice|, and \verb|diamondtwice|. -They cycle throu the four fillable symbols, but returning the symbols -twice before they go on to the next one. They are intented to be used -in combination with \verb|changestrokedfilled| and -\verb|changefilledstroked|. - -\section{Keys} - -Graph keys can be created by instances of the class \verb|key|. Its -constructor takes the following keyword arguments: - -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -argument name&description\\ -\hline -\texttt{dist}&(vertical) distance between the key entries (visual length); default: \texttt{"0.2 cm"}\\ -\texttt{pos}&\texttt{"tr"} (top right; default), \texttt{"br"} (bottom right), \texttt{"tl"} (top left), \texttt{"bl"} (bottom left)\\ -\texttt{hdist}&horizontal distance of the key (visual length); default: \texttt{"0.6 cm"}\\ -\texttt{vdist}&vertical distance of the key (visual length); default: \texttt{"0.4 cm"}\\ -\texttt{hinside}&align horizonally inside to the graph (boolean); default: \texttt{1}\\ -\texttt{vinside}&align vertically inside to the graph (boolean); default: \texttt{1}\\ -\texttt{symbolwidth}&width reserved for the symbol (visual length); default: \texttt{"0.5 cm"}\\ -\texttt{symbolheight}&height reserved for the symbol (visual length); default: \texttt{"0.25 cm"}\\ -\texttt{symbolspace}&distance between symbol and text (visual length); default: \texttt{"0.2 cm"}\\ -\texttt{textattrs}&text attributes (a list or a single entry); default: \texttt{text.vshift.mathaxis}\\ -\end{tabularx} -\medskip - -The data description to be printed in the graph key is given by the -title of the data drawn. - -\section{X-Y-Graph} - -The class \verb|graphxy| draws standard x-y-graphs. It is a subcanvas -and can thus be just inserted into a canvas. The x-axes are named -\verb|x|, \verb|x2|, \verb|x3|, \dots and equally the y-axes. The -number of axes is not limited. All odd numbered axes are plotted at -the bottom (for x axes) and at the left (for y axes) and all even -numbered axes are plotted opposite to them. The lower numbers are -closer to the graph. - -The constructor of \verb|graphxy| takes axes as named parameters where -the parameter name is an axis name as just described. Those parameters -refer to an axis instance as they where described in -section~\ref{graph:axes}. When no \verb|x| or \verb|y| is provided, -they are automatically set to instances of \verb|linaxis|. When no -\verb|x2| or \verb|y2| axes are given they are initialized as standard -linkaxis to the axis \verb|x| and \verb|y|. However, you can turn off -the automatism by setting those axes explicitly to \verb|None|. - -However, the constructor takes some more attributes listed in the -following table: - -\medskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -argument name&default&description\\ -\hline -\texttt{xpos}&\texttt{"0"}&x position of the graph (user length)\\ -\texttt{ypos}&\texttt{"0"}&y position of the graph (user length)\\ -\texttt{width}&\texttt{None}&width of the graph area (axes are outside of that range)\\ -\texttt{height}&\texttt{None}&as abovem, but for the height\\ -\texttt{ratio}&\texttt{goldenrule}&width/height ratio when only a width or height is provided\\ -\texttt{backgroundattrs}&\texttt{None}&background attributes for the graph area\\ -\texttt{axisdist}&\texttt{"0.8 cm"}&distance between axis (visual length)\\ -\texttt{key}&\texttt{None}&\texttt{key} instance for an automatic graph key\\ -\end{tabularx} -\medskip - -After a graph is constructed, data can be plotted via the \verb|plot| -method. The first argument should be an instance of the data providing -classes described in section~\ref{graph:data}. This first parameter -can also be a list of those instances when you want to iterate the -style you explicitly provide as a second parameter to the plot method. -The plot method returns the plotinfo instance (or a list of plotinfo -instances when a data list was provided). The plotinfo class has -attributes \verb|data| and \verb|style|, which provide access to the -plotted data and the style, respectively. Just as an example, from the -style you can access the path of the drawed line, fill areas with it -etc. - -After the plot method was called once or several times, you may -explicitly call the method \verb|finish|. Most of the graphs -functionallity becomes available just after (partially) finishing the -graph. A partial finish can even modify the order in which a graph -performs its drawing process. By default the five methods -\verb|dolayout|, \verb|dobackground|, \verb|doaxis|, \verb|dodata|, -and \verb|dokey| are called in that order. The method \verb|dolayout| -must always be called first, but this is internally ensured once you -call any of the routines yourself. After \verb|dolayout| gets called, -the method \verb|plot| can not be used anymore. - -To get a position within a graph as a tuple out of some axes values, -the method \verb|pos| can be used. It takes two values for a position -at the x and y axis. By default, the axes named \verb|x| or \verb|y| -are used, but this is changed when the keyword arguments \verb|xaxis| -and \verb|yaxis| are set to other axes. The graph axes are available -by their name using the dictionary \verb|axes|. There is also an -dictionary \verb|axespos|, which contains \verb|lineaxespos| instances -for all axes. They implement the \verb|_Iaxispos| interface, thus -having the following methods: - -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -method name&description\\ -\hline -\texttt{basepath(x1=None, x2=None)}&returns the base path for the range \texttt{x1} to \texttt{x2}, (hole range, when omitting the parameters)\\ -\texttt{vbasepath(x1=None, x2=None)}&as above but for graph coordinates\\ -\texttt{gridpath(x)}&returns the grid path\\ -\texttt{vgridpath(x)}&as above but for graph coordinates\\ -\texttt{tickpoint(x)}&returns the position of a tick\\ -\texttt{vtickpoint(x)}&as above but for graph coordinates\\ -\texttt{tickdirection(x)}&returns the direction, a tick should be drawn (towards inside of the graph)\\ -\texttt{vtickdirection(x)}&as above but for graph coordinates\\ -\end{tabularx} -\medskip - -Its likely, that this interface will change to contain local -transformation for the tick position/direction in a future release. -For the axes named \verb|x| and \verb|y|, the methods are available -within the graph (like the \verb|pos| method), where the method name -is prefixed by \verb|x| or \verb|y|, respectively. - -To manually add a graph key, use the \verb|addkey| method, which takes -a \verb|key| instance first followed by several \verb|plotinfo| -instances. - diff --git a/manual/graph2.py b/manual/graph2.py new file mode 100755 index 00000000..712767ed --- /dev/null +++ b/manual/graph2.py @@ -0,0 +1,5 @@ +from pyx import * +g = graph.graphxy(width=10) +g.plot(graph.data.function("y=x**2")) +g.plot(graph.data.file("graph.dat", x=1, y=2)) +g.writeEPSfile("graph2") diff --git a/manual/manual.tex b/manual/manual.tex dissimilarity index 78% index 3654eb3a..ff3f8df7 100644 --- a/manual/manual.tex +++ b/manual/manual.tex @@ -1,42 +1,59 @@ -\documentclass[dvips]{scrreprt} -\usepackage{pyx,tabularx,graphicx} -\usepackage[latin1]{inputenc} -\usepackage{url} -\usepackage{hyperref} -\usepackage{units} -\hypersetup{ - pdftitle={PyX Reference Manual}, - pdfauthor={Jörg Lehmann, André Wobst}, - colorlinks={true} -} -% \includeonly{graph} % for temporarily skipping of chapters -\setlength{\parindent}{0pt} -\begin{document} -\subject{\href{http://pyx.sourceforge.net/}{\url{http://pyx.sourceforge.net/}}} -\title{\PyX{} \input pyxversion.tex\\ -Reference Manual} -\author{J\"org Lehmann \href{mailto:joergl@users.sourceforge.net}{\url{}}\and -Andr\'e Wobst \href{mailto:wobsta@users.sourceforge.net}{\url{}}} -\maketitle -\quad\vfill\centerline{PostScript is a trademark of Adobe Systems Incorporated.} -\tableofcontents -\include{intro} -\include{path} -\include{unit} -\include{trafo} -\include{canvas} -\include{text} -\include{box} -\include{connector} -\include{epsfile} -\include{bbox} -\include{color} -\include{data} -\include{graph} -\appendix -\include{mathtree} -\include{colorname} -\include{palettename} -\include{pathstyles} -\include{arrows} -\end{document} +\documentclass{manual} + +% to shorten edit-compile-view cycles use +% \includeonly{graph} + +\usepackage{pyx} +\ifhtml % redefine the PyX macro for html (the other makes trouble) +\def\PyX{PyX} +\fi +\usepackage{graphicx} +\usepackage{tabularx} % TODO: get rid of that +\usepackage{units} % TODO: get rid of that + +\title{\PyX{} Reference Manual} +\author{J\"org Lehmann\\ +Andr\'e Wobst} +\authoraddress{http://pyx.sourceforge.net/} +\date{\today} +\release{\input{pyxversion.tex}} + +\makeindex + +\begin{document} + +\maketitle + +\ifhtml % make abstact better available (as in the python docs) +\chapter*{Front Matter\label{front}} +\fi +\begin{abstract} +\noindent +TODO: Insert an abstract about \PyX{}. +\end{abstract} + +\tableofcontents + +\include{intro} +\include{path} +\include{unit} +\include{trafo} +\include{canvas} +\include{text} +\include{box} +\include{connector} +\include{epsfile} +\include{bbox} +\include{color} +\include{graph} +\include{axis} +%\appendix +%\include{mathtree} +%\include{colorname} +%\include{palettename} +%\include{pathstyles} +%\include{arrows} + +\input{manual.ind} + +\end{document} diff --git a/manual/runlatex.sh b/manual/runlatex.sh deleted file mode 100755 index dae13bc7..00000000 --- a/manual/runlatex.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/bin/bash - -if [ $# != 1 ] ; then - echo "runs latex several times to get cross-references right" - echo "usage: runlatex.sh [.tex]" - exit 1 -fi - -file=${1%.tex} -rerunstring=1 -latexerror=0 -while [[ "$rerunstring" != "" && "$latexerror" == "0" ]] -do - latex $file.tex - latexerror=$? - rerunstring=$(tail -20 $file.log|grep "Rerun to get cross-references right.") -done -exit $latexerror diff --git a/manual/tex.tex b/manual/tex.tex deleted file mode 100644 index 74d3aac4..00000000 --- a/manual/tex.tex +++ /dev/null @@ -1,303 +0,0 @@ -\chapter{Module tex: \TeX/\LaTeX{} interface (obsolete)} -\label{tex} -\section*{Please note: THIS MODULE IS OBSOLETE. Consider the \texttt{text} module instead.} - -\section{Methods} -Text in \PyX{} is created by \TeX{} or \LaTeX. From the technical point -of view, the text is inserted as an Encapsulated PostScript file -(\verb|eps|-file). This \verb|eps|-file is generated by the module -\verb|tex| which runs \TeX{} or \LaTeX{} followed by \verb|dvips| to -create the requested text. \TeX{} is used by instances of the class -\verb|tex| while \LaTeX{} is used by \verb|latex|. Up to the -constructor and the advanced possibilities in \LaTeX{} commands both -classes \verb|tex| and \verb|latex| are identical. They provide 5 -methods to the user listed in the following table: - -\smallskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -method&task&allowed attributes in \texttt{*attr}\\ -\hline -\texttt{text(x, y, cmd, *attr)}&print \texttt{cmd}&\texttt{style, fontsize, halign, valign, direction, color, msghandler(s)}\\ -\texttt{define(cmd, *attr)}&execute \texttt{cmd}&\texttt{msghandler(s)}\\ -\texttt{textwd(cmd, *attr)}&width of \texttt{cmd}&\texttt{style, fontsize, missextents, msghandler(s)}\\ -\texttt{textht(cmd, *attr)}&height of \texttt{cmd}&\texttt{style, fontsize, valign, missextents, msghandler(s)}\\ -\texttt{textdp(cmd, *attr)}&depth of \texttt{cmd}&\texttt{style, fontsize, valign, missextents, msghandler(s)}\\ -\end{tabularx} -\smallskip - -There are some common rules: -\begin{itemize} -\item \verb|cmd| stands for a \TeX{} or \LaTeX{} expression. To -prevent a backslash plague, python's raw string feature can nicely be -used. \verb|x|, \verb|y| specify a position. -\item \verb|define| can only be called before any of the other -methods. In \LaTeX{} definitions are inserted directly in front of -the \verb|\begin{document}| statement. However, this is not a -limitation, because by \verb|\AtBeginDocument{}| definitions can be -postponed. -\item The extent routines \verb|textwd|, \verb|textht|, and -\verb|textdp| return true \PyX{} length (see section~\ref{unit}). -Usually, the evaluation takes place when performing a write and the -results are stored in a file with the suffix \verb|.size|. Therefore -you have to run your file twice at first to get the correct value. -This default behaviour can be changed by the \verb|missextents| -attribute. -\item All commands are passed to \TeX{} or \LaTeX{} in the calling -order of the methods with one exception: if the same command is used -several times (for printing as well as for calculating extents), all -requests are executed at the position of the first occurrence of the -command. -\item All text is inserted into the \verb|canvas| at the position, -where the \verb|tex|- or \verb|latex|-instance itself is inserted into -the \verb|canvas|. In fact, the \verb|eps|-file created by \TeX{} or -\LaTeX{} and \verb|dvips| is just inserted. -\item The tailing \verb|*style| parameter stands for a list of -attribute parameters listed in the last column of the table. Attribute -parameters are instances of classes discussed in detail in the -following section. -\item There can be several \verb|msghandler| attributes which will be -applied sequentially. All other parameters can occure only once. -\end{itemize} - - -\section{Attributes} -\begin{description} -\item[\texttt{style:}] \verb|style.text| (default -- does nothing to -the command),\\\verb|style.math| (switches to math mode in -\verb|\displaystyle|) -\item[\texttt{fontsize:}] specifies the \LaTeX{} font sizes by -\verb|fontsize.xxx| where \verb|xxx| is one of -\verb|tiny|, -\verb|scriptsize|, -\verb|footnotesize|, -\verb|small|, -\verb|normalsize| (default), -\verb|large|, -\verb|Large|, -\verb|LARGE|, -\verb|huge|, or -\verb|Huge|. -\item[\texttt{halign:}] \verb|halign.left| (default), -\verb|halign.center|, \verb|halign.right| -\item[\texttt{valign:}] \verb|valign.top(length)| or -\verb|valign.bottom(length)| --- creates a vertical box with width -\verb|length|. The vertical alignment is the baseline of the first line -for \verb|top| and the last line for \verb|bottom|. The box width is -stored in the \TeX{} dimension \verb|\linewidth|. -\item[\texttt{direction:}] \verb|direction.xxx| where \verb|xxx| -stands for \verb|horizontal| (default), \verb|vertical|, -\verb|upsidedown|, or \verb|rvertical|. Additionally, any angle -\verb|angle| (in degree) is allowed in \verb|direction(angle)|. -\item[\texttt{color:}] stands for any \PyX{} color (see -section~\ref{color}), default is \verb|color.gray.black| -\item[\texttt{missextents:}] provides a routine, which is called when a -requested extent is not yet available. In the following table a list -of choises for this parameter is described: - -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -missextents&description\\ -\hline -\texttt{missextents.returnzero}&returns zero (default)\\ -\texttt{missextents.returnzeroquiet}&as above, but does not return a -warning via \texttt{atexit}\\ -\texttt{missextents.raiseerror}&raise \texttt{TexMissExtentError}\\ -\texttt{missextents.createextent}&run \TeX{} or \LaTeX{} immediately to -get the requested size\\ -\texttt{missextents.createallextent}&run \TeX{} or \LaTeX{} immediately -to get the hight, width, and depth of the given text at once\\ -\end{tabularx} -\item[\texttt{msghandler:}] provides a filter for \TeX{} and \LaTeX{} -messages and defines, which messages are hidden. In the following table -the predefined message handlers are described: - -\smallskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -msghandler&description\\ -\hline -\texttt{msghandler.showall}&shows all messages\\ -\texttt{msghandler.hideload}&Hides messages which are written when loading -packages and including other files. They look like \texttt{(file...)} -where \texttt{file} is a readable file and \texttt{...} stands for any -text. This message handler is the default handler.\\ -\texttt{msghandler.hidegraphicsload}&Hides messages which are written by -\texttt{includegraphics} of the \texttt{graphicx} package. They look like -\texttt{} where \texttt{file} is a readable file.\\ -\texttt{msghandler.hidefontwarning}&Hides \LaTeX{} font warnings. They -look like \texttt{LaTeX Font Warning:} and are followed by lines starting -with \texttt{(Font)}.\\ -\texttt{msghandler.hidebuterror}&Hides messages except those -with a line which starts with ``\texttt{! }''.\\ -\texttt{msghandler.hideall}&hides all messages\\ -\end{tabularx} -\end{description} - - -\section{Constructors} -Named parameters of the constructor are used to set global options for -the instances of the classes \verb|tex| and \verb|latex|. -There are some common options for both classes listed in the following -table. - -\smallskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -parameter name&default value&description\\ -\hline -\texttt{defaultmsghandler}&\texttt{msghandler.hideload}&default -message handler (tuple of message handlers is possible)\\ -\texttt{defaultmissextents}&\texttt{missextents.returnzero}&default missing extent handler\\ -\texttt{texfilename}&\texttt{None}&Filename used for running \TeX{} or -\LaTeX. If \texttt{None}, a temporary name is used and the files are -removed automatically. It can be used to trace errors.\\ -\end{tabularx} -\smallskip - -Additionally, the class \verb|tex| has another option described in -the following table. - -\smallskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -parameter name&default value&description\\ -\hline -\texttt{lts}&\texttt{"10pt"}&Specifies a latex font size file. Those -files with the suffix \texttt{.lfs} can be created by -\texttt{createlfs.tex}. Possible values are listed when a requested -name couldn't be found.\\ -\end{tabularx} -\smallskip - -Instead of the option listed in the table above, for the class -\verb|latex| the options described in the following table are -available (additionally to the common available options). - -\smallskip -\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} -parameter name&default value&description\\ -\hline -\texttt{docclass}&\texttt{"article"}&specifies the document class\\ -\texttt{docopt}&\texttt{None}&specifies options to the document class\\ -\texttt{auxfilename}&\texttt{None}&Specifies a filename for storing the \LaTeX{} -\texttt{aux} file. This is needed when using labels and references.\\ -\end{tabularx} - -\section{Examples} -\subsection{Example 1} -\begin{quote} -\begin{verbatim} -from pyx import * - -c = canvas.canvas() -t = c.insert(tex.tex()) - -t.text(0, 0, "Hello, world!") - -print "width:", t.textwd("Hello, world!") -print "height:", t.textht("Hello, world!") -print "depth:", t.textdp("Hello, world!") - -c.writetofile("tex1") -\end{verbatim} -\end{quote} - -The output of this program is: -\begin{quote} -\begin{verbatim} -width: (0.019535 t + 0.000000 u + 0.000000 v + 0.000000 w) m -height: (0.002441 t + 0.000000 u + 0.000000 v + 0.000000 w) m -depth: (0.000683 t + 0.000000 u + 0.000000 v + 0.000000 w) m -\end{verbatim} -\end{quote} - -The file \verb|tex1.eps| is created and looks like: -\begin{quote} -\includegraphics{tex1} -\end{quote} - -\subsection{Example 2} -\begin{quote} -\begin{verbatim} -from pyx import * - -c = canvas.canvas() -t = c.insert(tex.tex()) - -t.text(0, 0, "Hello, world!") -t.text(0, -0.5, "Hello, world!", tex.fontsize.large) -t.text(0, -1.5, - r"\sum_{n=1}^{\infty} {1\over{n^2}} = {{\pi^2}\over 6}", - tex.style.math) -c.stroke(path.line(5, -0.5, 9, -0.5)) -c.stroke(path.line(5, -1, 9, -1)) -c.stroke(path.line(5, -1.5, 9, -1.5)) -c.stroke(path.line(7, -1.5, 7, 0)) - -t.text(7, -0.5, "left aligned") # default is tex.halign.left -t.text(7, -1, "center aligned", tex.halign.center) -t.text(7, -1.5, "right aligned", tex.halign.right) - -c.stroke(path.line(0, -4, 2, -4)) -c.stroke(path.line(0, -2.5, 0, -5.5)) -c.stroke(path.line(2, -2.5, 2, -5.5)) - -t.text(0, -4, - "a b c d e f g h i j k l m n o p q r s t u v w x y z", - tex.valign.top(2)) - -c.stroke(path.line(2.5, -4, 4.5, -4)) -c.stroke(path.line(2.5, -2.5, 2.5, -5.5)) -c.stroke(path.line(4.5, -2.5, 4.5, -5.5)) - -t.text(2.5, -4, - "a b c d e f g h i j k l m n o p q r s t u v w x y z", - tex.valign.bottom(2)) - -c.stroke(path.line(5, -4, 9, -4)) -c.stroke(path.line(7, -5.5, 7, -2.5)) - -t.text(7, -4, "horizontal") -t.text(7, -4, "vertical", tex.direction.vertical) -t.text(7, -4, "rvertical", tex.direction.rvertical) -t.text(7, -4, "upsidedown", tex.direction.upsidedown) - -t.text(7.5, -3.5, "45", tex.direction(45)) -t.text(6.5, -3.5, "135", tex.direction(135)) -t.text(6.5, -4.5, "225", tex.direction(225)) -t.text(7.5, -4.5, "315", tex.direction(315)) - -t.text(0, -6, "red", color.rgb.red) -t.text(3, -6, "green", color.rgb.green) -t.text(6, -6, "blue", color.rgb.blue) - -c.writetofile("tex2") -\end{verbatim} -\end{quote} - -The file \verb|tex2.eps| is created and looks like: -\begin{quote} -\includegraphics{tex2} -\end{quote} - -\section{Known bugs} -\begin{itemize} -\item The end of the last paragraph in a vertical box -(\verb|valign.top| and \verb|valign.bottom|) must be explictly -written (by the command \verb|\par| or an empty line) when a paragraph -formating parameter is changed locally (like the \verb|\baselineskip| -when changing the font size). Otherwise, the information is thrown -away due to a closing of the block before the paragraph formatting is -performed. -\item Due to \verb|dvips| the bounding box is wrong for rotated text. -The rotation is just ignored in the bounding box calculation. -\item Analysing \TeX{} messages is a difficult subject and the message -handlers provided with \PyX{} are not at all perfect in that sense. -For the message handlers \verb|msghandler.hideload| and -\verb|msghandler.hidegraphicsload| it is known, that they do not -correctly handle long filenames splited on several lines by \TeX. -\end{itemize} - -\section{Future of the module tex} -While we will certainly keep this module working at least for a while, -it is likely that another \TeX{} interface will occure soon. The idea -is to get rid of \verb|dvips| and integrate \TeX{} more directly into -\PyX. The replacement module called \verb|text| becomes available for -the first time in \PyX{} 0.3. - diff --git a/manual/tex1.py b/manual/tex1.py deleted file mode 100755 index f4454492..00000000 --- a/manual/tex1.py +++ /dev/null @@ -1,15 +0,0 @@ -#!/usr/bin/env python -import sys -sys.path[:0] = [".."] -from pyx import * -from pyx import tex - - -c = canvas.canvas() -t = c.insert(tex.tex()) -t.text(0, 0, "Hello, world!") -print "width:", t.textwd("Hello, world!") -print "height:", t.textht("Hello, world!") -print "depth:", t.textdp("Hello, world!") -c.writetofile("tex1.eps") - diff --git a/manual/tex2.py b/manual/tex2.py deleted file mode 100755 index e9fcf425..00000000 --- a/manual/tex2.py +++ /dev/null @@ -1,51 +0,0 @@ -#!/usr/bin/env python -import sys -sys.path[:0] = [".."] -from pyx import * -from pyx import tex - -c = canvas.canvas() -t = c.insert(tex.tex()) -t.text(0, 0, "Hello, world!") -t.text(0, -0.5, "Hello, world!", tex.fontsize.large) -t.text(0, -1.5, - r"\sum_{n=1}^{\infty} {1\over{n^2}} = {{\pi^2}\over 6}", - tex.style.math) - -c.stroke(path.line(5, -0.5, 9, -0.5)) -c.stroke(path.line(5, -1, 9, -1)) -c.stroke(path.line(5, -1.5, 9, -1.5)) -c.stroke(path.line(7, -1.5, 7, 0)) -t.text(7, -0.5, "left aligned") # default is tex.halign.left -t.text(7, -1, "center aligned", tex.halign.center) -t.text(7, -1.5, "right aligned", tex.halign.right) - -c.stroke(path.line(0, -4, 2, -4)) -c.stroke(path.line(0, -2.5, 0, -5.5)) -c.stroke(path.line(2, -2.5, 2, -5.5)) -t.text(0, -4, - "a b c d e f g h i j k l m n o p q r s t u v w x y z", - tex.valign.top(2)) -c.stroke(path.line(2.5, -4, 4.5, -4)) -c.stroke(path.line(2.5, -2.5, 2.5, -5.5)) -c.stroke(path.line(4.5, -2.5, 4.5, -5.5)) -t.text(2.5, -4, - "a b c d e f g h i j k l m n o p q r s t u v w x y z", - tex.valign.bottom(2)) - -c.stroke(path.line(5, -4, 9, -4)) -c.stroke(path.line(7, -5.5, 7, -2.5)) -t.text(7, -4, "horizontal") -t.text(7, -4, "vertical", tex.direction.vertical) -t.text(7, -4, "rvertical", tex.direction.rvertical) -t.text(7, -4, "upsidedown", tex.direction.upsidedown) -t.text(7.5, -3.5, "45", tex.direction(45)) -t.text(6.5, -3.5, "135", tex.direction(135)) -t.text(6.5, -4.5, "225", tex.direction(225)) -t.text(7.5, -4.5, "315", tex.direction(315)) - -t.text(0, -6, "red", color.rgb.red) -t.text(3, -6, "green", color.rgb.green) -t.text(6, -6, "blue", color.rgb.blue) -c.writetofile("tex2.eps") - -- 2.11.4.GIT