Lout 3.27.

git-svn-id: http://svn.savannah.nongnu.org/svn/lout/trunk@23 9365b830-b601-4143-9ba8-b4a8e2c3339c

1 files changed, 158 insertions, 57 deletions

diff --git a/doc/user/gra_data b/doc/user/gra_data
index 049a644..91f87ad 100644
--- a/doc/user/gra_data
+++ b/doc/user/gra_data
@@ -4,11 +4,15 @@
 @Begin
 @PP
 The @Code "@Data" symbol has options for controlling the
-data. @Index @Code "@Data"
+graphs. @RawIndex { graphs (statistical) }
+graphs.data @SubIndex { @Code "@Data" symbol }
+data.graph @Index { @Code "@Data" symbol (graphs) }
 appearance of its data.  We have already seen the
 @Code "points" option, which controls what is printed at each data
+graphs. @RawIndex { graphs (statistical) }
+graphs.points @SubIndex { @Code points option }
+points.graph @Index { @Code "points" option (graphs) }
 point:
-points.graphs @Index { @Code "points" option in graphs }
 @CD @Tab
    vmargin { 0.5vx }
    @Fmta { @Col @Code A ! @Col B ! @Col ! @Col @Code C ! @Col D }
@@ -41,20 +45,24 @@ points.graphs @Index { @Code "points" option in graphs }
 }
 If the @Code "points" option is omitted or empty, nothing is printed.  The
 symbols are centred over the data point.  There is a @Code "symbolsize"
+graphs. @RawIndex { graphs (statistical) }
+graphs.symbolsize @SubIndex { @Code symbolsize option }
+symbolsize.graph @Index { @Code "symbolsize" option (graphs) }
 option which controls the size (radius) of all these symbols:
-symbolsize. @Index { @Code "symbolsize" option in graphs }
 @ID @OneRow @Code {
 "@Data"
-"    symbolsize { 0.15 ft }"
+"    symbolsize { 0.15f }"
 }
 shows the default, 0.15 times the current font size.  More
 precisely, the default value is taken from an option
 to the @Code "@Graph" symbol, also called {@Code "symbolsize"}.  By
 setting that option you can therefore set the symbol size of all data
-points in the graph at once; its default value is {@Code "0.15 ft"}.
+points in the graph at once; its default value is {@Code "0.15f"}.
 @PP
 The @Code "@Data" symbol also has a @Code "pairs" option which
-pairs. @Index { @Code "pairs" option in graphs }
+graphs. @RawIndex { graphs (statistical) }
+graphs.pairs @SubIndex { @Code pairs option }
+pairs.graph @Index { @Code "pairs" option (graphs) }
 determines how each pair of points is connected.  The choices are
 @Code none (not connected, the default), @Code solid (a solid line),
 @Code dashed (a dashed line), or @Code dotted (a dotted line).  For
@@ -97,38 +105,49 @@ first and last dash in each segment will have half the length of the
 others.
 @PP
 A @Code "dashlength" option controls the length of dashes and also the
+graphs. @RawIndex { graphs (statistical) }
+graphs.dashlength @SubIndex { @Code dashlength option }
+dashlength.graph @Index { @Code "dashlength" option (graphs) }
 separation between dots, and a @Code "linewidth" option controls the
+graphs. @RawIndex { graphs (statistical) }
+graphs.linewidth @SubIndex { @Code linewidth option }
+linewidth.graph @Index { @Code "linewidth" option (graphs) }
 width (thickness) of the lines and dots:
 @ID @OneRow @Code {
 "@Data"
-"    dashlength { 0.2 ft }"
-"    linewidth { 0.5 pt }"
+"    dashlength { 0.2f }"
+"    linewidth { 0.5p }"
 "{"
 "    ..."
 "}"
 }
-This shows the default values, {@Code "0.2 ft"} for @Code "dashlength"
-and {@Code "0.5 pt"} (half a point) for {@Code "linewidth"}.  Actually
+This shows the default values, {@Code "0.2f"} for @Code "dashlength"
+and {@Code "0.5p"} (half a point) for {@Code "linewidth"}.  Actually
 the default value for @Code "linewidth" is whatever happens to be
 already in use, but Lout sets line widths to half a point initially.
 This option also controls the separation between bars in histograms.
 @PP
 The @Code "pairs" option is also used for producing histograms, like
+graphs. @RawIndex { graphs (statistical) }
+graphs.histograms @SubIndex { histograms }
 histograms. @Index { histograms }
+graphs. @RawIndex { graphs (statistical) }
+graphs.yhisto @SubIndex { @Code yhisto option }
+yhisto.graph @Index { @Code "yhisto" option (graphs) }
 this:
-@ID @OneRow @Code {
-"@Graph"
-"    hidecaptions { yes }"
-"    abovecaption { Computer Science 3 Results (1993) }"
-"    leftcaption { Number of"
-"students }"
-"    belowcaption { Final mark (%) }"
-"    yextra { 0 cm }"
-"    ymax { 80 }"
-"{"
-"    @Data pairs { yhisto }"
-"    { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }"
-"}"
+@ID @OneRow @Code @Verbatim {
+@Graph
+    hidecaptions { yes }
+    abovecaption { Computer Science 3 Results (1993) }
+    leftcaption { Number of
+students }
+    belowcaption { Final mark (%) }
+    yextra { 0c }
+    ymax { 80 }
+{
+    @Data pairs { yhisto }
+    { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }
+}
 }
 which has result
 @CD @Graph
@@ -137,7 +156,7 @@ which has result
     leftcaption { Number of
 students }
     belowcaption { Final mark (%) }
-    yextra { 0 cm }
+    yextra { 0c }
     ymax { 80 }
 {
     @Data
@@ -150,13 +169,16 @@ these two x values.  This means that the very last y value has no effect
 on the result (however, there must be a last y value anyway).
 @PP
 There is an alternative to @Code "yhisto" called {@Code "surfaceyhisto"}:
+graphs. @RawIndex { graphs (statistical) }
+graphs.surfaceyhisto @SubIndex { @Code surfaceyhisto option }
+surfaceyhisto.graph @Index { @Code "surfaceyhisto" option (graphs) }
 @CD @Graph
     hidecaptions { yes }
     abovecaption { Computer Science 3 Results (1993) }
     leftcaption { Number of
 students }
     belowcaption { Final mark (%) }
-    yextra { 0 cm }
+    yextra { 0c }
     ymax { 80 }
 {
     @Data
@@ -167,39 +189,50 @@ As you can see, @Code "surfaceyhisto" draws just the surface of the
 histogram, not the descending lines.
 @PP
 There are @Code "xhisto" and @Code "surfacexhisto" values of
+graphs. @RawIndex { graphs (statistical) }
+graphs.xhisto @SubIndex { @Code xhisto option }
+xhisto.graph @Index { @Code "xhisto" option (graphs) }
+graphs. @RawIndex { graphs (statistical) }
+graphs.surfacexhisto @SubIndex { @Code surfacexhisto option }
+surfacexhisto.graph @Index { @Code "surfacexhisto" option (graphs) }
 @Code "pairs" which produce a histogram whose bars are parallel to
 the x axis.  There are also {@Code "filledyhisto" } and
 {@Code "filledxhisto" } values which produce filled rectangles rather
+graphs. @RawIndex { graphs (statistical) }
+graphs.filledxhisto @SubIndex { @Code filledxhisto option }
+filledxhisto.graph @Index { @Code "filledxhisto" option (graphs) }
+graphs. @RawIndex { graphs (statistical) }
+graphs.filledyhisto @SubIndex { @Code filledyhisto option }
+filledyhisto.graph @Index { @Code "filledyhisto" option (graphs) }
 than outlined ones:
-@ID @OneRow @Code {
-"@Graph"
-"    abovecaption { Fertility rates in some developing countries }"
-"    xextra { 0 cm }"
-"    yextra { 0 cm }"
-"    xmax { 8 }"
-"    yticks {"
-"        1.5 (Turkey) 2.5 (Thailand)"
-"        3.5 (Indonesia) 4.5 (Costa Rica)"
-"        5.5 (Colombia) 6.5 (Cameroon)"
-"        7.5 (Botswana) 8.5 (Bangladesh)"
-"    }"
-"    yticklength { 0 cm }"
-"{"
-"    @Data"
-"        pairs { filledxhisto }"
-"    { 0 1 3.2 2 2.2 3 3.0 4 3.5 5 2.8 6 5.9 7 4.8 8 5.3 9 }"
-"}"
+@ID @OneRow @Code @Verbatim {
+@Graph
+    abovecaption { Fertility rates in some developing countries }
+    xextra { 0c }
+    yextra { 0c }
+    xmax { 8 }
+    yticks {
+        1.5 (Turkey) 2.5 (Thailand)
+        3.5 (Indonesia) 4.5 (Costa Rica)
+        5.5 (Colombia) 6.5 (Cameroon)
+        7.5 (Botswana) 8.5 (Bangladesh)
+    }
+    yticklength { 0c }
+{
+    @Data
+        pairs { filledxhisto }
+    { 0 1 3.2 2 2.2 3 3.0 4 3.5 5 2.8 6 5.9 7 4.8 8 5.3 9 }
+}
 }
 produces
 @CD @Graph
-    abovecaption { Fertility rates in some developing countries
-    }
-    xextra { 0 cm }
-    yextra { 0 cm }
+    abovecaption { Fertility rates in some developing countries }
+    xextra { 0c }
+    yextra { 0c }
     xmax { 8 }
     yticks { 1.5 (Turkey) 2.5 (Thailand) 3.5 (Indonesia) 4.5 (Costa Rica)
              5.5 (Colombia) 6.5 (Cameroon) 7.5 (Botswana) 8.5 (Bangladesh) }
-    yticklength { 0 cm }
+    yticklength { 0c }
 {
     @Data
         pairs { filledxhisto }
@@ -212,10 +245,13 @@ equal to the x value lying between the two y values; this time the very
 first x value has no effect on the result.
 @PP
 The colour of one set of data can be changed with a @Code "colour"
+graphs. @RawIndex { graphs (statistical) }
+graphs.colour @SubIndex { @Code colour option }
+colour.graph @Index { @Code "colour" option (graphs) }
 option:
-@ID @OneRow @Code {
-"@Data"
-"    colour { blue }"
+@ID @OneRow @Code @Verbatim {
+@Data
+    colour { blue }
 }
 For the complete list of acceptable colours, see Section
 {@NumberOf colour}.  The @Code "colour" option's name may also be
@@ -223,6 +259,10 @@ spelt @Code {"color"}.
 @PP
 It is also possible to paint the area between the data points and
 the x axis (or frame if @Code "style" is not {@Code "axes"}), using
+graphs. @RawIndex { graphs (statistical) }
+graphs.paint @SubIndex { @Code paint option }
+paint. @RawIndex { @Code "paint" option }
+paint.in.graphs @SubIndex { in graphs }
 @ID @OneRow @Code {
 "@Data"
 "    paint { yes }"
@@ -234,8 +274,69 @@ data sets.  However the points and lines of each data set are drawn after
 painting that set, so they cannot be hidden under their own paint; and
 axes and frames are drawn last so that they too are never hidden.
 @PP
+Wherever there is a @Code paint option in Lout's standard packages,
+there is a neighbouring @Code texture option.  For historical reasons
+the @Code paint option of @Code "@Graph" is not quite the same as other
+@Code "paint" options, but the @Code "texture" option is available
+graphs. @RawIndex { graphs (statistical) }
+graphs.texture @SubIndex { @Code texture option }
+texture.option. @RawIndex { @Code "texture" option }
+texture.option.in.graph @SubIndex { in graphs }
+as usual:
+@ID @OneRow @Code @Verbatim {
+@Graph
+    yextra { 0c }
+{
+    @Data
+        paint { yes }
+        texture { chessboard angle { 45d } }
+    { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 }
+}
+}
+produces
+@FootNote {
+If you can't see any textures here, the fault is probably with your
+PostScript viewer.  See Section {@NumberOf textures}.
+}
+@CD @Graph
+    yextra { 0c }
+{
+    @Data
+        paint { yes }
+        texture { striped angle { 90d } }
+    { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 }
+}
+Any value acceptable to the @Code "texture" option of @Code "@Box"
+(Section {@NumberOf boxes}) is acceptable here.  The @Code "texture"
+option will also give a texture to the filled areas of a
+{@Code filledxhisto} or {@Code filledyhisto}:
+@ID @OneRow @Code @Verbatim {
+@Graph
+    yextra { 0c }
+{
+    @Data
+        pairs { filledyhisto }
+        texture { striped angle { 45d } }
+    { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 7 0 }
+}
+}
+produces
+@CD @Graph
+    yextra { 0c }
+{
+    @Data
+        pairs { filledyhisto }
+        texture { striped angle { 45d } }
+    { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 7 0 }
+}
+If you want the bars to vary in colour or texture, you have to give
+multiple @Code "@Data" sets, one for each combination of colour and
+texture.
+@PP
 A @Code "dataformat" option is provided for changing the interpretation
-dataformat. @Index { @Code "dataformat" option in graphs }
+graphs. @RawIndex { graphs (statistical) }
+graphs.dataformat @SubIndex { @Code dataformat option }
+dataformat.graph @Index { @Code "dataformat" option (graphs) }
 of the data.  Ordinarily, as we know, the numbers are taken to be pairs of
 x and y coordinates, like this:
 @ID @OneRow @Code {
@@ -253,17 +354,17 @@ interpretation is changed to a sequence of y coordinates only:
 "    y y  ...  y"
 "}"
 }
-and x values 1, 2, and so on are inserted automatically, just as though
-the original input had been
+and x values 1, 2, and so on are inserted automatically, as though
+the original input was
 @ID @OneRow @Code {
 "@Data"
 "{"
 "    1 y  2 y  ..."
 "}"
 }
-There is also {@Code "xonly"}, which inserts y values 1, 2, and so on.  The
+Similarly, {@Code "xonly"} inserts y values 1, 2, and so on.  The
 default value, {@Code "xandy"}, gives the usual interpretation, and
-{@Code "swapxandy"} exchanges adjacent pairs of numbers in the data, so
-that the data is interpreted as @E { (y, x) } pairs rather than @E { (x, y) }
+{@Code "swapxandy"} exchanges adjacent pairs of numbers:  the data
+is interpreted as @E { (y, x) } pairs rather than @E { (x, y) }
 pairs.  The layout of data on lines has no effect on the interpretation.
 @End @Section