ctioga 1.11.1

data/ctioga/doc/ctioga.1

@@ -0,0 +1,2363 @@
+'\" t
+.\" ** The above line should force tbl to be a preprocessor **
+.\" Man page for ctioga, based on the one from man(1)
+.\"
+.\" Copyright 2006, 2007, 2008, 2009 by Vincent Fourmond
+.\"
+.\" You may distribute under the terms of the GNU General Public
+.\" License as specified in the file COPYING that comes with the
+.\" ctioga program.
+.\"
+.pc
+.TH CTIOGA 1 "2009-01-07" "Version 1.9" "Tioga command-line interface"
+.SH NAME
+ctioga \- a command-line front-end for the Tioga plotting library
+.SH SYNOPSIS
+.\" The general command line
+.B ctioga
+.I arguments
+\&.\|.\|.
+
+.SH DESCRIPTION
+.B ctioga
+is a command-line front-end to the wonderful Tioga plotting
+library. It aims at plotting quickly both data files and mathematical
+functions, with however the possibility of a high control over the
+details.
+
+.SH IMPORTANT NOTE
+Please keep in mind while reading this that the main author of
+.B ctioga
+has more fun programming than writing documentation, which means that
+he is more willing to invest energy into new features of ctioga rather
+than keeping this manual page up-to-date. Best care is taken for
+.B ctioga
+to remain backward-compatible, which means that the information
+you'll find here will most probably never be misleading. However, not
+all the features might be documented at some point. The currently
+implemented features will be found using
+.I ctioga --help\fR.
+
+
+
+.SH EXAMPLES
+
+To get to the facts, let's start with a few examples:
+.TP 8 
+.BI ctioga \ File.dat
+Produces a file \fIPlot.pdf\fR showing the second column of File.dat
+as a function of the first.
+
+.TP 
+.BI ctioga \ File.dat@2:3
+Produces a file \fIPlot.pdf\fR showing the third column of File.dat
+as a function of the second.
+
+.TP 
+.B ctioga \fIFile.dat@2:3 @4:5 \fR
+Produces a file \fIPlot.pdf\fR showing the third column of File.dat
+as a function of the second and the fifth as a function of the fourth.
+
+.TP 
+.BI ctioga \ --math\ 'sin(x)'
+Produces a file \fIPlot.pdf\fR showing the function sin(x).
+
+.TP 
+.BI ctioga \ --xpdf\ --math\ -l\ 'Cosine'\ 'cos(x)'
+Produces a file \fIPlot.pdf\fR showing the function cos(x), nicely
+labeled with the text 
+.I 'Cosine'
+and launches 
+.I xpdf
+to display the file produced.
+
+.P
+
+More examples and a rather complete tutorial 
+can be found in the
+.I examples/
+directory in the original tarball.
+
+
+.SH OPTIONS
+
+ctioga works with the concept of \fIbackends\fR: a \fIbackend\fR is an
+object dealing with the data. Some read data from different kinds of
+files, others, like the 
+.I math
+backend create data on demand from mathematical formulas. Backends
+work with data sets. A set is one curve. 
+
+ctioga's command line is made of of options, starting with '-' or '--',
+mixed with sets (all the rest). Options apply to the sets specified on
+their right; some (like \fI--legend\fR) only to the next one.
+
+
+.\" --------------------------------------------------------------------
+.SS Basic style options
+
+.TP 8
+.BI -c,\ --[no-]color \ [color]
+specifies the color to be used for lines. It can be set to any valid
+Tioga color, or to
+.I auto
+to use \fIctioga\fR's automatic color scheme (by default).  When
+specified as
+.B --no-color
+it disables the display of the lines.
+
+.TP
+.BI -m,\ --[no-]marker \ [marker]
+enables or disable the use of markers. 
+.I marker
+can be \fIauto\fR, \fIno\fR or a Tioga marker specification. Like with 
+.IR --color , 
+.I auto
+makes the markers shift with every data set.
+
+.TP
+.BI --marker-color \ color
+exactly the same as
+.I --color
+except that it applies the the marker's color.
+
+.TP
+.BI --line-style \ linestyle
+sets the line style. As with previous parameters, 
+.I auto
+turns on automatic change, and you can specify any Tioga line
+style. Using 
+.I no
+removes completely lines.
+
+.TP
+.BI --line-width \ width
+sets the line width. This will be affected by any subsequent 
+.IR --rescale .
+
+
+.TP
+.B --[no-]interpolate
+wheter to turn on automatic interpolation for the next curves or
+not. Automatic interpolation just transforms lines between two
+consecutive data points into cubic splines. It looks very good in many
+cases. 
+
+.TP
+.BI --error-bar-color \ color
+.B ctioga
+version 1.4 has a support for error bars, and this options enables one
+to select their color. See discussion on the 
+.I text
+backend below for more details about how to get error bars in the
+first place.
+
+
+.TP
+.BI --drawing-order \ order
+Have you ever wanted to have your markers in a different color and 
+.I behind
+the lines ? You can use this option to do so. It takes an integer
+between 0 and 5, and specifies the order in which the lines, the
+markers and the error bars are drawn on the resulting PDF. The last
+will be the most visible in the end. Any invalid argument for 
+.I order
+will show which numbers are valid and what they mean.
+
+.\" --------------------------------------------------------------------
+.SS Transparency
+
+.TP
+.BI --transparency \ transparency
+.TP
+.BI --marker-transparency \ transparency
+.TP
+.BI --error-bar-transparency \ transparency
+Sets the transparency for drawing respectively lines, markers and
+error bars. The transparency is a number
+between 0 and 1, 0 meaning perfectly opaque and 1 absolutely
+invisible.
+
+.\" --------------------------------------------------------------------
+.SS Fillings
+
+From 
+.B ctioga 
+version 
+.IR 1.5 ,
+it is possible to fill spaces under the curves. You need to specify a 
+.I y
+value where the filling will go to. The boundary for that has to be
+a horizontal line. It is specified using the 
+.I --fill-type
+option:
+
+.TP
+.BI --fill-type \ type
+Sets the fill type for filling next curves. The fill type can be
+.RS 4
+.TP 12
+.I none
+for no filling
+
+.TP 
+.I y_axis
+to fill until the 
+.I y = 0
+line
+
+.TP 
+.IR bottom ,\  top
+to fill respectively to the bottom or to the top of the current graph
+
+.TP
+.I y = val
+to fill until the 
+.I y
+value 
+.IR val .
+.RE
+
+.TP
+.BI --fill-color \ color
+The color for the fill. If specified neither by you nor by the current
+theme, it defaults to the current plotting color.
+
+.TP
+.BI --fill-transparency \ trans
+Sets the transparency for fills. I daresay, it looks very cool with a
+transparency of around 0.5.
+
+.\" --------------------------------------------------------------------
+.SS Histograms
+
+.B ctioga 
+version 1.5 brings a much more powerful way to make histograms. Here
+are the functions dealing with that:
+
+.TP
+.BI --hist \ type
+All subsequent curves will be histograms. The 'type' of histogram used
+depends on the 
+.I type
+argument. It can be
+.IR no \ or \ off
+to stop making histograms, 
+.I old-style
+to use the old style histograms: steps without sides. Then, you can
+use the same kind of specification as for the 
+.I --fill
+option to specify the level at which the steps should start/stop. 
+.B Important:
+please note that if you use something else than 
+.I old-style
+for this argument and that you fill the resulting curves, the actual
+argument to 
+.I --fill
+will be ignored and will be considered the same as the
+.I type
+one of the
+.I --hist
+option: not taking the same thing always leads to pretty
+disgusting results. However, please note that you need to use 
+.I --fill 
+with a valid argument to actually get a filled histogram.
+
+.TP
+.BI --hist-left \ left
+.TP
+.BI --hist-right \ right
+Set respectively the position of the left or the right side of the
+step relative to its total size. If you want that the steps are
+joined, use respectively 0 and 1. Other values will change the
+apparent width of the steps. Please note that nothing prevents you
+from setting either value outside the [0,1] interval where these
+values make sense. But don't complain if it looks ugly.
+
+.TP
+.BI --hist-width \ width
+A convenience interface for the 
+.I --hist-left
+and
+.I --hist-right 
+options. Basically sets the left and right boundaries so that the
+apparent width of the step is 
+.I width
+times its real size and that the results are centered on the interval.
+
+.TP
+.B --no-hist
+Stop making histograms.
+
+.TP
+.B --[no-]histogram
+This is the old option, here to keep old things working. It is the
+equivalent of either the 
+.I --hist old-style
+option or the 
+.I --no-hist
+one. Don't use it. Anyway, new histograms look way better !!
+
+.\" --------------------------------------------------------------------
+.SS Themes and sets
+
+.TP
+.BI --theme \ theme
+chooses the theme. Themes are little pieces of Ruby code that can take
+care of many detail of presentation, to help you focus on the data you
+want to plot, and not on the details about presentation. 
+.B ctioga
+will automatically load themes in the 
+.I themes/
+subdirectory of your 
+.I rubylib/CTioga
+directory, and also on your personal
+.I $HOME/.ctioga/themes
+directory. A good place to start to write your own theme is to take
+the 
+.I rubylib/CTioga/themes/demo.rb
+file and tweak it until it suits your needs.
+
+.TP
+.BI --theme-list
+lists all the themes 
+.B ctioga
+found. If for some reason the theme you wrote doesn't show up here,
+you can give a try at the
+.I --debug
+flag, it should give relevant information about the problem.
+
+.TP
+.B --reset-theme
+resets the current theme, which essentially means: select the default
+color/marker sets and reset them. 
+
+.TP
+.B --mono
+sets up a monochromatic display: color is set to Black and linestyle
+changes with every set. Strictly equivalent to
+.IR --theme\  mono .
+
+.TP
+.BI --color-set \ set
+.TP
+.BI --marker-set \ set
+.TP
+.BI --marker-color-set \ set
+.TP
+.BI --line-style-set \ set 
+chooses the different color, marker, marker colors and linestyle sets
+available. The only way to get reliable data about available sets is
+to run
+.BI ctioga \ --help\fR,
+which lists them. To know how they look like, just try out dataset
+expansion:
+
+.I ctioga --math 'sin(x) + 1##8'
+
+Starting from 
+.B ctioga
+version 1.8, you can use directly colors, markers and so on for sets,
+and you get a set with only this color/marker/linestyle. 
+
+.\" --------------------------------------------------------------------
+.SS Style manipulations
+
+.TP
+.B --skip-style
+Does not use the next theme style, but skips to the next one.
+
+.TP
+.B -s, --same-style
+Apply the same style to the next curve as to the last curve. This
+actually only applies to elements of style deemed that have been
+fed with the
+.I auto
+argument, which is nearly everything by default. Style can be further
+overridden by other style options.
+
+.TP
+.BI --save-style \ name
+Saves the style of the last curve under the name
+.IR name .
+
+.TP
+.BI --use-style \ name
+Uses a previously saved style for the next curve. Same provisions as
+for 
+.I --same-style
+apply. If 
+.I name
+has not been saved yet, it is interpreted as the number of the style
+we're interested in. 0 is the first, 1 the second, -1 the last, -2 the
+one just before and so on. 
+.I --same-style
+is therefore equivalent to
+.I --use-style -1
+(unless a style with name 
+.I -1
+has been saved beforehand).
+
+.TP
+.BI --reset-override
+Resets the current style override. See the section CURVE STYLES below
+for a detailed explanation of what are overrides.
+
+.TP
+.BI --save-override \ name
+The pendant of the 
+.B --save-style
+option, but for overrides only. See CURVE STYLES below.
+
+.TP
+.BI --use-override \ name
+Uses a previously saved override. See CURVE STYLES below.
+
+.\" --------------------------------------------------------------------
+.SS Shortcuts
+
+.TP
+.BI --short \ shortcut
+Uses the given shortcut. Shortcuts are a quick way to add many
+command-line arguments at once. See the SHORTCUTS section below.
+
+.TP
+.BI --short-list
+Lists available shortcuts, along with the command-line arguments they
+expand into.
+
+
+.\" --------------------------------------------------------------------
+.SS Edges and axes looks
+
+.TP 
+.BI --xaxis \ style
+.TP 
+.BI --yaxis \ style
+Gives some style informations about the 
+.I X
+or
+.I Y 
+axes and edges. 
+Valid arguments are:
+.IR left , \ right , \ top , \ bottom , \ org 
+that place axes only on the corresponding sides (org is the origin)
+with no edges.
+.I both
+sets edges on both sides.
+.IR hidden , \ line , \ ticks , \ major , \ majornum \ and \ full
+which select the style for both edges and axes (hidden, line only,
+line with major and minor ticks, major ticks only, major ticks with
+numeric labels, and major and minor ticks with numeric labels). You
+can specify several items separated by commas.
+
+.TP
+.B --no-axes
+Disable all axes and edges for the current plot.
+
+
+
+.TP
+.BI --lines-color \ axis\ color
+Selects the color for drawing background lines corresponding to the
+named
+.IR axis .
+Lines are starting from major ticks. If you use that with both the X
+and Y axis, you'll have a background grid.
+
+
+.\" --------------------------------------------------------------------
+.SS LaTeX options
+
+.TP
+.BI --use \ package
+Adds a 
+.BI \eusepackage{ package }
+in the LaTeX preamble of the file. This can be very useful to depend
+on custom style files for fonts or to use standard or personal
+macros. 
+
+.TP
+.BI --preamble \ string
+Adds the given 
+.I string
+on a line of its own inside the LaTeX preamble. This can give
+basically any kind of customization that the 
+.I --use
+option cannot. You are however strongly encouraged to use 
+.I --use
+whenever it is possible.
+
+.\" --------------------------------------------------------------------
+.SS Global appearance
+
+.TP
+.BI --[no-]background \ color
+Sets the background color of the current plot, or removes it
+altogether for the current plot.
+
+.TP
+.BI --[no-]watermark \ TEXT
+Adds a text watermark at the back of the plot.
+
+.TP
+.BI --watermark-color \ COLOR
+Sets the color for the watermark.
+
+
+.TP
+.BI --aspect-ratio \ ratio
+sets the aspect ratio of the plot (the ratio of it's length over it's
+height). 
+.I Deprecated, do not use !
+
+.TP
+.BI --golden-ratio
+sets the aspect ratio to the golden number. Looks good.
+.I Deprecated, do not use !
+
+.TP
+.BI --xrange \ range
+.TP
+.BI --yrange \ range
+sets the current X or Y plotting range; arguments are in the form 
+.IB left : right
+where 
+.IR left \ or \ right
+can be omitted. If you swap them, the plot will be swapped as
+well. 
+.B NOTE: 
+these settings are completely uncorrelated with the ones from the
+mathematical backend. 
+
+.TP
+.BI --margin \ margin
+sets a margin around data when plotting. If your plot has many data
+points near the edge, try something between 0.01 and 0.05. See the
+MARGINS section below for more explanations about how to specify
+margins. 
+
+.TP
+.BI --rescale \ factor
+scales the current picture by 
+.IR factor .
+This is especially useful for subplots and insets, but it can be used
+anywhere. 
+
+.TP
+.BI --padding \ padding
+Sets the padding for the current object and subsequent ones to 
+.IR padding . 
+The latter should be in the form of
+.IB left , right , bottom , top
+or
+.IB left , right , bottom and top
+or
+.IB left and right , bottom and top
+or 
+.IR all .
+Each of the elements can be a valid (absolute) TeX dimension, such as
+.I 10cm
+or
+.IR 12pt ,
+or a number, in which case the dimension is relative to the current
+graph (but be careful in grids, as it is relative to the 
+.I whole 
+graph, and not simply to the current element).
+See the section LAYOUT below for an explanation of what is the padding.
+
+
+
+.\" --------------------------------------------------------------------
+.SS Subplots and assimilated...
+
+.TP
+.B --x2\fR,\fB --y2
+Use an alternative 
+.I x
+or
+.I y
+axis until the matching
+.I --end
+is encountered. Useful to plot, say, two different data that have
+different Y values but share the same X values.
+
+.TP
+.BI --inset \ spec
+Starts an inset at position 
+.IR spec . 
+See the INSETS section for more details about the exact
+specification. The plot decorations (title, labels) are 
+.I outside
+the box specified by
+.IR spec .
+
+.TP
+.BI --zoom-inset \ spec
+This is very much like the 
+.I --inset
+option, except that the new inset starts with all the curves that
+have already been added to its parent. This is really useful to zoom
+into particular places of the curves, using the 
+.I --xrange
+and
+.I --yrange
+options. Legend is not added for the curves duplicated this way.
+
+.TP
+.BI  --next-inset \ spec
+Leaves the current inset/subplot and starts a new inset at the given
+position. See the INSETS section for more details. 
+.B NB:
+you need to 
+.I --end
+the current 
+.I --x2
+or
+.I --y2
+specification before using that, else you'll get rather unexpected
+results.
+
+.TP
+.BI --subplot \ spec
+
+.TP
+.BI --next-subplot \ spec
+these two options have the same effet as 
+.I --inset
+and 
+.IR --next-inset ,
+with the exception that, unlike for insets, the decorations (title,
+labels) are 
+.I inside 
+the box delimited by
+.IR spec .
+
+
+.TP
+.B --disable-legends
+No legend will be taken into account after this switch for the current
+subplot. 
+
+.TP
+.B --enable-legends
+Reverts 
+.IR --disable-legends .
+
+
+.TP
+.BI --grid \ spec
+Start a grid with a number of column or rows given by 
+.IR spec ,
+which can be either
+.BI column= nb
+or
+.BI row= nb\fR.
+You start a new plot by using the 
+.I --next
+option.
+
+.TP
+.BI --col
+Starts a column of plots sharing the same X range. New plots start
+with 
+.IR --next .
+
+.TP
+.BR --[no-]auto-next ,\  --auto-next-expanded
+After the use of this option, 
+.B ctioga
+considers that there is a
+.I --next
+before every single data set specification on the command-line
+(except the first one). The
+negation permits to cancel this behavior. With
+.IR --auto-next-expanded ,
+.B ctioga
+first performs dataset expansion and places 
+.I --next
+before the resulting datasets. 
+
+
+.TP
+.B --region
+Starts a filled region. This is primarily used for filling space
+between curves. See the 
+.B FILLED REGIONS
+section below for a more complete explanation.
+
+.TP
+.BI --region-color \ color
+Sets the color used for filling the current region.
+
+.TP
+.BI --region-transparency \ transparency
+Sets the transparency of the region's fill.
+
+
+.TP
+.BI --region-dont-display
+No curve in the region will be displayed. They will only be used to
+delimit the filled region.
+
+.TP
+.BI --region-debug
+Helps understanding how the filling works by tampering with the style
+of the plots inside the region to fill them so as to represent the
+actual clipping path: the filled region will be the one coloured by
+the colors of all the plots.
+
+.TP
+.BI --region-invert-rule
+Reverts the rule for delimiting the filling region. See the 
+.B FILLED REGIONS
+section below.
+
+.TP
+.BI --region-fill-twice
+Fills the region twice, using opposite rules for determining the
+filling region. You really should have a look at the
+.B FILLED REGIONS
+section below to understand that. It will probably give better results
+in the case of intersecting curves.
+
+
+.TP
+.B --end
+Ends the current subplot, grid, inset or region.
+
+
+.\" --------------------------------------------------------------------
+.SS Labels and titles (including tick labels)
+
+.TP
+.BI -x,\ --[no-]xlabel \ label
+sets the x axis label of the current plot, or removes it.
+
+.TP
+.BI -y,\ --[no-]ylabel \ [label]
+sets the y axis label of the current plot, or removes it.
+
+.TP
+.BI -t,\ --[no-]title \ [title]
+sets the title of the current plot, or removes it.
+
+.TP
+.BI --side \ what\ align
+.TP
+.BI --lcolor \ what\ color
+.TP
+.BI --position \ what\ where
+.TP
+.BI --angle \ what\ angle
+.TP
+.BI --scale \ what\ scale
+.TP
+.BI --shift \ what\ shift
+.TP
+.BI --align \ what\ align
+.TP
+.BI --just \ what\ just
+Sets respectively the side, color, position, angle, scale, shift,
+alignement or justification of the 
+.I what
+label, where 
+.I what
+can be either
+.IR title , \ xlabel , \ ylabel , \ xticks \ or \ yticks .
+
+Please note that the 
+.I color
+attribute is not available for tick labels.
+
+
+.\" --------------------------------------------------------------------
+.SS Legends and texts
+
+
+.TP
+.BI -l,\ --[no-]legend \ [legend]
+sets the legend of the 
+.I next
+dataset, or removes it from the legend display.
+
+.TP
+.BI --[no-]auto-legend 
+.B ctioga 
+automatically provides default legends for plots that don't have
+one. This option allows one to turn this off and back on. 
+
+.TP
+.B -N\fR,\fB --no-legends
+are shortcuts for 
+.IR --no-auto-legend .
+
+.TP
+.BI --[no-]separate-legends
+For inclusion of a graph in an article, it is sometimes useful to be
+able to include the legend "pictogram" (the small image next to the
+text) directly from within the article, and not on the graph. With
+this option, automatic legending is turned off, and 
+.B ctioga
+produces files of the form
+.IR Plot_legend_00.pdf , \ Plot_legend_01.pdf ,\ aso.
+which contains only the small pictograms. You can then include those
+in your article with the
+.I \eincludegraphics
+command to make your own in-text legend.
+
+.TP
+.BI --fontsize \ nb
+Sets the default TeX font size for text. It is passed directly to TeX
+without interpretation, so mistakes in this parameter might result in
+very cryptic error messages.
+
+.TP
+.BI --legend-scale \ scale
+Changes the default scale for the legends. This does influence the
+size of the text and the pictograms, and also to some extent the
+positioning of the legends.
+
+.TP
+.BI --legend-pos \ spec
+Sets the legend position on one of the side of the plot. 
+.I spec
+is in the form 
+.IB side , size , delta
+where 
+.I side
+is
+.IR left , \ right , \ top , \ bottom , 
+.I size
+is the fraction of the page that will be dedicated to the plot (best
+take it rather smaller than 1...) and 
+.IR delta ,
+optional, is the fraction of the page that should be left blank
+between the legend and the plot itself. 
+
+.TP
+.BI --legend-inside \ spec
+Position te legend inside the plot. The specification 
+.I spec
+is the nearly same as for insets, see the INSETS section
+for more information.
+
+.TP
+.BI --legend-dy \ dimension
+The distance between two lines of the legend, in terms of the height of
+one text line.
+
+.TP
+.BI --legend-line \ text
+Adds a line of text without any pictogram to the legend.
+
+
+.TP
+.BI --[no-]legend-frame \ [type]
+If 
+.I type
+is
+.I round
+or
+.I square\fR,
+draws a (rounded or square) frame around the legends. Best used in
+combination with the 
+.I vh:x,y
+.B --legend-inside
+specifications.
+If 
+.I none\fR,
+cancels the drawing of the frame.
+
+.TP
+.BI --[no-]legend-color \ [color]
+Sets the color of the frame to be drawn when 
+.B --legend-frame
+is on, or cancels the drawing of the frame (this way, you can have a
+filled box without a line around). 
+
+.TP
+.BI --[no-]legend-background \ [color]
+Sets the background color of the legend frame to 
+.I color\fR,
+or stops drawing a background for the legend frame. Works only when a
+legend frame is being drawn.
+
+.TP
+.BI --[no-]legend-transparency \ [value]
+Sets the transparency value for the background of the legend to 
+.I value\fR,
+or make the legend fully opaque.
+
+.TP
+.BI --legend-line-width \ value
+Sets the line width for drawing the frame around the legend.
+
+.TP
+.BI --legend-line-style \ style
+Sets the line style for drawing the frame around the legend.
+
+
+.\" --------------------------------------------------------------------
+.SS Axis manipulations
+
+.TP
+.BI --xfact \ f ,\ --yfact \ f
+Scales the 
+.I x
+or the
+.I y
+values by a factor of
+.IR f .
+This can be useful to change the units in a graph. If say, you have
+.I x
+data expressed in meters, but in the range of nanometers, you can use
+.I --x-fact 1e9
+and use nanometers units...
+
+.TP
+.BI --xoffset \ f ,\ --yoffset \ f
+Adds the 
+.I f
+to the 
+.I x 
+or 
+.I y 
+values. This applies 
+.B after
+multiplication by
+.I --xfact
+or
+.IR --yfact ,
+if the latter is applicable. Useful for instance to convert on the fly
+Celsius degrees to kelvins.
+
+.TP
+.B --[no-]xlog, --[no-]ylog
+Swicthes on or off the log scale for the axes. These options 
+must appear 
+.B before
+any data set. 
+.B ctioga
+ will most probably fail if they don't.
+
+.B Note:
+this option has no effect on the sample rate of the 
+.I math
+backend. You probably want to use 
+.I --math-log
+in addition to this to get a decent output when using the
+.I math
+backend.
+
+.TP
+.B --reset-transformations
+Resets all the offset, scales and log options applied so far.
+
+.TP
+.BI --comma,\ --decimal\  SEP
+uses 
+.I SEP
+as a decimal separator for axis (or a comma for
+.IR --comma ,
+obviously). It is based on LaTeX black magic, so it might fail from
+time to time. Please do report cases when it does.
+
+
+
+.\" --------------------------------------------------------------------
+.SS Real size options
+
+.TP
+.BI -r,\ --real-size\ size
+Turns on the real size mode for 
+.IR ctioga .
+.I size
+should look like
+.IR 10cmx12in .
+The PDF file produced will have exactly the size requested, with the
+plot filling as much as possible. You can include it in your
+documents with the TeX command
+.IR \eincludegraphics .
+
+.TP
+.BI --frame-margins\  margin
+With the
+.B --real-size
+option, when the sizes are small, the text around the plot can be
+clipped off the graph. Try to set the
+.I margin
+a bit higher with this parameter (try something like 0.2, and go on
+increasing until you find something decent).
+.B Important note:
+with the new layout mechanism introduced in 
+.B ctioga 
+version
+.IR 1.6 ,
+it is no longer necessary to use this option, except in the most
+desperate cases. See the section LAYOUT below.
+
+.\" --------------------------------------------------------------------
+.SS Graphics primitives
+
+.TP
+.BI --draw \ spec
+Adds a graphic primitive to the current graph, using the
+specification 
+.IR spec . 
+See the 
+.B GRAPHIC PRIMITIVES
+section below for more details about the specifications.
+
+.TP
+.BI --draw-help
+Lists the graphic primitives currently known to 
+.BR ctioga ,
+along with the options they currently handle and pointers to the
+appropriate functions in the 
+.B Tioga 
+documentation. By construction, the output of this function will
+always be a perfect reflection of the capabilities of 
+.BR ctioga .
+
+
+
+.\" --------------------------------------------------------------------
+.SS Backend-related options
+
+See the sections BACKENDS and FILTERS for more details.
+
+.TP
+.BI --text
+
+.TP
+.BI --text-skip
+
+.TP
+.BI --text-baseline
+
+.TP
+.BI --multitext
+
+.TP
+.BI --multitext-skip
+
+.TP
+.BI --math
+
+.TP
+.BI --math-samples \ number
+
+.TP
+.BI --math-xrange \ range
+
+.TP
+.BI --smooth\  number
+.TP
+.BI --sort
+
+.TP
+.BI --filter-pop
+
+.TP
+.BI --filter-clear
+
+and more...
+
+.\" --------------------------------------------------------------------
+.SS Miscellaneous options
+
+.TP
+.BI --xpdf
+runs
+.I xpdf
+on the PDF file produced to see the results.
+
+.TP
+.BI --open
+runs
+.I open
+on the PDF file produced to see the results.
+
+.TP
+.BI --viewer \ viewer
+opens the PDF file produced with
+.IR viewer .
+
+.TP
+.BI --no-viewer
+cancels the opening of the file if requested earlier (such as in a
+configuration file, see next section).
+
+.TP
+.BI --args \ file
+Reads command-line arguments or options, 
+.B one per line\fR,
+from 
+.I file\fR.
+An option and its arguments must be on separated lines. This can be
+useful to avoid excessive quoting for complex plots
+
+
+.TP
+.BI --[no-]cleanup
+wether or not to remove all files created by the plot apart 
+from the pdf output. This is not a good thing is case you want to
+include the picture inside a LaTeX file. In the latter case, you might
+want to prefer the next option.
+.B Important note:
+from 
+.B ctioga
+version 1.5, this option is on by default (I'm fed up to always forget
+it and clean up manually afterwards).
+
+.TP
+.BI --tex-cleanup
+removes all files produced except the 
+.I _figure.pdf
+and
+.I  _figure.txt
+as those ones are used for inclusion in LaTeX documents using the
+.I \etiogafigure
+Tioga-provided commands.
+
+.TP
+.BI --clean-all
+removes all files produced, after displaying the PDF file produced (if
+you did ask to display something). 
+
+.TP
+.BI --include \ file
+.I file
+is read and evaluated as ruby code. See next section for more informations.
+
+.TP
+.BI --save-dir \ dir
+files will be created in the directory
+.I dir
+rather than in the current directory. 
+.\"Comes in quite convenient...
+
+.TP
+.BI --name \ name
+the base name for files will be 
+.I name
+rather than Plot.
+
+.TP
+.BI --output \ name
+Asks
+.B ctioga
+to write the figure created up to this flag to the file
+.I name.pdf
+just as if you had written
+.I --name name
+and stopped the command-line here. Further output is still
+produced. This can be used to create animations, such as:
+
+.I ctioga --math 'sin(x)' --output One_sine 'cos(x)' --name Two_sines
+
+which produces two files: 
+.I One_sine.pdf
+that contains only the
+.I 'sin(x)'
+curve, and 
+.I Two_sines.pdf
+that contains both
+.I 'sin(x)'
+and
+.I 'cos(x)'
+curves.
+
+.TP
+.BI --display-commandline
+the command-line used to make the plot is written in black at the
+bottom of the plot. No care is taken to ensure it doesn't overwrite
+any existing drawing. It can come in useful when sending image to
+someone or when one forgets too quickly how to make plots (which is
+the case of the author of
+.B ctioga\fR). 
+Now,
+.B ctioga
+includes by default the command-line as a comment of the produced PDF
+file. Tools like 
+.I pdfinfo
+can be used to retrieve it, see the 
+.B --mark
+command just below.
+
+
+.TP
+.BI --[no-]mark
+.B ctioga 
+can fill the 
+.I creator
+meta-information field of the produced PDF file with the
+command-line. This is a useful feature, as you can use  
+.I pdfinfo(1)
+to see which command-line was used to produce a given file (it is also
+displayed in 
+.IR acroread(1) ).
+However, it can sometimes prove to be painful, as the text is
+interpreted by TeX and causes funny errors. 
+This is why it is switched off by default. You can turn it on
+(and back off) with this switch.
+
+
+.TP
+.B --echo
+writes the ctioga command-line on standard output. Especially useful
+for examples found in the 
+.I tests/
+directory, but you might find uses for that too.
+
+.TP
+.BR --quiet ,\ --verbose ,\ --debug
+These options choose the verbosity level of
+.B ctioga\fR.
+With
+.B --quiet\fR,
+only errors are reported, while you get increasing amount of messages
+with
+.B --verbose
+which culminates in
+.B --debug\fR.
+The latter is so full of information you'll probably never find
+anything unless you wrote
+.B ctioga\fR.
+
+.TP
+.B --version
+Writes the version of 
+.B ctioga
+on standard output and exits.
+
+.SS Alternative outputs
+
+.TP
+.BI --eps
+With this option,
+.B ctioga
+does not call pdflatex, but rather transforms the intermediate PDF
+file into an EPS file using pdftops (from xpdf) and then calls latex
+followed by dvips to produce an EPS file. This results essentially in
+a difference in the type of the fonts used, and can ease the
+integration of 
+.B ctioga
+graphs into pure LaTeX document (not generated with pdfLaTeX).
+
+.TP
+.BI --png \ width x height
+Runs
+.B ctioga
+as usual, but converts the produced PDF file into a PNG file of size 
+.IB width x height
+with the convert program from ImageMagick. The PDF file produced is 
+.B not
+deleted. This option also changes the real size of the graph to match
+the size of the PNG file produced (on postscript point for one
+pixel). This can always be changed later on.
+
+.TP
+.BI --png-oversampling \ nb
+The conversion to PNG will use a resolution of
+.I nb
+times more pixels in each dimension before rescaling. The higher this
+number, the better the antialiasing will be. Output is fairly decent
+with numbers around 2 (the default) to 3. You might need to tweak this
+option if you use
+.I --real-size 
+after the
+.I --png
+option.
+
+.TP
+.BI --svg
+Runs
+.B ctioga
+as usual, and then converts the produced PDF file into a SVG file
+using
+.B pdf2svg\fR.
+
+
+
+.SS Debugging options
+
+.TP
+.BI --debug
+This options enables some debugging output, especially when things
+don't quite end up as expected. It is more designed for developpers,
+though. See above, too.
+
+.TP
+.B --debug-patterns
+Produces two more graphes, called 
+.I Test_patterns
+and
+.I Test_patterns_right
+that show if the alignment of the graphes produced by 
+.B ctioga
+with the given command-line options are correctly aligned. If somehow
+you find that it is not, you 
+.B should
+file a bug report (with the full command-line and the PDF files
+produced).
+
+.SH "INSETS"
+
+Starting from release 1.8, 
+.B ctioga
+provides three ways to specify the position of insets, subplots and
+inner legends: 
+
+.TP
+.IB x , y : w[ x h]
+centers the object at position 
+.IB x , y
+with a width of 
+.I w
+and a height of
+.IR h ,
+or 
+.I w
+if 
+.I h
+was not specified. All values are from 0 to 1, relative to the
+container. 
+
+.TP
+.IB x1 , y1 ; x2 , y2 
+places the object with the exact border coordinates given by 
+.IB x1 , y1
+and
+.IB x2 , y2\fR.
+As for the other ways, all positions are between 0 and 1 and relative
+to the container.
+
+.TP
+.IB h x w [+|-] x [+|-] y
+A X Geometry-like specification. The box will be of height 
+.I h
+and of width
+.I w
+and the point
+.I x,y
+is the left (+) or right (-) top (+) or bottom (-) corner of the box.
+
+.SS Legend box
+
+The 
+.B --legend-inside
+can take an inset specification as argument. However, from version
+.B 1.9\fR,
+it can also take another form:
+
+.IB vh : x ,y
+
+where 
+.I v
+is the vertical centering (\fIt\fR for top, \fIc\fR for center and
+\fIb\fR for bottom), 
+.I h
+is the horizontal centering (\fIl\fR for left, \fIc\fR for center and
+\fIr\fR for right),
+and
+.I x
+and 
+.I y
+are the coordinates. For instance
+
+.I --legend-inside tl:0.5,0.5
+
+will place the top left of the legends at the exact center of the
+drawings.
+
+Starting from 
+.B ctioga
+version
+.I 1.10\fR,
+it is possible to omit altogether the positions. To put the legend in
+the top left of the graph, simply use:
+
+.I --legend-inside tl
+
+
+.SH "LAYOUT"
+
+Since 
+.B ctioga
+version 1.6, a relatively complex layout system has been incorporated
+to the code. The layout is responsible mainly for leaving enough space
+around plots so you can actually see labels and ticks. As of version
+1.8, only one parameter of the layout system is accessible: something
+I call the padding. It represents the
+.I minimal
+amount of space that should be left on the sides of a graph. The
+actual space left may be bigger due to the presence of elements, such
+as labels. You can control it via the
+.I --padding
+option.
+
+
+.SH "CONFIGURATION FILES"
+
+At startup, 
+.B ctioga
+looks for a 
+.I .ctiogarc
+file in the current directory and in the
+.I $HOME
+directory. This file is then read and evaluated as ruby code. The
+functions provided in this file are then made available to the
+backends. You can use it for two purposes:
+
+.TP 2
+.B * 
+define your own functions that can be called by backends such as the 
+.I --math
+backend.
+.TP
+.B *
+before starting to process the command-line, if a function
+.I ctioga_defaults
+is defined, ctioga runs it. It can be used to set default values for 
+.IR ctioga .
+You are strongly advised to look at the file
+.I plotmaker.rb
+to see what you actually can modify. This function is run in the
+context of the 
+.I PlotMaker
+instance created.
+.TP
+.B *
+before doing the actual plotting, 
+.B ctioga
+looks for a function named 
+.I ctioga_init
+and if it finds it, it calls it passing it the 
+.I FigureMaker
+object used to make the plots. 
+You can use that function to customize the appearance of the
+graphes. You will find Tioga's rdoc documentation really useful for
+doing so.
+
+.P
+
+.P
+The files passed to 
+.B ctioga
+with the 
+.I --include
+option are treated exactly the same way, and in the order they are
+found. From the description above, you can guess that it's pretty
+useless to have a
+.I ctioga_defaults
+in such a file, as it will not be taken into account (although this
+could be interesting as well).
+
+.SH GRAPHIC PRIMITIVES
+
+Starting from ctioga 1.4, it is now possible to add simple graphic
+elements to a graph, such as text labels, markers and arrows. It is
+additionally possible to add tangent to the last curve plotted. You
+should be somewhat familiar with the Tioga documentation to make the
+best of them, although simple use should be straightforward.
+
+You use graphic primitives with the
+.B --draw
+option. It takes a single argument (a long one), which is further
+broken into separate words in the same way the shell would do it. This
+argument must have the following form:
+
+.IB what :
+.I mandatory arguments
+.I option1=thing option2=thing...
+
+In this, 
+.I what
+is the graphic primitive that can be used, the mandatory arguments must
+always be specified; they often are coordinates of meaningful
+points. Optional arguments follow a 
+.IB key = value
+syntax, and can be completely omitted. Their name is the same as in
+the dictionnary in the 
+.I Tioga
+function. See the 
+.B --draw-help
+command-line switch for a list of supported keys.
+
+Points are specified using
+.IB x , y
+values. Please note the absence of space between the coordinates.
+
+.B  ctioga
+understands the following primitives:
+
+.TP
+.BI arrow: \ tail\ head
+Draws an arrow from the point
+.I tail
+to the point
+.I head.
+
+.TP
+.BI line: \ tail\ head
+Same thing as the
+.B arrow
+primitive, excepted that arrow heads and tails are disabled by
+default.
+
+.TP 
+.BI hrule: \ point\ size
+Draws a horizontal ruler at the given point of the given size.
+
+.TP 
+.BI vrule: \ point\ size
+Draws a vertical ruler at the given point of the given size.
+
+.TP
+.BI text: \ point\ text
+Places a TeX text at the location
+.IR point .
+Please note that you need to quote 
+.I text
+if there are spaces or quotation marks inside.
+
+.TP
+.BI marker: \ point\ marker
+This is the pendant of 
+.I text
+for markers.
+
+.TP
+.BI tangent: \ spec
+This is not strictly speaking a graphics primitive, but it comes in
+very handy to place tangents to a curve. See below for the meaning of 
+.IR spec .
+(not documented yet)
+
+All these primitives accept additional options. It would be too long
+to describe them here, but the
+.I --draw-help
+option lists them all and gives pointers to the function in the 
+.B Tioga
+documentation where you will find documentation about them.
+
+.P 
+For example, to place a piece of text at the origin, use
+
+\" The following 'escape sequence' is pretty ugly, but it turned
+\" out to be the only one that works...
+
+.I --draw 'text: 0,0 \fI"Some text" '
+
+Note the quotes within quotes around 
+.IR  Some\ text . 
+To do the same, but text tilting 45 degree from
+horizontal and with a nice (!) pink color, this would do:
+
+.I --draw 'text: 0,0 \fI"Some text" angle=45 color=Pink'
+
+\" .SS Tangents
+
+\" A tangent to a curve is essentially an arrow with a direction given by
+\" the slope of the curve at a given point, and 'centered' around this
+\" point. To specify this point, you have several ways:
+
+
+.SH CURVE STYLES
+
+.B ctioga
+has a pretty advanced mechanism for choosing a style for a
+curve. This mechanism has been designed to provide maximum flexibility
+while keeping the command-line to its minimal.
+Styles are the result of the interaction of two elements
+
+.TP 2
+.B *
+the theme, which is providing a base for the style of a curve
+
+.TP
+.B *
+the override, that is any style-related options that have been passed
+on the command-line.
+
+.P
+
+When 
+.B ctioga
+needs to know the style of the next curve, it first asks the 
+.B theme
+to provide one. Usually, the styles provided by the themes will change
+at every curve. Then, the style is modified taking the override into
+account. A 
+.I --color Red
+command-line option sets the 
+.I color
+override to 
+.IR Red ,
+which means that every single curve after that, until the override is
+changed, will be red.
+
+A
+.I --color auto
+option removes the override for
+.IR color ,
+so that the actual color used is the theme's one.
+
+The default override is to set the
+.I markers
+to 
+.IR no , 
+so that by default no markers are present. The use of 
+.I --reset-override
+restores the default override (which would remove markers...).
+
+Finally, the 
+.I --save-style
+option saves the style effectively used for the last curve. The 
+.I --use-style
+option prevents 
+.B ctioga
+from asking the theme to provide a base style, but rather uses the
+saved style as if the theme had provided it.
+
+.SH SHORTCUTS
+
+Starting from 
+.B ctioga
+1.7, it is possible to use shortcuts on the command-line. Shortcuts
+are used with the
+.I --short
+option and expand into a series of command-line arguments. For
+instance, 
+.I --short cloud
+expands into
+.I --marker auto --marker-scale 0.2 --line-style no\fR,
+which is very convenient to make dot clouds. You can list available
+shortcuts along with what they expand to with the
+.I --short-list 
+option. You can define shortcuts in your 
+.I ~/.ctiogarc
+file with something in the spirit of
+
+.I Shortcut.new('pink', '--color', 'Pink', '--marker-color', 'Pink')
+
+This line defines a 
+.I pink
+shortcut that expands to
+.I --color Pink --marker-color Pink\fR. 
+You use it simply by passing the 
+.I --short pink
+option to 
+.B ctioga\fR.
+Better, if it does not conflict with existing options, you can use it
+directly as 
+.I --pink\fR.
+
+
+passing 
+Be sure to separate all arguments (which you would separate with
+spaces on the command-line) with 
+.IR commas ,
+and to enclose them in single or double quotes.
+Failing to do so will most likely result in 
+.B ctioga
+complaining about unknown options. 
+
+
+You can make sure 
+.B ctioga
+sees these definitions with the
+.I --short-list 
+option. If they don't show up there, you might have either a
+compilation problem in you
+.I ~/.ctiogarc
+file, or you simply didn't really write it there...
+
+
+
+
+.SH MARGIN SPECIFICATION
+
+Several options accept a specification for margins. You need to
+remember that Tioga, and hence ctioga counts margins as a fraction of
+the total relevant length from the given side. So, if the right margin
+is at 
+.IR 0.2 ,
+it means that it will take the right 
+.I 20%
+of the image. The specification is
+
+.I left,right,top,bottom
+
+where each of the component is a number between 0 and 1. All distances
+are always relative to the direct container: margins for the whole
+plot are relative to the size of the whole plot.
+
+.SH FILLED REGIONS
+
+With the 
+.I --region
+option, you start a filled region, which means that all subsequent
+plots until the next
+.I --end
+option will serve, in addition to be displayed normally, as a way to
+delimit the region where the fill will occur, according to the
+following simple rule: every odd plot will be closed by a line at the
+top of the figure, every even one by a line at the bottom. The
+resulting path will be used as a clipping path for the region. To
+understand which region will be filled, imagine that every curve is
+filled in the normal way to the top or the bottom of the plot. The
+colored region will be the one filled by all curves. The 
+.I --region-debug
+does precisely this and can be of a really great help to understand
+what is actually happening.
+
+If the 
+.I --region-invert-rule
+option is in order, the above rule gets reversed: every odd plot is
+closed to the bottom and every even one to the top. 
+With the
+.I --region-fill-twice
+option, the region is filled twice, once with each rule. 
+
+To make simple things simple, if you just want to be filling the space
+between two non-intersecting curves, just put the lower one firs or
+use
+.I --region-invert-rule 
+if you don't want that.
+For relatively simple intersecting curves, you might want to try
+.IR --region-fill-twice ,
+as it tends to do what one wants (in my humble opinion).
+
+For more complex stuff, you can use the
+.I --region-dont-display
+to specify complex shapes and clip them. You can use multiple
+.I --region
+to get the desired effect.
+
+
+.SH "ENVIRONMENT VARIABLE"
+
+If a 
+.B CTIOGA
+environement variable is found, it is taken as a part of the command
+line, with some differences however:
+
+.TP 2
+.B *
+it is parsed before the command line;
+
+.TP
+.B *
+if a 
+.BI --include \ file
+option is present, the 
+.IR file 's
+.I ctioga_defaults
+function will be taken into account;
+
+.TP
+.B *
+it's contents don't show up in the 
+.B --display-commandline 
+display.
+
+.SH BACKENDS
+
+.B ctioga
+is based on the concept of 
+.IR Backends .
+Backends are classes that deal with acquiring the data. This can mean
+generate the data on the fly (like what the 
+.I math
+backend does), reading it from a text file (the
+.IR text ) 
+backend or from binary files or databases (backends yet to be
+written). For some backends, you can provide additional information
+with command-line switches. For some, a given set of command-line
+switches are necessary for good operation (not applicable yet).
+
+\" .P
+
+\" We will detail each available backend separately.
+
+.SS Set expansion
+
+Most of the backends come with a feature called 
+.I set expansion
+: it is possible to compactly transform a single set specification
+into several different data sets. For instance,
+.I file@1:2##4
+is transformed into
+.I file@1:2 file@1:3 file@1:4\fR.
+
+There are three patterns recognised by most of the backends:
+
+.TP
+.IB n ## m
+where 
+.I n
+and 
+.I m
+are numbers, is expanded into all the numbers from 
+.I n
+to 
+.I m
+included.
+
+.TP
+.BI #< n < code > m > 
+is expanded into the Ruby code 
+.I code
+with variable
+.B i
+ranging from
+.I n
+to
+.IR m .
+The value the block is returning is replaced
+in the set specification. This way, 
+.I #<1<i**2>4>
+expands into
+.I 1 4 9 16\fR.
+Please note the absence of spaces around 
+.I n
+and 
+.IR m . 
+
+.TP
+.BI #< var = n < code > m > 
+Although it looks very much like the previous one, this one is much
+easier to work with: the previous expands to a block of Ruby code,
+which means that you're likely to get into compilation errors. This
+way, however, expands the 
+.B string
+.IR code ,
+replacing any occurence of the variable named
+.I var
+by an integer value from 
+.I n
+to 
+.IR m .
+Contrary to the previous expressions, you can put arbitrary spaces. 
+
+
+.P
+The second and third expansions, though in appearance very similar,
+have completely different applications. 
+
+.P
+The second, 
+.BI #< var = n < code > m >\fR,
+works with a real Ruby expression that must return a 
+.I String
+object, or something that can be cast to a String, such as a number.
+This expansion can be used for instance to plot every second column of
+a file, using the following specification:
+
+.I ctioga file.dat@'1:#<2<i*2>6>'
+
+.B ctioga
+will expand that to the value of the expression 
+.I i*2
+with
+.I i
+ranging from 2 to 6. What we obtain is:
+
+.I ctioga file.dat@'1:4' file.dat@'1:6' ... file.dat@'1:12'
+
+The second expansion is well adapted to dirty tricks about data
+files. In principle, it is the most powerful expansion, as you get
+full ruby interpretation. But it can be delicate, as you need to think
+in terms of Ruby expressions.
+
+.P
+On the other hand, in the third, 
+.BI #< var = n < code > m > 
+you define a variable whose name will be replaced by all the numbers
+from
+.I n
+to \fIm\fR. In particular, we can't try the same trick as above: using
+
+
+.I ctioga file.dat@'1:#<n=2<n*2>6>'
+
+will result in 
+.B ctioga
+expanding that into:
+
+.I ctioga file.dat@'1:2*2' file.dat@'1:3*2' ... file.dat@'1:6*2'
+
+which is completely different than above. On the other hand, this
+expansion is much more suited to change a parameter that must appear
+in several places in the expansion, such as the followin:
+
+.I ctioga --math '#<n = 2< sin(n*x)/n>10>'
+
+which plots 
+.I sin(n*x)/n
+for all
+.I n
+values from 2 to 10.
+
+That is possible to do with the second expansion, but it is way
+heavier:
+
+.I ctioga --math '#<2<"sin(#{i}*x)/#{i}">10>'
+
+Note that the quotes are necessary, as we want to get a ruby string,
+and not the result of the computation of 
+.I sin(i*x)/i\fR,
+which will most likely result in a Ruby error, because it does not
+know about any
+.IR x .
+
+
+.SS The text backend
+
+Select it with the option
+.IR --text .
+It accepts four options:
+
+.TP
+.BI --text-skip \ number
+when reading subsequent files, the file
+.I number
+lines of the file are skipped.
+
+.TP
+.BI --text-baseline \ set
+this specifies that 
+.I set 
+should act as a baseline for every subsequent set. That is, the Y
+values of this set will be substracted to every single subsequent
+set. Use 
+.I no
+to cancel baseline.
+
+.TP
+.BI --text-col \ spec
+which column specification to use in case no one is specified. No
+expansion is performed here.
+
+.TP
+.BI --text-separator \ regexp
+a Ruby regular expression that designates the column separator.
+For instance, for CSV files, you could use 
+.I ,
+or
+.I ;
+or, even better
+.IR "'/[,;]/'" .
+
+
+.P
+
+It reads text files in a simple
+format (numbers separated with spaces) and seperates them in
+columns. The first column in the file is 1, and so on. You can access
+to the index of the line with the column number 0 (like in
+.IR gnuplot ).
+
+The general syntax of a data set is
+.IB file @ x_col : y_col
+with the following meaning:
+
+.TP 4
+.I file
+is the name of the file where the data is. If it is omitted, the last
+file opened by the backend is used.
+
+.TP
+.IB x_col : y_col
+are column specifications. If they are simple numbers, the
+corresponding columns are used: 
+.I 3:1
+asks to plot the first column as a function of the third. 
+On the contrary if they contain at least one \fI$\fR  
+sign, then they are interpreted as a function of the columns, where 
+.I $n
+represents the nth column:
+.I $2**2:$1*$3
+asks to plot the product of column 1 and 3 as a function of the square
+of the second. Arbitrary expressions can be used, as well as functions
+defined in configuration or included files. Please note that in the
+latter case you will most probably need to quote the arguments with 
+.I single quotes
+to prevent the shell from tampering with your arguments.
+
+.P
+If the 
+.BI @ x_col : y_col
+is omitted, then it defaults to 
+.IR \fB@\fI1\fB:\fI2 ,
+or the the value given to the 
+.B --text-col
+option if the latter was specified before.
+
+.P
+The text backend supports an extansion to the set expansion mechanism
+described earlier, in that you can ommit the trailing number in
+a 
+.I n##m
+specification. In this case, the last digit is taken to be the number of
+the last column in the file. If 
+.I file.dat
+has 4 columns,
+.I file.dat@1:2##
+is exactly equivalent to
+.IR file.dat@1:2##4 .
+
+Starting from 
+.B ctioga
+version 1.4, the text bacjend supports error bars. You do it using
+extra column specifications, such as in the following:
+
+.IB file.dat : 1 : 2 : xeabs=3 : yeabs=4
+
+This column specification means that column 
+.I 3
+will be taken as absolute errors on the 
+.I x
+values
+and column
+.I 4
+as the absolute error on the 
+.I y
+values, both of the being symmetric: for 
+.IR y ,
+for instance, you get the value in the column 
+.I 2 
+plus or minus the one in column
+.I 4
+as an error bar.
+
+Quite a few different specifiers are available in place of 
+.I xeabs
+and 
+.IR yeabs .
+For instance, for 
+.I x
+error bars:
+
+.TP
+.I xeabs
+specifies an absolute symmetric error
+
+.TP
+.I xeup
+specifies the absolute error above the 
+.I x 
+values.
+
+.TP
+.I xedown
+the absolute error below the
+.I x
+values.
+
+.TP
+.I xerel
+plays the same role as
+.I xeabs
+but for relative values (expressed in fractions of the corresponding
+value). 
+
+.TP
+.IR xerdown \ and \ xerup
+are the equivalent of 
+.I xeup
+and 
+.I xedown
+for relative values.
+
+
+.TP
+.I xmin
+and
+.I xmax
+directly specify the position of the left and right position of the
+error bar.
+
+.P 
+
+The 
+.I yeabs
+and so on are the pendant of the
+.I xeabs
+for the 
+.I y
+values. Specifications can be abbreviated to the smallest unambiguous
+possibilities. 
+
+.TP 
+.B --[no-]text-split
+
+Starting from version
+.B 1.9\fR,
+at the request of 
+.I Ivars Finvers\fR,
+it is possible to separate a text file into subsets at blank lines, a
+bit like what gnuplot is doing. Subsets can be reached using a syntax
+in the spirit of
+
+.I ctioga --text-split file.dat#12 
+
+that shows the 12th subset of 
+.I file.dat\fR.
+
+
+
+.SS The multitext backend
+
+Select it with the option
+.IR --multitext .
+It recognizes the option 
+.I --multitext-skip
+which is the equivalent of
+.IR --text-skip .
+It exists to provide the ability of plotting columns from different data 
+files and works similarly to the
+.I --text 
+backend with a stricter syntax:
+
+.IB [file1@x_col] : [file2@y_col]
+
+Nothing can be ommited, especially not the square braces. Nevertheless, it can 
+handle arbitrarily complicated mathematical expression such as
+
+.IB [file1@x_col1]-[file2@x_col2] : [file3@y_col1]/[file4@y_col2]
+
+Note that the files should all have the same number of lines and that you 
+should avoid for example division by 0. 
+You will also need to quote the arguments to avoid shell expansion.
+
+The expansion mechanism explained in the 
+.I text
+backend also works, with the exception that the last column has to be specified.
+
+.SS The math backend
+
+Select it with the option
+.IR --math .
+It accepts two options
+
+.TP 10
+.BI --math-xrange \ range
+specifies the range over which to plot, in the form
+.IB xmin : xmax
+
+.TP
+.BI --math-samples \ number
+the number of points used for the computation. They are distributed
+homogeneously in the range.
+
+.TP
+.B --[no-]math-log
+with this option, the samples are spaced logarithmically instead of
+linealy. Good in combination with
+.IR --xlog .
+
+
+.P 
+You can use arbitrary functions of 
+.I x
+with this backend, such as
+.IR sin(x) , \ x**2\ +\ 2*x , \ etc ...
+You will probably need to quote the arguments to prevent shell
+expansion.
+
+
+
+.SS The gnuplot backend
+
+This backend is an attempt to use files that make plots with
+.BR gnuplot . 
+In particular, it can be really useful to write a series of
+functions and fits using gnuplot, profiting from its abilities while
+benefitting from 
+.BR ctioga 's
+better-looking output.
+
+In short, this backend sends the file to
+.B gnuplot
+and intercept its output with the 
+.I table
+terminal.
+You should not have to modify the original file to use with 
+.BR ctioga ,
+but that might fail some times (please file a bug report then).
+
+.B Note :
+this is just a backend, and in its way it will only provide 
+.B ctioga
+with 
+.BR data .
+In particular, 
+.B all formatting options in the gnuplot file are lost 
+!
+
+You select it with the 
+.I --gnuplot
+option.
+
+Options:
+
+.TP 
+.BI --gnuplot-range \ range
+overrides range specification for plots from the file
+
+.TP 
+.BI --gnuplot-vars \ vars
+a colon-separated list of variables that will override the ones from
+the file.
+
+
+
+
+For the examples, we'll use the following 
+.I ctioga.gnuplot 
+file:
+
+.I set term postscript
+.I a = 10
+.I b = 4
+.I plot [2:12] x**2 - a*x + b
+
+It can be found in the 
+.I examples/
+directory in the source tarball. Try this:
+
+
+.I ctioga --gnuplot ctioga.gnuplot
+
+.I ctioga --gnuplot --gnuplot-range -2:2 ctioga.gnuplot
+
+.I ctioga --gnuplot ctioga.gnuplot --gnuplot-vars 'a=11; b=3' ctioga.gnuplot
+
+
+.SH FILTERS
+
+Each backend can have as many filters as you wish. They are applied in
+the order with which they come on the command-line. You can view it as
+a stack where the bottom filters are applied first, and new filters go
+on top. 
+.I Each backend has its own stack.
+
+
+.TP
+.B --filter-pop
+Pops the last filter pushed onto the current backend's stack.
+
+.TP
+.B --filter-clear
+Clears all filters of the current backend.
+
+.TP
+.BI --smooth\  number
+Applies a gaussian-like convolution filter of size 
+.I number
+onto the data. For better results, 
+.I number
+should be odd to have a clear middle for the convolution kernel.
+
+.TP
+.B --sort
+Sorts the X data.
+
+
+.TP
+.BI --trim \ number
+Keeps only one point every 
+.I number
+in the data. Useful to reduce PDF size and displaying time for curves
+with wild oversampling.
+
+.TP
+.B --norm
+Normalizes the input data so that the maximum absolute value is 1. It
+does not change its sign.
+
+.TP
+.B --cumulate
+Sums all points as they are read. Do not mistake this for integration.
+
+.TP
+.B --strip
+Strips all points that are not NaN, mostly useful with 
+.B ctable 
+(1).
+
+.TP
+.B --avgdup
+Averages all Y values of the same X value. Sorts data at the same
+time.
+
+.TP
+.B --stddev
+Averages successive Y values with the same X value, and set error bars
+to reflect standard deviation around the average. Dead useful.
+
+
+.SH AUTHOR
+
+.B ctioga
+was written by Vincent Fourmond with the help of Jean-Julien Fleck.
+.B Tioga
+was written by Bill Paxton.
+
+.SH BUGS
+
+.B ctioga
+is most certainly not bug-free. You can use the facility at 
+.B rubyforge.org
+to report any bug you notice:
+.IR http://rubyforge.org/tracker/?func=add&group_id=1477&atid=5773 .
+You can also use the same facility for feature requests.
+
+.SH "IMPORTANT NOTE"
+
+The development of
+.B ctioga
+as such has ended. Further development is going on on a complete
+rewrite of the engine, called
+.B ctioga2\fR.
+More information can be found at the 
+.B ctioga2
+website:
+.IR http://ctioga2.rubyforge.org .
+
+.SH "SEE ALSO"
+
+.BR xpdf (1),
+.BR pdflatex (1),
+.BR open (1),
+.BR gnuplot (1)
+
+The original tarball includes an 
+.I examples/
+directory where you will find some data files, some commented examples
+of configuration files and most importantly a tutorial along with a
+.I tutorial.sh
+shell script demonstrating the commands used in the tutorial.
+
+It also includes a
+.I tests/
+directory containing test shell scripts. Runnning these shell scripts
+should give you a decent idea of 
+.BR ctioga 's
+possibilities while assuring that it did install properly.
+
+Useful documentation, including an illustrated version of the
+tutorial and instructions on bug reporting, can be found on 
+.BR ctioga 's
+website, at 
+.IR http://sciyag.rubyforge.org/ctioga .
+
+More information about 
+.B Tioga
+and its rdoc documentation 
+can be found at
+.I http://www.kitp.ucsb.edu/~paxton/tioga.html