ctioga 1.11.1

data/ctioga/examples/trig.rb

@@ -0,0 +1,14 @@
+# Small script for generating sine and cosine:
+# use it this way:
+# ruby trig.rb > trig.dat
+
+# To generate the same but with csv data, use the following:
+# ruby trig.rb | sed -r 's/[[:space:]]+/;/g' > trig.csv 
+
+
+include Math                    # can come in useful
+
+100.times do |i|
+  x = (-PI + i * PI / 49.5).to_f
+  puts "#{x}\t#{sin(x)}\t#{cos(x)}\t#{sin(x/2.0)/5}"
+end

data/ctioga/examples/trigh.dat

@@ -0,0 +1,100 @@
+-4.71238898038469	-0.917152335667274	-2.30129890230729
+-4.61718920300318	-0.911962795826179	-2.22281992807806
+-4.52198942562167	-0.906464045442052	-2.14657952077055
+-4.42678964824016	-0.900639694677448	-2.07250089987198
+-4.33158987085865	-0.894472744738396	-2.00050946197059
+-4.23639009347715	-0.887945599708787	-1.93053270562375
+-4.14119031609564	-0.881040084120858	-1.86250015834283
+-4.04599053871413	-0.873737466959347	-1.79634330562156
+-3.95079076133262	-0.866018492832175	-1.73199552193608
+-3.85559098395111	-0.857863421069835	-1.66939200364745
+-3.7603912065696	-0.849252073537055	-1.60846970373893
+-3.66519142918809	-0.840163891951616	-1.5491672683223
+-3.56999165180658	-0.830578005503796	-1.49142497484937
+-3.47479187442507	-0.820473309553165	-1.4351846719663
+-3.37959209704357	-0.809828556144359	-1.38038972095031
+-3.28439231966206	-0.798622457026909	-1.3269849386697
+-3.18919254228055	-0.786833799783009	-1.27491654200981
+-3.09399276489904	-0.774441577558059	-1.22413209370887
+-2.99879298751753	-0.761425132748937	-1.17458044954928
+-2.90359321013602	-0.747764314831341	-1.12621170685104
+-2.80839343275451	-0.73343965229808	-1.07897715421559
+-2.713193655373	-0.718432538433136	-1.03282922246932
+-2.61799387799149	-0.702725430361072	-0.987721436757379
+-2.52279410060999	-0.686302060488436	-0.943608369739589
+-2.42759432322848	-0.669147659095111	-0.900445595841306
+-2.33239454584697	-0.651249186442792	-0.85818964651311
+-2.23719476846546	-0.632595572350614	-0.816797966454314
+-2.14199499108395	-0.613177960752033	-0.776228870756193
+-2.04679521370244	-0.592989956302669	-0.736441502921768
+-1.95159543632093	-0.57202786966815	-0.697395793719876
+-1.85639565893942	-0.550290957698884	-0.659052420832072
+-1.76119588155791	-0.527781654311782	-0.621372769251747
+-1.66599610417641	-0.50450578756561	-0.584318892395562
+-1.5707963267949	-0.480472778156452	-0.54785347388804
+-1.47559654941339	-0.455695814392468	-0.511939789980835
+-1.38039677203188	-0.430191998652027	-0.476541672568824
+-1.28519699465037	-0.403982460404117	-0.441623472765773
+-1.18999721726886	-0.377092431089443	-0.407150025002913
+-1.09479743988735	-0.349551276535727	-0.373086611614244
+-0.999597662505843	-0.321392483117054	-0.339398927872924
+-0.904397885124335	-0.292653594564082	-0.306053047443517
+-0.809198107742826	-0.263376097181849	-0.273015388215317
+-0.713998330361316	-0.233605252219573	-0.240252678482332
+-0.618798552979808	-0.203389875239204	-0.207731923435875
+-0.523598775598299	-0.172782063516364	-0.17542037193601
+-0.42839899821679	-0.141836873741898	-0.143285483528396
+-0.333199220835281	-0.11061195353276	-0.111294895673309
+-0.237999443453773	-0.079167131462267	-0.0794163911538371
+-0.142799666072263	-0.0475639714357357	-0.0476178656304292
+-0.0475998886907538	-0.0158652982233368	-0.0158672953091214
+0.0475998886907547	0.0158652982233371	0.0158672953091217
+0.142799666072263	0.0475639714357357	0.0476178656304292
+0.237999443453772	0.0791671314622667	0.0794163911538368
+0.333199220835281	0.11061195353276	0.111294895673309
+0.42839899821679	0.141836873741898	0.143285483528396
+0.523598775598298	0.172782063516364	0.17542037193601
+0.618798552979808	0.203389875239204	0.207731923435875
+0.713998330361316	0.233605252219573	0.240252678482332
+0.809198107742825	0.263376097181848	0.273015388215317
+0.904397885124335	0.292653594564082	0.306053047443517
+0.999597662505844	0.321392483117054	0.339398927872924
+1.09479743988735	0.349551276535727	0.373086611614244
+1.18999721726886	0.377092431089443	0.407150025002913
+1.28519699465037	0.403982460404117	0.441623472765773
+1.38039677203188	0.430191998652027	0.476541672568824
+1.47559654941339	0.455695814392468	0.511939789980835
+1.5707963267949	0.480472778156452	0.54785347388804
+1.66599610417641	0.50450578756561	0.584318892395562
+1.76119588155791	0.527781654311782	0.621372769251747
+1.85639565893942	0.550290957698884	0.659052420832072
+1.95159543632093	0.57202786966815	0.697395793719876
+2.04679521370244	0.592989956302669	0.736441502921768
+2.14199499108395	0.613177960752033	0.776228870756192
+2.23719476846546	0.632595572350614	0.816797966454314
+2.33239454584697	0.651249186442792	0.85818964651311
+2.42759432322848	0.669147659095111	0.900445595841306
+2.52279410060998	0.686302060488436	0.943608369739588
+2.61799387799149	0.702725430361072	0.98772143675738
+2.713193655373	0.718432538433136	1.03282922246933
+2.80839343275451	0.73343965229808	1.07897715421559
+2.90359321013602	0.74776431483134	1.12621170685104
+2.99879298751753	0.761425132748937	1.17458044954928
+3.09399276489904	0.774441577558059	1.22413209370887
+3.18919254228055	0.786833799783009	1.27491654200981
+3.28439231966206	0.798622457026909	1.3269849386697
+3.37959209704356	0.809828556144359	1.38038972095031
+3.47479187442507	0.820473309553165	1.4351846719663
+3.56999165180658	0.830578005503796	1.49142497484937
+3.66519142918809	0.840163891951616	1.5491672683223
+3.7603912065696	0.849252073537055	1.60846970373893
+3.85559098395111	0.857863421069835	1.66939200364745
+3.95079076133262	0.866018492832175	1.73199552193608
+4.04599053871413	0.873737466959347	1.79634330562156
+4.14119031609564	0.881040084120858	1.86250015834283
+4.23639009347714	0.887945599708787	1.93053270562375
+4.33158987085865	0.894472744738396	2.00050946197059
+4.42678964824016	0.900639694677448	2.07250089987198
+4.52198942562167	0.906464045442052	2.14657952077055
+4.61718920300318	0.911962795826179	2.22281992807806
+4.71238898038469	0.917152335667274	2.30129890230729

data/ctioga/examples/trigh.rb

@@ -0,0 +1,10 @@
+# Small script for generating sine and cosine:
+# use it this way:
+# ruby trig.rb > trig.dat
+
+include Math                    # can come in useful
+
+100.times do |i|
+  x = (-1.5 * PI + i * 1.5 * PI / 49.5).to_f
+  puts "#{x}\t#{tanh(x/3)}\t#{sinh(x/3)}"
+end

data/ctioga/examples/tutorial

@@ -0,0 +1,763 @@
+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 !