From c9c4856866f27116b953d133448653d6b9a2849c Mon Sep 17 00:00:00 2001
From: =?utf8?q?Andr=C3=A9=20Wobst?= <wobsta@users.sourceforge.net>
Date: Mon, 22 May 2006 19:47:35 +0000
Subject: [PATCH] update the axes examples to the new structure -- hopefully
 its now becoming more useful

git-svn-id: https://pyx.svn.sourceforge.net/svnroot/pyx/trunk/pyx@2780 069f4177-920e-0410-937b-c2a4a81bcd90
---
 examples/axis/INDEX           |  2 +-
 examples/axis/README          |  8 +++++---
 examples/axis/log.py          |  6 ------
 examples/axis/log.txt         | 14 ++++++++++++++
 examples/axis/manualticks.py  | 33 ++++++++++++++-------------------
 examples/axis/manualticks.txt | 11 +++++++++++
 examples/axis/minimal.py      |  6 ++++++
 examples/axis/minimal.txt     | 13 +++++++++++++
 examples/axis/painter.py      | 26 ++++++++------------------
 examples/axis/painter.txt     | 17 +++++++++++++++++
 examples/axis/parter.py       | 39 ++++++++++++++-------------------------
 examples/axis/parter.txt      | 21 +++++++++++++++++++++
 examples/axis/rating.py       | 40 ++++++++++++++--------------------------
 examples/axis/rating.txt      | 31 +++++++++++++++++++++++++++++++
 examples/axis/simple.py       | 13 -------------
 examples/axis/texter.py       | 11 -----------
 examples/axis/texter.txt      | 11 +++++++++++
 17 files changed, 180 insertions(+), 122 deletions(-)
 create mode 100644 examples/axis/log.txt
 rewrite examples/axis/manualticks.py (77%)
 create mode 100644 examples/axis/manualticks.txt
 create mode 100644 examples/axis/minimal.py
 create mode 100644 examples/axis/minimal.txt
 rewrite examples/axis/painter.py (90%)
 create mode 100644 examples/axis/painter.txt
 rewrite examples/axis/parter.py (85%)
 create mode 100644 examples/axis/parter.txt
 rewrite examples/axis/rating.py (92%)
 create mode 100644 examples/axis/rating.txt
 delete mode 100644 examples/axis/simple.py
 create mode 100644 examples/axis/texter.txt

diff --git a/examples/axis/INDEX b/examples/axis/INDEX
index 38654d26..705bc965 100644
--- a/examples/axis/INDEX
+++ b/examples/axis/INDEX
@@ -1,4 +1,4 @@
-simple
+minimal
 painter
 rating
 manualticks
diff --git a/examples/axis/README b/examples/axis/README
index ee12563c..a6d86155 100644
--- a/examples/axis/README
+++ b/examples/axis/README
@@ -1,5 +1,7 @@
 Graph axes
 
-This section demonstrates the axis subsystem of the graph module. While here
-axes are created along paths, all the demonstrated features can be used in
-graphs as well.
+This section demonstrates some axes features of the graph system. For that we
+draw axes along paths, although this ''might'' look a bit esoteric (especially
+since we're using curved paths). But please be not distracted by that: all the
+shown functionality is available to the quite boring case of straight axes as
+they are typically used in graphs.
diff --git a/examples/axis/log.py b/examples/axis/log.py
index 17556f21..999ab97b 100644
--- a/examples/axis/log.py
+++ b/examples/axis/log.py
@@ -1,9 +1,3 @@
-# Certainly logarithmic axes are supported in PyX. By playing with
-# partitioners and texters, you can easily change the base.
-#
-# It is left as an exercise to the reader to create a automatic
-# partitioner for logarithmic axes with base 2.
-
 import math
 from pyx import *
 from pyx.graph import axis
diff --git a/examples/axis/log.txt b/examples/axis/log.txt
new file mode 100644
index 00000000..4fc8d689
--- /dev/null
+++ b/examples/axis/log.txt
@@ -0,0 +1,14 @@
+Logarithmic axes
+
+Logarithmic axes are quite similar to linear axes and differ only in a very few
+properties, namely the non-linear convert method in which they transform values
+to positions on the axis, a different default partitioner and a different
+default rater. While the partitioner really is quite different - it implements
+a logarithmic positioning of the ticks - the rater just alters some defaults in
+favour of using more subticks to improve the visualization of the logarithmic
+nature of the axis.
+
+! Beside presenting a standard logarithmic axis we also show you how to alter
+the base used by the logarithmic axis. Since the functionality of a logarithmic
+axis is independend of the base, all we need to adjust are certain components
+creating ticks, the texts for the labels etc.
diff --git a/examples/axis/manualticks.py b/examples/axis/manualticks.py
dissimilarity index 77%
index 91d65b14..42396fd0 100644
--- a/examples/axis/manualticks.py
+++ b/examples/axis/manualticks.py
@@ -1,19 +1,14 @@
-# Ticks can be set manually in combination with automatically created
-# ticks. Note that the rating takes into account the manual ticks as
-# well.
-
-import math
-from pyx import *
-from pyx.graph import axis
-
-p = path.curve(0, 0, 3, 0, 1, 4, 4, 4)
-
-myticks = [axis.tick.tick(math.pi, label="\pi", labelattrs=[text.mathmode]),
-           axis.tick.tick(2*math.pi, label="2\pi", labelattrs=[text.mathmode])]
-
-c = canvas.canvas()
-c.insert(axis.pathaxis(p, axis.linear(min=0, max=10)))
-c.insert(axis.pathaxis(p.transformed(trafo.translate(4, 0)),
-                       axis.linear(min=0, max=10, manualticks=myticks)))
-c.writeEPSfile("manualticks")
-c.writePDFfile("manualticks")
+import math
+from pyx import *
+
+p = path.curve(0, 0, 3, 0, 1, 4, 4, 4)
+
+myticks = [graph.axis.tick.tick(math.pi, label="\pi", labelattrs=[text.mathmode]),
+           graph.axis.tick.tick(2*math.pi, label="2\pi", labelattrs=[text.mathmode])]
+
+c = canvas.canvas()
+c.insert(graph.axis.pathaxis(p, graph.axis.linear(min=0, max=10)))
+c.insert(graph.axis.pathaxis(p.transformed(trafo.translate(4, 0)),
+                             graph.axis.linear(min=0, max=10, manualticks=myticks)))
+c.writeEPSfile("manualticks")
+c.writePDFfile("manualticks")
diff --git a/examples/axis/manualticks.txt b/examples/axis/manualticks.txt
new file mode 100644
index 00000000..7d64ad2a
--- /dev/null
+++ b/examples/axis/manualticks.txt
@@ -0,0 +1,11 @@
+Manually place ticks at certain positions
+
+Ticks can be set manually by passing tick instances to the `manualticks`
+argument of the axis instance as shown at the right axis in this example.
+
+As you can see the manual ticks are combined with tick created automatically.
+You could disable any automatic tick creation by setting the `parter` argument
+to None. But what's much more interesting is, that the manually and
+automatically created ticks are not just merged, but the combination together
+is used when rating the resulting partion. Hence the manual ticks lead to a
+different set of automatically created ticks for this example.
diff --git a/examples/axis/minimal.py b/examples/axis/minimal.py
new file mode 100644
index 00000000..b04226d3
--- /dev/null
+++ b/examples/axis/minimal.py
@@ -0,0 +1,6 @@
+from pyx import *
+
+c = graph.axis.pathaxis(path.curve(0, 0, 3, 0, 1, 4, 4, 4),
+                        graph.axis.linear(min=0, max=10))
+c.writeEPSfile("minimal")
+c.writePDFfile("minimal")
diff --git a/examples/axis/minimal.txt b/examples/axis/minimal.txt
new file mode 100644
index 00000000..65c5921a
--- /dev/null
+++ b/examples/axis/minimal.txt
@@ -0,0 +1,13 @@
+Minimal example drawing an axis along a path
+
+This is the basic example how to draw an axis along an arbitrary path. The
+function `pathaxis` from the `graph.axis` module takes a path and returns a
+canvas. Different from the typical usecase in graphs, we must fix the axis
+range by appropriate `min` and `max` arguments, because no data is provided to
+the axis instance where a data range could be extracted from. In graphs the
+range of an axis gets adjusted automatically although you can still set minimal
+and/or maximal values to force a certain axis range.
+
+The axis instance is passed as the second argument to the `pathaxis` function.
+To use the axis at a graph all you need to do is to path the instance to the
+axis constructor using an appropriate keyword specifying the axis name.
diff --git a/examples/axis/painter.py b/examples/axis/painter.py
dissimilarity index 90%
index ffb19496..701b0ee5 100644
--- a/examples/axis/painter.py
+++ b/examples/axis/painter.py
@@ -1,18 +1,8 @@
-# Axis painters performs the painting of an axis. By default, ticks
-# are stroked inside of the graph (in the path examples there is no
-# graph but don't mind) while labels and the axis title are plotted
-# outside. The axis title is rotated along the axis (without writing it
-# upside down), while the tick labels are not rotated. The axis painters
-# takes a variety of keyword arguments to modify the default
-# behaviour.
-
-from pyx import *
-from pyx.graph import axis
-
-ap = axis.painter.regular(outerticklength=axis.painter.ticklength.normal)
-
-c = axis.pathaxis(path.curve(0, 0, 3, 0, 1, 4, 4, 4),
-                        axis.linear(min=0, max=10, title="axis title",
-                                    painter=ap))
-c.writeEPSfile("painter")
-c.writePDFfile("painter")
+from pyx import *
+
+mypainter = graph.axis.painter.regular(outerticklength=graph.axis.painter.ticklength.normal)
+
+c = graph.axis.pathaxis(path.curve(0, 0, 3, 0, 1, 4, 4, 4),
+                        graph.axis.linear(min=0, max=10, title="axis title", painter=mypainter))
+c.writeEPSfile("painter")
+c.writePDFfile("painter")
diff --git a/examples/axis/painter.txt b/examples/axis/painter.txt
new file mode 100644
index 00000000..e0793daf
--- /dev/null
+++ b/examples/axis/painter.txt
@@ -0,0 +1,17 @@
+Painting of an axis
+
+Axis painters performs the painting of an axis, which means they take all the
+information of the axis an create a proper drawing for that.
+
+While an usual axis painter has quite some parameters to adjust the output,
+here we only alter the ticks. By default, ticks are stroked only towards the
+inside of the graph (in the path examples there is no graph but don't mind).
+The labels and the axis title are plotted outside of the graph. Futhermore the
+axis title (when present as in this example) is rotated along the axis (without
+writing it upside down), while the tick labels are not rotated at all.
+
+In this example we set an `outerticklength`. Together with the
+`innerticklength` set to the same value by default the ticks are stroked across
+the axis. As it is common to sub-components of the axis, you need to pass the
+adapted instances (stored in the variable `mypainter` here) to the axis in its
+constructor.
diff --git a/examples/axis/parter.py b/examples/axis/parter.py
dissimilarity index 85%
index 91ee735f..10a731f8 100644
--- a/examples/axis/parter.py
+++ b/examples/axis/parter.py
@@ -1,25 +1,14 @@
-# Partitioners (in the code the short form parter is used) take
-# care of calculating appropriate tick positions for a given axis
-# range. Automatic partitioners create several tick lists, which are
-# rated by an axis rater instance afterwards while manual partitioners
-# create a single tick list only, which thus doesn't need to be rated.
-#
-# Note that the partitioning uses fractional number arithmetics. For
-# that, tick instances can be initialized with floats using a fixed
-# precision but also with strings as shown.
-
-import math
-from pyx import *
-from pyx.graph import axis
-
-p = path.curve(0, 0, 3, 0, 1, 4, 4, 4)
-
-myparter = axis.parter.linear(["1/3", "1/6"])
-
-c = canvas.canvas()
-c.insert(axis.pathaxis(p, axis.linear(min=0, max=1, parter=myparter)))
-c.insert(axis.pathaxis(p.transformed(trafo.translate(4, 0)),
-                       axis.linear(min=0, max=1, parter=myparter,
-                                   texter=axis.texter.rational())))
-c.writeEPSfile("parter")
-c.writePDFfile("parter")
+import math
+from pyx import *
+
+p = path.curve(0, 0, 3, 0, 1, 4, 4, 4)
+
+myparter = graph.axis.parter.linear(["1/3", "1/6"])
+
+c = canvas.canvas()
+c.insert(graph.axis.pathaxis(p, graph.axis.linear(min=0, max=1, parter=myparter)))
+c.insert(graph.axis.pathaxis(p.transformed(trafo.translate(4, 0)),
+                             graph.axis.linear(min=0, max=1, parter=myparter,
+                             texter=graph.axis.texter.rational())))
+c.writeEPSfile("parter")
+c.writePDFfile("parter")
diff --git a/examples/axis/parter.txt b/examples/axis/parter.txt
new file mode 100644
index 00000000..e4e1648d
--- /dev/null
+++ b/examples/axis/parter.txt
@@ -0,0 +1,21 @@
+Manual parters and rational number arithmetics
+
+Partitioners (in the code the short form `parter` is used all over the place)
+take care of calculating appropriate tick positions for a given axis range.
+Automatic partitioners create several tick lists, which are than rated by an
+axis rater instance afterwards. In contrast manual partitioners create a single
+tick list only, which thus doesn't need to be rated at all.
+
+In this example we create a manual partitioner, which places ticks with a
+distance of 1/3 and subticks with a distance of 1/6. We than use this
+partitioner at two axis, which are identical except for a texter instance to
+show you another feature of the axes in PyX, namely the rational number
+arithmetics used to place ticks. The rational numbers are preserved throughout
+the whole process of merging ticks, until the texter finally needs to output
+the rational numbers. And at the very end the decimal texter steps into the
+problem to create a proper representation for the frations. The solution is
+shown at the left part of the example: the texter marks a period to express the
+fraction.
+
+Alternatively you can use the rational texter to display the values by
+fractions directly.
diff --git a/examples/axis/rating.py b/examples/axis/rating.py
dissimilarity index 92%
index 0d37faed..4e1c9ced 100644
--- a/examples/axis/rating.py
+++ b/examples/axis/rating.py
@@ -1,26 +1,14 @@
-# In the example below, several axes with the same parameters are
-# plotted on a path scaled in 3 different sizes. Note that the axes
-# adjust the ticks appropriately to the available space. The rating
-# mechanism takes into account the number of ticks and subticks, but
-# also the distances between the labels. Thus, the example in the
-# middle has less ticks than the smallest version, because there is
-# not enough room for labels with a decimal place.
-#
-# The rating mechanism is configurable and exchangeable by the axis
-# keyword argument "rater". Instead of reconfiguring the rating
-# mechanism, simple adjustments to favour more or less ticks are
-# possible by the axis keyword argument "density".
-
-from pyx import *
-from pyx.graph import axis
-
-p = path.curve(0, 0, 3, 0, 1, 4, 4, 4)
-
-c = canvas.canvas()
-c.insert(axis.pathaxis(p.transformed(trafo.translate(-4, 0).scaled(0.75)),
-                       axis.linear(min=0, max=10)))
-c.insert(axis.pathaxis(p, axis.linear(min=0, max=10)))
-c.insert(axis.pathaxis(p.transformed(trafo.scale(1.25).translated(4, 0)),
-                       axis.linear(min=0, max=10)))
-c.writeEPSfile("rating")
-c.writePDFfile("rating")
+from pyx import *
+
+p2 = path.curve(0, 0, 3, 0, 1, 4, 4, 4)
+p1 = p2.transformed(trafo.translate(-4, 0).scaled(0.75))
+p3 = p2.transformed(trafo.scale(1.25).translated(4, 0))
+
+myaxis = graph.axis.linear(min=0, max=10)
+
+c = canvas.canvas()
+c.insert(graph.axis.pathaxis(p1, myaxis))
+c.insert(graph.axis.pathaxis(p2, myaxis))
+c.insert(graph.axis.pathaxis(p3, myaxis))
+c.writeEPSfile("rating")
+c.writePDFfile("rating")
diff --git a/examples/axis/rating.txt b/examples/axis/rating.txt
new file mode 100644
index 00000000..a05ab36a
--- /dev/null
+++ b/examples/axis/rating.txt
@@ -0,0 +1,31 @@
+Rating of axis partitionings
+
+In this example several axes with the same parameters are plotted on a path
+scaled at 3 different sizes. Note that the axes adjust the ticks appropriately
+to the available space. For that a `partitioner` (the short form `parter` is
+used in the code) creates several possible solutions for placing ticks and
+labels at the axis.
+
+However, we do not address this partioning feature here (we just use the
+default), but we show you the rating facilities instead. Still, we don't modify
+the defaults either, but we want to discuss certain features of this system.
+
+The rating mechanism takes into account the number of ticks and subticks, but
+also the distances between the labels. Thus, the example in the middle has less
+ticks than the right version, because there is more space available at the
+larger path. More interestingly more labels are also shown on the very left
+path, although it is smaller than the middle one. This is due to the fact, that
+there is not enough room for labels with a decimal place on the smaller axis!
+
+! The rating mechanism is configurable and exchangeable by passing rater
+instances to the `rater` keyword of the axis constructor. But instead of
+reconfiguring the whole rating mechanism, simple adjustments to favour more or
+less ticks are easily possible by the axis keyword argument `density`.
+
+!! In this example the same axis instance is used several times. This works
+since the axis does not store any data within its own instance. Instead, an
+`anchoredaxis` instance is created by the `pathaxis` which embbeds the axis in
+a proper environment. Among others a place for storing information for this
+specific use of the axis instance is provided that way. When using axes in a
+graph the graph instance takes care of the proper setup of the anchored axes
+instances.
diff --git a/examples/axis/simple.py b/examples/axis/simple.py
deleted file mode 100644
index 0ba831da..00000000
--- a/examples/axis/simple.py
+++ /dev/null
@@ -1,13 +0,0 @@
-# This is the basic example how to draw an axis along an arbitrary
-# path. The function pathaxis from the graph.axis module takes a path
-# and returns a canvas. Different from the typical usecase in graphs,
-# we must fix the axis range by appropriate min and max arguments,
-# because of missing data. In graphs the range can be adjusted
-# automatically.
-
-from pyx import *
-
-c = graph.axis.pathaxis(path.curve(0, 0, 3, 0, 1, 4, 4, 4),
-                        graph.axis.linear(min=0, max=10))
-c.writeEPSfile("simple")
-c.writePDFfile("simple")
diff --git a/examples/axis/texter.py b/examples/axis/texter.py
index 8578ae00..88549da4 100644
--- a/examples/axis/texter.py
+++ b/examples/axis/texter.py
@@ -1,14 +1,3 @@
-# Texters create the label strings written to the ticks. There are
-# texters available for decimal numbers without and with an
-# exponential part as well as fractions. Internally, the partitioning
-# is based on fractions to avoid any rounding problems.
-#
-# Although we could modify axis.linear into a piaxis "inplace", we
-# define a special piaxis below to give an impression, how easy
-# alternative default settings can be implemented. A more advanced
-# task would be to add an appropriate special partitioner for a
-# piaxis.
-
 import math
 from pyx import *
 from pyx.graph import axis
diff --git a/examples/axis/texter.txt b/examples/axis/texter.txt
new file mode 100644
index 00000000..255a0866
--- /dev/null
+++ b/examples/axis/texter.txt
@@ -0,0 +1,11 @@
+Texter
+
+Texters create the label strings written to the ticks. There are texters
+available for decimal numbers without and with an exponential part as well as
+fractions.
+
+! At the right axis we also show how to create a special piaxis. Here some axis
+parameters are altered to fit an pi-scaled axis nicely. Futhermore instead of
+just creating a special axis instance by setting the divisor and texter
+parameters, a `piaxis` class is created which just alters the defaults of the
+linear axis it is based at.
-- 
2.11.4.GIT