How to read this tutorial
=========================

This tutorial is willingly overdocumented so that each and everyone of you 
could find whatever explanation they are looking for:

* if you just want to see what are the main features fo Ctioga, read through 
and don't hesitate to copy/paste the example lines (don't forget to add 
--xpdf, --open or --viewer YourFavoritePDFViewer to effectively look at the 
produced graph) to get an idea;

* for those who are always in a hurry, the file tutorial.sh can be executed 
to look at the results of all the examples in a row;

* if you are here because you don't understand one option or set of options, 
just grep on it and you should find your way.


Here are the avalaible sections:

* Plotting math functions: where you will learn how to do some mathematics;
* Plotting simple data files: where you will play with data;
* Ruby Power: where you can use some very nice rubisms;
* Using presentation options: where you will learn how to customize your plot;
* Drawings: where you will know how to add some graphic materials;
* More words about backends: where other backends are described;
* Housekeeping and various options: where your won't forget your housekeeping 
duties.

Have fun !


JJ Fleck 09/2006


Plotting math functions
=======================

Ctioga knows basic math function from which a lot can already be done.
Let's plot an exponential:

prompt> ctioga --math 'exp(x)'

Note that the variable in the function is always implicitly "x"

By the way, let's not forget to add some title via the --title (or -t) command

prompt> ctioga --math 'exp(x)' --title 'My exponential'

By default Ctioga assumes that the x-range is -10:10 and stretches the y-axes
so that the function is completely in the plot. A more "usual" way of looking 
at exponentials could be

prompt> ctioga --math-xrange -5:1 --math 'exp(x)' -t 'My exponential'

Note that you have to use --math-xrange to get this behavior, the --xrange 
option will only modify the plotting range but not the computing range, which 
could lead to sampling problems. Compare

prompt> ctioga --xrange -1:1 --math 'sin(10 * x)' \
               -t 'badly sampled sine'

and

prompt> ctioga --math-xrange -1:1 --math 'sin(10 * x)' \
               -t 'well sampled sine'

From time to time, it can be very useful to define a function piece by piece:

prompt> ctioga --xrange -3:3 --math-xrange -2:0 --math 'x+1'    \
                             --math-xrange 0:2         'exp(x)' \
                             -t 'Strange exponential'

Adding the --yrange option can be used to isolated a piece of graph

prompt> ctioga --yrange -2:8 --xrange -3:3         \
               --math-xrange -2:0 --math 'x+1'     \
               --math-xrange  0:2        'exp(x)'  \
               -t 'Strange exponential' 

Ctioga also knows about parametric functions, whenever you use the variable t,

prompt> ctioga --math --math-trange -3.1415:3.1415 \
               'sin(2*t):cos(3*t)'                 \
               -t 'parametric curve'

Note that you can use --math-trange to specifies the range over which to 
compute the curve. As for --math-xrange, default is -10:10.


--include options allows you to define some functions so that ctioga could use 
them. Look to file include_1.rb for an example of syntax. In this file is 
defined the function pol(x) = (1.0 - x) * (1.0 + x) that we can use:

prompt> ctioga --include include_1.rb --math 'pol(x)' -t 'Polynomial function'



Plotting simple data files
==========================

Ctioga has been primarily intended to rapidly plot data files from the command 
line. It's syntax is not far from the one used by gnuplot.

The simplest command (assuming you are in directory examples/ with datafile 
trig.dat) is

prompt> ctioga trig.dat -t 'data sine'

which plot column 2 with respect to column 1 and automaticaly set the width 
and height of the plot, give the legend with respect to the filename

If you append an other file name (for example trigh.dat for some hyperbolic 
trigonometry):

prompt> ctioga trig.dat trigh.dat -t 'data sine and hyperbolic tangente'

it will plot the two dataset on the same plot (with different colors and 
legends) and adapt automatically the extension to the biggest x and y used so 
that both dataset are completely visible on the graph

Let's see how to change the columns we would like to use.

To plot the third column rather than the second one, you use

prompt> ctioga trig.dat@1:3 -t 'data cosine'

Or to plot a circle with parametric representation

prompt> ctioga trig.dat@2:3 -t 'Circle'


Note that if there is no filename before the "@", the previous file is used 
instead:

prompt> ctioga trig.dat @1:3 @2:3 -t 'Some trigonometry'

plots the sine (which is implicitly @1:2), the cosine (@1:3) and the circle 
(@2:3)

If you add the other file, depending on where you put it, the results will 
change.

Compare

prompt> ctioga trig.dat trigh.dat @1:3 @2:3 -t 'Mixing 1'

prompt> ctioga trig.dat @1:3 trigh.dat @2:3 -t 'Mixing 2'

prompt> ctioga trig.dat @1:3 @2:3 trigh.dat -t 'Mixing 3'

To put some legends, use the --legend (or -l) option. Don't forget to protect
your legend with simple quotes as in 'my legend' whenever it contains spaces
or things that could be interpreted by your shell. Bear also in mind that it 
will finally get passed to LaTeX, so use "^" and "_" with caution.

prompt> ctioga --legend sine trig.dat     \
               -l cosine @1:3             \
               -l 'beautiful circle' @2:3 \
               -t 'Some trigonometry'

You can also use LaTeX coding in your legends

prompt> ctioga -l '$\sin(x)$' trig.dat                          \
               -l '$\cos(x)$' @1:3                              \
               -l '$r = \sqrt{\cos^2(x) + \sin^2(x)} = 1$' @2:3 \
               -t 'Some trigonometry'

Data files and expansion
------------------------

Ctioga has a feature for automatic data set expansion. When you're interested
to plot several columns of one file as a function of only one column, it is
interesting to use the 2##4 syntax. file.dat@2##4 is exactly equivalent to
file.dat@1:2 file.dat@1:3 file.dat@1:4. This can reduce quite a bit the
tediousness that can come sometimes...

prompt> ctioga -t 'Use of expansion' trig.dat@1:2##3

Starting from ctioga 1.3, you can use tis mechanism as well for nearly
any backend, including the --math one:

prompt> ctioga -t 'Math and expansion' --math 'sin(x + 1##4)'

Filters
-------

Ctioga also have some filters you can apply to your data.

From time to time, data are not computed in the way we would like to. For 
example

prompt> ctioga -t 'Unsorted' noise.dat

That's why Ctioga comes with the --sort filter

prompt> ctioga -t 'Sorted' --sort noise.dat

That's better. But it is quite hard to recognize the cosine underneath the 
noise. Let's apply some smoothing

prompt> ctioga -t 'Smoothing' --sort --smooth 3 noise.dat

Well, it cannot be perfect, can it ? Let's compare the difference

prompt> ctioga -t 'Comparison' --sort -l 'Noise' noise.dat \
                               --smooth 3 -l 'Smoothing' noise.dat

Once set, a filter is applied to all the remaining plots. To remove the last 
filter applied, use --filter-pop. To remove all of them, use --filter-clear. 
Do not forget the order of application, for example you would better always 
apply --sort first if necessary

prompt> ctioga -t 'Sorting second'                             \
               -l 'Sorting second' --smooth 3 --sort noise.dat \
               --filter-clear                                  \
               -l 'Sorting first'  --sort --smooth 3 noise.dat

Histograms
----------

Ctioga allows you to plot data (or math functions) in the form of histograms 
with the --histogram switch

prompt> ctioga -t 'Cumulative distribution'                         \
               --math --math-xrange 0:40 --yrange 1:4.5 --ylog      \
               -l 'data'                                            \
               --histogram    --math-sample 21  'x**3-30*x**2+4100' \
               -l 'fit'                                             \
               --no-histogram --math-sample 200 'x**3-30*x**2+4100' 

Error bars
----------

Soon to come, some possibility to add error bars for observers.


Ruby Power
==========

As Ctioga is written in Ruby and is internally letting Ruby take care of most 
of the computations, you can use your knowledge in Ruby to improve your plots.
Let's suppose for example that you are only interested in the function 
gathering the maximum value of two of your data columns. You can use the .max 
method implemented for all 'Enumerable' you find in Ruby, for example Arrays:

prompt> ctioga -t 'Everybody likes to go there' \
               -l 'Max value'                    \
               trig.dat@'$1:[$2,$3].max'
               
Sure enough, you can also use the .min method.


What if you would like to put some conditions on plotted points ? You just 
have to use some 'if' statements

prompt> ctioga -t 'First and third quarter' \
               -l 'Conditionnal drawing'    \
               trig.dat@'$2:(if $3*$2 > 0 ; $3 else 0.0/0.0 ; end)'

Note the use of 0.0/0.0 to get a NaN which will not be drawn.

If you are curious of the Dvectors defined by Tioga and extensively used by 
Ctioga, you can also use some of their power to speed up computation or simply 
writing. For example to sum the squared roots of 3 curves

prompt> ctioga -t 'Square root summation'   \
               -N trig.dat@'$1:sqrt($2##4)' \
               -l 'Sum using Dvectors'      \
               trig.dat@'$1:Dvector[$2,$3,$4].safe_sqrt.sum'
               
You can find many more Dvector's shortcuts on the dedicated web page, looking 
for "Dobjects:Dvector" in the central frame:

http://theory.kitp.ucsb.edu/~paxton/tioga_doc/

Using presentation options
==========================

Let's go towards more aesthetic considerations. 

Depending on what you plot, external presentation will differ. We have already
seen how to add title (introduced by --title or -t) and legends (introduced by
-l or --legend) to the plot. Note that --title is a global setting. As there
is only one title for the entire plot, it can be specified wherever you want
whereas the legend acts on a given dataset or function and has to be specified
just before the curve on which it will apply. This consideration holds true
for most of the options we will present in this section as they generally
apply to a given curve.

Particular options
------------------

Red is not your favorite color ? You have a lot more choice.. You just have to 
introduce the --color or -c options before the plot you would like to colorize

prompt> ctioga --color Violet trig.dat \
               -c Blue @1:3            \
               -c Turquoise @2:3       \
               -c PowderBlue trigh.dat \
               -t 'Blue tones'

The complete set of available colors can be found in the Tioga documentation 
at 

http://theory.kitp.ucsb.edu/~paxton/tioga_doc/classes/Tioga/ColorConstants.html

Background color could also be specified using the --background option to make 
plots less crude

prompt> ctioga --background Ivory trig.dat -l 'Ivory background'

Well, colors are a great thing but for use on a B&W printer, you would 
certainly prefer some black color and different linestyle: 
use the --mono switch

prompt> ctioga --mono trig.dat @1:3 @2:3 -t 'Black trigonometry'

But what if the Ctioga's default for linestyle are not the one you would 
expect ? Just change them:

prompt> ctioga --line-style Line_Type_Dot trig.dat       \
               --line-style Line_Type_Dash @2:3          \
               --line-style Line_Type_Dot_Long_Dash @1:3 \
               -t 'Some line types'

Once again, line types are derived from those of tioga. You can find the 
complete set and an explication how to define it yourself at

http://theory.kitp.ucsb.edu/~paxton/tioga_doc/classes/Tioga/Strokes.html

Note that line-style is a switch. Every coming curve will have the 
last-defined line-type, even if you switch to --mono

One curve could be more important than an other, a way of underlining it is to 
play on line-width.

prompt> ctioga --line-width 0.5 trig.dat @1:3 \
               --line-width 2 @2:3            \
               -t 'See the circle ?'

Just as --line-style, it has an influence over all coming curves until an 
other --line-width is issued.

What about plotting real data and trying to fit some model on it. Well Ctioga 
has no fitting routine as it only concerns plotting (but who knows,
one day..?). Nevertheless, you can use your favorite tool to find the fitting 
parameters and Ctioga to plot the result:

prompt> ctioga -l 'model' --math --xrange -4:4 'sin(x)'                \
               -l 'data'  --text --marker Plus --line-width 0 trig.dat \
               -t 'comparison data/model'

Note that you switch back from math mode to data-reading mode with the switch
--text (because datas are in a text file). Once again, the list of available
markers (including Cross, Diamond, Semicircle but also Arrow, Hand or Check)
is available here:

http://theory.kitp.ucsb.edu/~paxton/tioga_doc/classes/Tioga/MarkerConstants.html

If you like, you can also have the markers of a different color than the 
underlying curve:

prompt> ctioga --marker Plus --marker-color Blue trig.dat \
               -t 'Bicolored graph'

Global options
--------------

Together with --title, there is two other global settings, namely --xlabel
(or-x) to specify the label of the x axis and --ylabel (or -y) for the y one.
You can call them wherever you want. For example, a plot of x = cos(t) could
be written as

prompt> ctioga -l '$x = \cos(t)$' --math 'cos(x)' -x '$t$' -y '$x$' \
               -t 'Evolution of position $x$ in time'

By default, Ctioga produces squared plots, which is useful for inclusion in 
2 columns papers but not that good-looking for oral presentation. To correct 
this, you have the switch --golden-ratio to set the ratio of  height to length
to the well known (1 + sqrt(5))/2:

prompt> ctioga trig.dat @1:3 @2:3 -t 'Gold trigonometry' --golden-ratio

Or you can define this ratio yourself

prompt> ctioga trig.dat @1:3 @2:3             \
               -t 'Silver trigonometry'       \
               --aspect-ratio 2

prompt> ctioga trig.dat @1:3 @2:3             \
               -t 'Bronze trigonometry'       \
               --aspect-ratio 0.5

Options --xrange and --yrange that we met at the beginning of this tutorial 
come with the option --margin which gives an extra space (0.1 represents 10%) 
around the curve so that it does not touch the borders

prompt> ctioga trig.dat --margin 0.1          \
               -t '10\% air on both sides'

If you want only air around the vertical side, use in conjonction with 
--xrange

prompt> ctioga trig.dat --margin 0.1 --xrange -3.14:3.14 \
               -t '10\% air on vertical side'

Ctioga automaticaly choose some set of colors if none is defined on the line. 
You can change it if it does not fit your requirement. Currently available
sets are "default" and "colorblind"

prompt> ctioga trig.dat @1:3 @2:3 trigh.dat @1:3 @2:3 \
               -t 'default color-set'

prompt> ctioga --color-set colorblind                 \
               trig.dat @1:3 @2:3 trigh.dat @1:3 @2:3 \
               -t 'colorblind color-set'

You can also use the "gradient" feature, for example going from Blue to Red in 
6 steps

prompt> ctioga --color-set gradient:Blue--Red,6       \
               trig.dat @1:3 @2:3 trigh.dat @1:3 @2:3 \
               -t 'Gradient feature with 6 steps'

With less steps, the colors repeat itself

prompt> ctioga --color-set gradient:Blue--Red,3       \
               trig.dat @1:3 @2:3 trigh.dat @1:3 @2:3 \
               -t 'Gradient feature with 3 steps'

The same is true for markers and line-types but for the moment, only the 
"default" is available. If you have ideas of sets, just email them to us and 
we will be happy to add them.

prompt> ctioga -m --marker-set default trig.dat @1:3 @2:3  \
               -t 'Using Markers'

prompt> ctioga --mono --line-style-set standard trig.dat @1:3 @2:3  \
               -t 'Using line-styles (which is already the default...)'

Finally, you can also have a different set of colors for you markers

prompt> ctioga -m --marker-set default        \
               --marker-color-set colorblind  \
               trig.dat @1:3 @2:3             \
               -t 'Using Markers'

Axis manipulation
-----------------

Logarithmic axes can be specified *at the beginning of the plot* with options 
--xlog and --ylog. In this case, an exponential looks like a mere right line

prompt> ctioga --ylog --math 'exp(x)' -t 'Some straight line'

prompt> ctioga --xlog --ylog --math-xrange 0.001:1000 \
               --math '1/x**2' '1/x**3' -t 'Power laws'

One astrophysical example of such a use is the stellar Initial Mass Function 
(IMF) which is known to be a power law by pieces

prompt> ctioga --xlog --ylog --math                                       \
               --math-xrange 0.1:1  -l 'Low masses' '1/x**1.3'            \
               --math-xrange 1:10   -l 'Intermediate masses' '1/x**2.35'  \
               --math-xrange 10:100 -l 'High masses' '1/x**4*10**1.65'    \
               -x '$\log_{10}(M/M_\odot)$' -y '$\log_{10}(dN/dM)$'        \
               -t 'Kroupa IMF' --golden-ratio

There is one detail you have to be careful at: the corresponding range has to 
be given in logscale also. For example, if you want to plot the previous 
figure between 0.01 and 1000, you have to specify --xrange -2:3 rather than 
--xrange 0.01:1000

prompt> ctioga --xlog --ylog --xrange -2:3 --math                         \
               --math-xrange 0.1:1  -l 'Low masses' '1/x**1.3'            \
               --math-xrange 1:10   -l 'Intermediate masses' '1/x**2.35'  \
               --math-xrange 10:100 -l 'High masses' '1/x**4*10**1.65'    \
               -x '$\log_{10}(M/M_\odot)$' -y '$\log_{10}(dN/dM)$'        \
               -t 'Kroupa IMF' --golden-ratio


From time to time, it can also be useful to stretch or shrink axes by a given 
factor, for example in a fitting purpose or to compare two set of data that do 
note have the scale. Use --xfact and --yfact. Compare

prompt> ctioga trig.dat @1:4 -t 'Scaling problem'

prompt> ctioga trig.dat --xfact 0.5 --yfact 5 @1:4 -t 'Scaling resolved'

Drawings
========

From time to time, you will certainly need to add text, arrows or markers at 
some points in you plot. Let's consider the physical case of the discharge of 
a capacity C in a resistor R so that RC=2. Normally, it's simply an 
exponential decay

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange 0:9 \
               -x '$t$' -y '$U_C$'                               \
               'exp(-x/2)' --yrange 0:1

Arrow
-----

Cool.. But well, it's a bit cheap, isn't it ? Let's add some graphical 
information. For example, after 3RC, the discharge is complete at 95% and so 
let's draw an arrow to highlight this position

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange 0:9 \
               -x '$t$' -y '$U_C$'                               \
               'exp(-x/2)' --yrange 0:1                          \
               --draw "arrow: 6,0.2 6,0.07"

To do this, we used the --draw switch followed by the keyword "arrow" and the 
indication of its origin (6,0.2) and target (6,0.07). The head and tail of the 
arrow are usually too big, so we will use options in the form "option=value" 
to get it right

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange 0:9 \
               -x '$t$' -y '$U_C$'                               \
               'exp(-x/2)' --yrange 0:1                          \
               --draw "arrow: 6,0.2 6,0.07 tail_scale=0.1 head_scale=0.5" 

Other valid options are 

 * "tail_marker" and "head_marker" to change the default markers used. The 
 given value should be a valid Tioga Marker ;
 * "line_style" which value should be a valid Tioga Line_Type as given on page 
 
http://theory.kitp.ucsb.edu/~paxton/tioga_doc/classes/Tioga/Strokes.html
 
 * "line_width" which specify the width of the arrow line ;
 * and finally "color" to change the color of the arrow.

Text
----

Well, we stil have to say why we draw this arrow. Let's use the keyword "text" 
to do that for which you have to give the application point and the text to 
add

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange 0:9 \
               -x '$t$' -y '$U_C$'                               \
               'exp(-x/2)' --yrange 0:1                          \
               --draw "arrow: 6,0.2 6,0.07 tail_scale=0.1 head_scale=0.5" \
               --draw "text: 6,0.22 '\$95\\%\$ decay'"

Note that due to multiple evaluation, you have to specify escape caracters for 
"$" and "\" so that LaTeX really see $95\%$.

Tangent
-------

If you would like to add an arrow on a curve, the "tangent" keyword will do 
it. It is basically an arrow and so share the same options. But the position 
indication is the fraction of the data vector to place it. For example, if you 
have 200 data points, specifiing 0.35 will put the tangent where the 70th 
data point is located. This has to be done that way because a curve can go 
back and forth and only the position into the data structure can help to 
define uniquely where the tangent should apply. Here we will indicate the 
direction of decay in the middle of the graph

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange 0:9 \
               -x '$t$' -y '$U_C$'                               \
               'exp(-x/2)' --yrange 0:1                          \
               --draw "arrow: 6,0.2 6,0.07 tail_scale=0.1 head_scale=0.5" \
               --draw "text: 6,0.22 '\$95\\%\$ decay'"           \
               --draw "tangent: 0.5 head_scale=0.7"


What is interesting to discover in our physical problem is the value of RC 
which is given by the intersection of the tangent at the origin with the x 
axis. We can then use the option xextent or yextent. But now, to be able to 
compute properly the tangent at the origin, we have to extent the definition 
domain of our exponential, for example from -1 to get a simple position of the 
"0" value at 0.1=(0-(-1))/(9-(-1))

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange -1:9 \
               -x '$t$' -y '$U_C$'                                \
               'exp(-x/2)' --yrange 0:1 --xrange 0:9              \
               --draw "arrow: 6,0.2 6,0.07 tail_scale=0.1 head_scale=0.5" \
               --draw "text: 6,0.22 '\$95\\%\$ decay'"            \
               --draw "tangent: 0.5 head_scale=0.7"               \
               --draw "tangent: 0.1 head_scale=0.1 xextent=2 color=Black" 


We could also have used the "yextent" option, but there we have to go towards 
the negative values

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange -1:9 \
               -x '$t$' -y '$U_C$'                                \
               'exp(-x/2)' --yrange 0:1 --xrange 0:9              \
               --draw "arrow: 6,0.2 6,0.07 tail_scale=0.1 head_scale=0.5" \
               --draw "text: 6,0.22 '\$95\\%\$ decay'"            \
               --draw "tangent: 0.5 head_scale=0.7"               \
               --draw "tangent: 0.1 head_scale=0.1 yextent=-1 color=Black" 

Marker
------

Finally, let's add some text on this tangent using the respective options

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange -1:9 \
               -x '$t$' -y '$U_C$'                                \
               'exp(-x/2)' --yrange 0:1 --xrange 0:9              \
               --draw "arrow: 6,0.2 6,0.07 tail_scale=0.1 head_scale=0.5"  \
               --draw "text: 6,0.22 '\$95\\%\$ decay'"            \
               --draw "tangent: 0.5 head_scale=0.7"               \
               --draw "tangent: 0.1 head_scale=0.1 yextent=-1 color=Black" \
               --draw "text: 1.9,0.15 '\$\\tau=RC\$'              \
               angle=-77 scale=2 color=Blue"

and a funny marker using the "marker" keyword

prompt> ctioga -t 'RC circuit decay' -N --math --math-xrange -1:9 \
               -x '$t$' -y '$U_C$'                                \
               'exp(-x/2)' --yrange 0:1 --xrange 0:9              \
               --draw "arrow: 6,0.2 6,0.07 tail_scale=0.1 head_scale=0.5"  \
               --draw "text: 6,0.22 '\$95\\%\$ decay'"            \
               --draw "tangent: 0.5 head_scale=0.7"               \
               --draw "tangent: 0.1 head_scale=0.1 yextent=-1 color=Black" \
               --draw "text: 1.9,0.15 '\$\\tau=RC\$'              \
               angle=-77 scale=2 color=Blue"                      \
               --draw "marker: 1.5,0.05 OtherHand                 \
               angle=-45 scale=2 color=Blue"

A reminder of all the options and drawing abilities can be found using the 
--draw-help option on the command line.


More words about backends
=========================

In the first two paragraphs, we have talked much about --math and --text 
modes. We believe that these two modes (these two backends as we will call 
them from now on) will be the two more useful ones. But if you ever feel 
limited by them, you can just write your own and experience the power of ruby. 
Vince for example wrote two backends (--mdb and --mdbcv) that you would 
probably never use because they are especially made for his experiments 
results. Nevertheless, you can take example on them to fit your special needs 
by for example automaticaly retrieving informations in the headers. 

Multitext Backend
-----------------

My own codes are producing a lot of outputs that I have to split into several
files to ease their use. Nevertheless, I would like from time to time to plot 
one column of one file as a function of a column in another file or even make 
some mathematical manipulations of columns that don't live in the same files.
So I wrote the multitext backend to do so. The syntax is a bit rigid for now, 
but it could come useful one day. Basically, you can write things as

prompt> ctioga --multitext '[trig.dat@2]:[trigh.dat@2]' \
               -t "two files in one plot"

The syntax is necessarily of the type [filename@column_number] within square 
brackets. Sure enough, the files have to have the same number of lines and be 
somehow related (but this becomes your problem now :o). Any mathematical 
expression is then possible

prompt> ctioga --multitext '[trig.dat@2]:[trigh.dat@2] + [trig.dat@3]'   \
               -t "Some computation on different files"

prompt> ctioga --multitext '[trig.dat@2]**2:[trigh.dat@2] * [trig.dat@3]'\
               -t "Some more computation on different files"

CSV files
---------

Starting from ctioga 1.3, it is now possible to specify arbitrary column
separators for the --text backend. This makes it possible to now parse
CSV (comma-separated values) files, such as the trig.csv file included
in the archive:

prompt> ctioga --text-separator ';' trig.csv -t "CSV trigonometry"

Housekeeping and various options
================================

The coming options do not directly apply to the plot, but more to the material 
living of the plots, how to view it, how to share it with others, how to 
include it in a TeX file and so on. So there will be no more example, just a 
description of what the option does effectively:

Shell Variable
--------------

Ctioga naturally look into the content of the shell variable CTIOGA that you 
can define in your prefferred shell starting file. For example, the script 
tutorial.sh begins with

prompt> CTIOGA="--xpdf --clean-all --display-commandline" \
		export CTIOGA

and thus every ctioga call will be prepended by this set of commands. A wise 
idea is to set it to "--xpdf" as this options will be the most commonly 
forgotten.

Viewing
-------

You can choose to view the resulting pdf file with the viewer you cherish with 
the --viewer option. For example

prompt> ctioga --viewer gv trig.dat

--xpdf and --open are short cuts to using xpdf or open (for MacOSX users, 
which has the same effect as double clicking on the selected file) as viewers.

--no-viewer avoid a viewer to be opened even if you CTIOGA variable is set to 
--xpdf

Cleaning
--------

Ctioga produce a lot af auxilliary files in order to produce the final pdf 
version of your plot. Most of the time, you will only need the pdf file so 
that option --cleanup will erase every other files that have been created. 

Nevertheless, when you will need to include your file within a TeX document so 
that the font used within the plot are exactly those of your document, you 
will rather use --tex-cleanup and see what remains.

If your are a cleaning maniac and want just to have a look at your datas or a 
given mathematical function, use --clean-all. Don't forget to use it together 
with a viewing option, --xpdf for example.

Naming
------

If you want to keep the files but store them elsewhere, use the --save-dir 
option to specify the destination directory which will be created if 
necessary. That could be an option you would like to set with the CTIOGA shell 
variable.

In that case (and other), you will want to differenciate the produced files 
from one another by giving sensible names using -n or --name option as a 
prefix for all generated files from tioga (default prefix is "Plot"). Note 
that you would better avoid prefix containing extension name, you don't want 
to have a plot named my_data.txt.pdf, do you ? Anyway, internal processing 
will failed, especially when going through LaTeX.

Misc
----

--display-commandline display the command line you have been using to produced 
the plot on the plot itself. It can be good to demonstrate simple plots but 
won't be that useful if line is too long.

--mark is more efficient to remember which command has been used to produce a 
plot. It fills the 'creator' field of the produced PDF file with the 
command line. You can then look at it with the pdfinfo command. It is disabled 
by default because the result has to be given to LaTeX which could complain. 
However it does not restrain the plot to be generated so that it could be an 
option to add to the CTIOGA shell variable. --no-mark option will disable it 
if it is already set.

--debug and --debug-patterns are debugging tools. If you are using it, well 
I'm sure your name is Vince !

I hope you enjoyed this tutorial and are now ready to make full use of the 
power of Ctioga, Tioga, Ruby and Cie !