\documentclass[a4paper]{article}
%%
\usepackage[T1]{fontenc}
%% \usepackage{html}
%%
%% TO obtain an HTML version of GraceGTK documentation:
%% Uncomment the  \usepackage{tex4ht} line below
%% run 'ht latex GraceGTK.tex'
%% \usepackage{tex4ht}
\usepackage[english]{babel}
\usepackage{epsfig}
\usepackage{url}
\urldef{\aaaurl} \url{http://www.semibyte.de/dokuwiki/informatik:linux:xmgrace:grace_benutzerhandbuch}
\urldef{\aaburl} \url{http://plasma-gate.weizmann.ac.il/Grace/}
\urldef{\aacurl} \url{ftp://ftp.uu.net/graphics/jpeg/}
\urldef{\aadurl} \url{http://www.libpng.org/pub/png/libpng.html}
\urldef{\aaeurl} \url{http://www.pdflib.com/}
\urldef{\aafurl} \url{http://www.fftw.org}
\urldef{\aagurl} \url{http://unidata.ucar.edu/packages/netcdf/index.html}
\urldef{\aahurl} \url{Tutorial.html}
\urldef{\aaiurl} \url{FAQ.html}
\urldef{\aaaurl} \url{http://www.gtk.org}
\urldef{\aahome} \url{http://gracegtk.sourceforge.net}
%%
\usepackage{makeidx}
%%
\usepackage{ifpdf}
\ifpdf\pdfcompresslevel=9\fi
%%
\usepackage{array}
\newcolumntype{T}{>{\ttfamily}l}
\newcolumntype{P}[1]{>{\ttfamily}p{#1}}
\showcols
\usepackage[colorlinks=true,urlcolor=blue,linkcolor=blue]{hyperref}
%%
%% In a MS Windows environment, the times font give a better
%%  PDF rendering and you can uncomment the line below
%% Don't forget to rerun latex, latex, index, latex
%% to get summary and index up-to-date.
%% \usepackage{times}
%%
\newcommand{\grace}{\texttt{grace-5.1.22 }}
\newcommand{\ggtk}{\texttt{GraceGTK} }
\newcommand{\gsix}{\texttt{grace-5.99} }
\newcommand{\linuxonly}{\textit{ (Unix/Linux only)}}
\newcommand{\fftw}{\texttt{FFTW }}
%% To describe the command interpreter
\newcommand{\expr}{\textit{expr}}
\newcommand{\iexpr}{\textit{iexpr}}
\newcommand{\nexpr}{\textit{nexpr}}
\newcommand{\sexpr}{\textit{sexpr}}
\newcommand{\vexpr}{\textit{vexpr}}
\newcommand{\mexpr}{\textit{mexpr}}
\newcommand{\indx}{\textit{indx}}
\newcommand{\pvr}[1]{\hfill\textrm{#1}}
%% To write column vertically without "rotating" package 
%% that don't work in DVI
\newcommand{\Vcol}[1]{\parbox{2mm}{\vspace{1mm}\texttt{#1\vspace{1mm}}}}

%%
\bibliographystyle{plain}
%%
\DeclareMathSizes{10}{10}{8}{7}
\textwidth 16cm          % Width of text line.
\textheight 24cm         % Height of text (including footnotes and figures,
                         %    excluding running head and foot).
\oddsidemargin   -5mm    % Left margin on odd-numbered pages.
\evensidemargin  -5mm    % Left margin on even-numbered pages.rer dans une page A4
%%
\makeindex
%%

\setcounter{page}{1}
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\title{GraceGTK guide}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
\author{Software version: \texttt{gracegtk-0.4.4}}
%% \date{23.12.2010}
\begin{document}
%%
\maketitle
\abstract{This document explains the usage of \ggtk
a 2D plotting tool for numerical data.}
\tableofcontents
\listoftables
\clearpage
\noindent
\textbf{Note that most of this document is borrowed to the
Grace User Guide} (\grace).
\section{Introduction}
The name \textit{Grace} is used  when the text is valid  for \grace
as well as for \ggtk and \ggtk when relevant only for this later.
\subsection{What is GraceGTK? }
%%
Grace and \ggtk are WYSIWYG tools to make two-dimensional plots of numerical
data.\\
\ggtk is an evolution of \grace using the GTK Application
Programming Interface  (API) instead of Motif API.
%%1 You must have a look to Grace documentation before reading this.
Its goal is to gives a tool that makes easy to grab numerical data,
perform some post-processing (Fourier transform, filtering,
\textit{etc}) and obtain a drawing able to make a good figure in an
article.

\ggtk is derived from \grace, developed under GPL copyright by a
team of volunteers under the coordination of Evgeny Stambulchik.
You can get the newest information about Grace and download the
latest version\footnote{Of course \gsix is newer than \grace,
  but had never gain the status of \texttt{grace-6} and remains with a
  development status.
  The differences between these two codes are important.}
 at the
\emph{Grace home page} \texttt{\aaburl}


Grace itself is derived from Xmgr (a.k.a. ACE/gr), originally written by
Paul Turner.
Paul still maintains and develops a non-public version of Xmgr for
internal use.

\ggtk home is \aahome

The natural operating system for GTK programs is Unix/Linux, but
the use of GTK allows to build a standalone distribution for MS
Windows.


\subsection{Copyright statement }
For Grace:
%% \begin{tscreen}
\begin{verbatim}
Copyright ((C)) 1991-1995 Paul J Turner, Portland, OR
Copyright ((C)) 1996-2007 Grace Development Team
Maintained by Evgeny Stambulchik
 For GraceGTK:
Copyright ((C)) 2009-2010 Patrick Vincent and the Grace Development Team


                         All Rights Reserved

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
\end{verbatim}
%% \end{tscreen}
For some libraries required to build \ggtk
(which are therefore even included in a suitable version)
there may be different Copyright/License statements. Though their
License may by chance match the one used for Grace,
the Grace Copyright holders can not influence or change them.\\
N.B. The status of Cephes seems not clear an this library is  used
by \grace, but not by \gsix .
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{Tl}            \hline
      Package        &  License \\ \hline
      cephes         &  ?    \\
      T1lib          &  LGPL    \\
      GTK+           &  GPL     \\
      libundo        &  GPL     \\ \hline
    \end{tabular}
  \end{center}
  \caption{Licenses}
\end{table}
%% ............................
\section{Installation guide}
%% ............................
\subsection{Installing from sources}
\label{configuration}
%%
\begin{description}
\item  [Requirements.]\index{Requirements}
  \index{C}~\\
  You need an ANSI C compiler (\texttt{gcc} is just fine),
  and  a development version of GTK
  (\verb=GTK+-2.12= or above\footnote{
    It should work also with \texttt{GTK+-2.10}, but without the
  tooltips.}.
  GTK can be found at {\em } {\tt \aaaurl}.\\
  Contour level curves need a FORTRAN compiler: \texttt{gfortran} is
  just fine. \\
  The FORTRAN compiler is detected by \texttt{configure} through the
  environment variable \texttt{FC},
  e.g. if \texttt{gfortran} is the name of the compiler command:\\
    \verb+ export FC=gfortran+
    \\
  If you want to compile your own changes to some parts of
  \ggtk, you will need  \texttt{bison} (the parser generator)
  and the GNU \texttt{autotools}.

\item  [Output drivers and extra libraries.]\index{Extra libraries}
\index{Cairo}\index{Drivers}
  \hypertarget{extra-lib}{}~\\
  Since version 0.3.3, \ggtk have output drivers based on the Cairo
  library. Cairo is integrated in the GTK distribution, thus no extra
  libraries are needed to use these drivers.
  Currently, PDF, PNG and SVG Cairo drivers are included 
  and are necessary
  to render correctly color mapped sets (\texttt{xycmap} sets),
  but these drivers are not at all optimized\footnote{e.g. strings are
    always written on a pixel basis using the T1lib library
    and don't define device fonts.}
  and in some cases you can prefer original \grace drivers.
  \\
  Some features will be available only if additional libraries are
  installed:
  \begin{itemize}
  \item
    \index{JPEG}
    The JPEG backend needs the IJG's {\em JPEG library}
    (\texttt{\aacurl} ), version 6.x.
  \item
    \index{PNG}
    The \grace PNG backend needs the {\em libpng} library\\
    (\texttt{\aadurl}version 0.96 or above).
  \item
    \index{PDF}
    The \grace PDFlib driver requires the PDFlib library of Thomas Merz to be
    installed, which is available {\em here} \texttt{\aaeurl}, version
    4.0.3 or above.\\    
    An alternative is to convert Postscript files into PDF with
    \texttt{epstopdf} or another conversion tool.
  \item
    \index{FFTW}\index{Fourier!FFTW}
    The \fftw library (Fast Fourier Transform) allows to perform
    Fourier transformation efficiently. If this package is not found,
    the Fourier transforms are computed by a conventional DFT,
    i.e. very inefficiently for large sets.\\
    \ggtk should work with \texttt{fftw-2} as well as with \texttt{fftw-3}.
    For more information on this package, see the
    {\em FFTW Home page} \texttt{\aafurl}.\\
    It is highly recommended if you want to compute Fourier
    transforms.
    If you want a fine tuning, see details in section
    \ref{fftw-tuning}.
  \item 
    The wavelet transforms are based on GNU Scientific Library (GSL).
    If the library is not installed, a bundled small part of the
    library is used. \\
    The library home is
    \url{ http://www.gnu.org/software/gsl/}.    
  \item
    \index{NetCDF}
    The NetCDF input driver existing in \grace is not implemented
    in \ggtk.
  \end{itemize}
%%
\item [Windows XP and Vista.]~\\
  \index{MS Windows}\index{Windows!XP}\index{Windows!Vista}
  You must have MinGW, MSYS and GTK+ installed.
  Each release of \ggtk is checked hastily to run under these OS,
  but Linux is the natural environment for \ggtk,
  thus obtaining a working program may need some hacking.
  You can have to hack autotools files to get  a working configure.
  and some features (e.g. piping) does not works under MS Windows.\\
  No testing has been done for the Cygwin environment.
%%
\item [Compilation.]~\\
  \index{compilation}
  \verb+cd gracegtk-+\textit{x.y.z}\\
  \texttt{./configure}\\
  should produce a working \texttt{Makefile}.
  \\
  \texttt{make}\\
  should compile the various elements.
  If something goes wrong, try to see if the problem has been
  described already in the \texttt{FAQ} (in the
  \texttt{doc} directory).\\
  If the \verb+./configure+ does not work for you,
  try to soft link \verb+ac-tools/configure.in+ in the main
   directory and to run  \texttt{autoconf} to regenerate
  the configure file.\\
  In a MS Window environment,
  the \verb+grace_np+ directory, is not compiled.
%%
\item [Configuration.]~\\
  \index{configuration}
  In order to get a working executable of \ggtk \textit{without
    install},   i.e. to be able to 
  run the program from \texttt{gracegtk-}\textit{x.y.z} directory,
  you need to
  \verb+export GRACEGTK_HOME=.+
  environment variable.
  For other variables, e.g. to launch the help viewer from the
  \texttt{help} menu see section
  \ref{environment-variables}.
%%
\item [Testing.]~\\
  \index{testing}
  \verb+make tests+\\
  will run for you various examples. For each example, you can play
  with the mouse and the menus to change the graphs displayed.
  If you prefer to run selected examples, just type\\
  \verb+export GRACEGTK_HOME=.+\\
  \verb+./src/ggrace+\\
  and select the examples with \texttt{Examples} menus.
%%
\item [Installation.]~\\
  \index{Installation}
  \verb+make install+\\
  install by default in \verb+/usr/local/gracegtk+
  (of course you need to have the right permissions).
  Then you must include in your profile file
\begin{verbatim}
export GRACEGTK_HOME=/usr/local/gracegtk
export PATH=$PATH:/usr/local/gracegtk/bin
\end{verbatim}
%% $ dollar needed by emacs/auctex to balance with upper dollar
  Upon start-up, \ggtk loads its init file \verb+gracerc+
  See  section \ref{gracerc} for details.\\
  You can also customize some environment variables,
  mainly for GUI size and help viewer configuration:
  see section \ref{environment-variables}.
%%
\item [Removing installation or installing a new version.]~\\
Just remove the installation directory 
(Unix/Linux default: \verb+/usr/local/gracegtk+).\\
If you want to install a new version and keep the old one, you
can simply rename the directory of the old one.
Accessing the old one will depend upon local variables setting.
%%
\end{description}
%% ............................
\subsection{Binary installation}
\subsubsection{MS Windows}
\index{MS Windows}\index{Windows!XP}\index{Windows!Vista}
Windows\copyright~~ binaries (32 bits) are available on
\url{http://gracegtk.sourceforge.net}~.
Simply unzip the file at the place of your choice and execute 
\texttt{ggrace.exe} in the \texttt{bin} directory.\\
Some features are not yet available under MS Windows.
\begin{itemize}
\item Printing: write into a file (e.g. in PDF) and use a reader
(e.g. Acrobat Reader) as previewer/printer interface.
\item Help: on line help will not work: use a viewer to read
  \verb+ doc/GraceGTK.pdf+
\item Piping is not available.
\end{itemize}
\subsubsection{Unix/Linux}
No binaries for these OS are distributed by the \ggtk home site.
%% ............................
\section{Getting started}
For a jump-in start, you can browse the demos
("\texttt{Examples}" menu tree).
These are ordinary Grace projects, so you can play with them
and modify them.
Also, read the \grace \emph{Tutorial} \texttt{\aahurl}.

O.k. Here's a VERY quick introduction:
\begin{enumerate}
\item  Start the GUI version: \texttt{ggrace} (return).
\item  Select/check the output medium and canvas size in
  \texttt{File/Print setup}.
\item  Load your data clicking the \texttt{Import} toolbar button.
\item  Open the Explorer by clicking \texttt{TreeView} button.
\item  Adjust what you want by selecting items in the drawing tree
  and using the contextual right pane menus.
  Default behaviour\footnote{
    This "instant update" feature can be disabled in the
    \texttt{Edit/Preferences} menu.}
  is that almost all changes in the pane are reflected by
  redrawing immediately the canvas.
  In few cases, you have to   acknowledge the changes with
  the ``\texttt{Apply}'' button.
\item  Data can be manipulated in \texttt{Data/Transformations}.\\
  As an example, to shift a data set by 20 to the left:
  open '\texttt{Evaluate Expression}',
  select the source graph and set on the left, the destination graph
  on the right, and say Formula:   $x=x-20$.
  If no set is selected on the right, a new set is created, if a set
  is selected, it is overwritten by the new one.\\
  As you'll probably notice, Grace can do MUCH more than that.
  Explore at your leisure.
\item  When you like your plot, select File/Print. That's it!
\end{enumerate}
Each time it is possible without to much complexity, the original
\texttt{grace-5} menus are preserved and should work as described in the
\texttt{grace-5} documentation but the \texttt{Menubar/Plot} menus now
open  the \texttt{Explorer} menus instead of old ones.

From the end user point of view,
the main novelties are the new toolbar buttons and the Explorer/TreeView
window dialog.
Try the Examples \ggtk menu entries to discover some of them.

\ggtk evolution is to add features copied from \gsix, the beta version
of grace-6. Thus, you can also have a look on \gsix and try it.

One of the main novelty in \ggtk is the development of an easy
management of "geometric" objects:
arcs, boxes, lines, polylines, strings and compounds,
inspired by the well known free program \texttt{xfig}
\index{xfig}\footnote{ \ggtk is not intended to be a replacement for
  \texttt{xfig} and only some features of \texttt{xfig} are included
  in \ggtk.}.
%%
%% ............................
\subsection{General concepts}
%%
\subsubsection{\ggtk command files}
\label{project-file}
\index{Files!command}
These files contains instructions for the command interpreter.
The language used is in principle upward compatible with \grace
command files.\\
A file containing all the information necessary to restore a plot
is called a \emph{project file}:
the default extension of the file is \texttt{.agr} and the commands
lines begins by a \texttt{@}\\
If it is a ``style sheet'' containing
only the parameters needed to draw similar graphs with other
compatible data, it is called a \emph{parameter file}:
the default extension of the file is \texttt{.par}
and for each line the leading \texttt{@} is ommitted.\\
See section \ref{Commandinterpreter} for details on \ggtk language.
%%
\subsubsection{Input data file}
\label{DataFiles}
\index{Files!data}
\ggtk reads ASCII text files containing space and comma separated
columns of data. The data fields can be either numeric (Fortran 'd' and
'D' exponent markers are also supported) or alphanumeric (with or
without quotes). \\
Several calendar date formats are recognized
automatically and you can specify your own reference for numeric
date formats. \\
Blank lines and lines beginning with \verb+#+ are ignored.\\
The end of a dataset is marked by a line with a \verb+&+\\
You can mix data and commands in a command file:
see section \ref{Commandinterpreter}  for details on \ggtk language.
%%
\subsubsection{Datasets and sets}
\label{datasets}
\index{Sets}
A \textit{dataset} (often called simply a \textit{set} in the following)
is a collection of points with $x$ and $y$ coordinates, up to
four optional data values (which, depending on the set type, can be
displayed as error bars or like) and one optional character string.\\
More generally, a \textit{set} is a way of representing datasets.
It consists of a dataset plus a collection of parameters
describing the visual appearance of the data (like color, line dash
pattern etc).\\
Note that each set has is own dataset (e.g. if several curves
have the same abscissas, the arrays for $x$ are duplicated).
%%
\subsubsection{Graphs and sets}
\label{graph}
\index{Graphs}
A \textit{graph} consists of (every element is optional): a graph
frame, axes, a title and a subtitle, a number of sets and additional
annotative objects (text strings, lines, boxes and
arcs of ellipses).

The \textit{graph type} can be any of:\label{graph-types}
\index{Graphs!types}\index{Polar graph}
\begin{itemize}
\item  XY Graph (curves, vector or color maps)
\item  XY Chart\\
  The idea of "XY Chart" is to plot bars (or symbols in general) of
  several sets side by side, assuming the abscissas of all the sets are
  the same (or subsets of the longest set).
\item  Polar Graph (see section \ref{polarhint}).
\item  Fixed Graph (i.e. X/Y ratio = 1)
\item  Pie chart
\item  XYHILO draw vertical bars between Hi and Low, with two
  horizontal ticks at Open and Close.
\end{itemize}
The \textit{set type} list is in table \ref{tab_set}.
\begin{table}[htbp]
  \begin{tabular}{||l|p{7mm}|p{11cm}||} \hline\hline
    Set type &  \# of num. cols &  Description \\ \hline
    XY       &  2 &  An $x,y$ scatter and/or line plot, plus (optionally) an annotated value \\ \hline
    XYDX     &  3 &  Same as XY, but with error bars (either one- or two-sided) along $x$-axis \\
    XYDY     &  3 &  Same as XYDX, but error bars are along $y$-axis \\
    XYDXDX   &  4 &  Same as XYDX, but left and right error bars are defined separately \\
    XYDYDY   &  4 &  Same as XYDXDX, but error bars are along $y$-axis \\
    XYDXDY   &  4 &  Same as XY, but with X and Y error bars (either one- or two-sided) \\
    XYDXDXDYDY &  6 &  Same as XYDXDY, but left/right and upper/lower error bars are defined separately \\ \hline
    BAR      &  2 &  Same as XY, but vertical bars are used instead of symbols \\
    BARDY    &  3 &  Same as BAR, but with error bars (either one- or two-sided) along $y$-axis \\
    BARDYDY  &  4 &  Same as BARDY, but lower and upper error bars are defined separately \\ \hline
    XYHILO   &  5 &  columns are X/Hi/Low/Open/Close \\ \hline
    XYZ      &  3 &  Same as XY; makes no sense unless the annotated value is $z$ \\
    XYR      &  3 &  $x, y$, Radius. Only allowed in Fixed graphs \\
    XYSIZE   &  3 &  Same as XY, but symbol size is variable \\ \hline
    XYCOLOR  &  3 &  $x, y$, color index (of the symbol fill)\\
    XYCMAP   &  3 &  $x, y$, \textit{color} interpolated in a dedicated color map.\\
    XYCOLPAT &  4 & $x, y$, color index, pattern index (currently used for Pie charts only) \\
    XYVMAP   &  4 &  Vector map ($x ,y ,V_x ,V_y$)\\
    XYBOXPLOT &  6 &  Box plot ($x$, median, upper/lower limit, upper/lower whisker) \\
    \hline
  \end{tabular}
  \caption{Set types}
  \index{Sets!types}
  \label{tab_set}
\end{table}
\begin{table}[htbp]
  \begin{center}
  \begin{tabular}{|l|ccccc|}    \hline \hline
    Set type   &  XY Graph &  XY Chart &  Fixed &  Polar &  Pie \\ \hline \hline
    XY         &  +        &  +        &  +     &  +     &  + \\  \hline
    XYDX       &  +        &  -        &  +     &  -     &  - \\
    XYDY       &  +        &  +        &  +     &  -     &  - \\
    XYDXDX     &  +        &  -        &  +     &  -     &  - \\
    XYDYDY     &  +        &  +        &  +     &  -     &  - \\
    XYDXDY     &  +        &  -        &  +     &  -     &  - \\
    XYDXDXDYDY &  +        &  -        &  +     &  -     &  - \\ \hline
    BAR        &  +        &  +        &  +     &  -     &  - \\
    BARDY      &  +        &  +        &  -     &  -     &  - \\
    BARDYDY    &  +        &  +        &  -     &  -     &  - \\ \hline
    XYHILO     &  +        &  -        &  -     &  -     &  - \\ \hline
    XYZ        &  +        &  -        &  +     &  +     &  - \\
    XYR        &  -        &  -        &  +     &  -     &  - \\
    XYSIZE     &  +        &  +        &  +     &  +     &  - \\
    XYCOLOR    &  +        &  +        &  +     &  +     &  + \\
    XYCMAP     &  +        &  -        &  +     &  -     &  - \\
    XYCOLPAT   &  -        &  -        &  -     &  -     &  + \\
    XYVMAP     &  +        &  -        &  +     &  -     &  - \\
    XYBOXPLOT  &  +        &  -        &  -     &  -     &  - \\  \hline
    \hline
  \end{tabular}
  \caption{Graph/Set type connection}
  \label{tab_graphset}
  \index{Graphs!sets types compatibility}
  \index{Sets!graphs types compatibility}
  \end{center}
\end{table}
Not all set types, however, can be plotted on any graph type.\\
The table~\ref{tab_graphset} summarises the constraints.
%%
%% ............................
\subsubsection{World and viewport coordinates}
\index{World coordinates}\index{Viewport coordinates}
There are two types of coordinates in Grace: the \textit{world
coordinates} and the \textit{viewport coordinates}. Points of
data sets are defined in the world coordinates and the
tickmarks of the axes give the scales.
The viewport coordinates correspond to the image of the plot drawn on
the canvas.  The transformation converting the world coordinates into
the viewport ones is determined by both the graph type and the axis
scaling.
%%
%% ............................
\subsubsection{Regions}
\label{regions}
\index{Regions}
\textit{Regions} are sections of the graph defined by the interior or
exterior of a polygon, or a half plane defined by a line. Regions are
used to restrict data transformations to a geometric area occupied by
region.
%%
%% ............................
\subsubsection{Geometric objects}
\label{geometric-objects}
\index{Objects!definition}
\index{Arc}\index{Box}\index{Line}\index{Polyline}
\index{Ellipse}\index{String}
\emph{Boxes, strings, lines} and \emph{arcs} can be defined
independently of graphs, thus are called \textit{geometric}.
\begin{description}
\item[Boxes] are simple rectangles
\item[Strings] are used to display some text.\\
  It is possible to use  new lines (\verb+\n+), Grace escape
  sequences, \textit{etc} to beautify the output.
\item[Lines] are segments linking two points, with possibly arrows at
  the ends and a label displaying the length.
\item[Polylines] are segments connecting points and can be closed or
  opened, drawn as zigzags or smooth X-spline interpolated curves.
\item[Arcs] are arcs of ellipse. For an easy manipulation, it is
  possible to particularise as a complete ellipse or a circle defined by
  radius or bounding box.
\end{description}
%%
%% ............................
\subsubsection{Identification numbers}
\index{id-numbers}
A \textit{id-number} is attached to each graph, set or geometric
object.
The numbering is global for graphs and geometric objects and relative
to a graph for the sets. The id-number is attributed by the program
when the element is created or the project is red.
If one element is killed, its \textit{id-number} is not reused.\\
\textit{Id-numbers} are used to build compounds.\\
Beware when you merge two different command files that the
numbers may overlay and in that case,
you have to manually change the numbers attached to different
objects.
%%
\subsubsection{TreeView}
The various elements of the drawing are linked by a tree structure
that can be visualised in the \texttt{Explorer} windows.
Each graph is the head of a branch of the tree containing axes, sets,
legend box and optionally, geometric objects.
%%
\subsubsection{Layers}
\index{Layers}
The drawing is done on one or several \textit{layers}, with depths in
the range \texttt{[1,100]}, starting to draw the deepest, then the
upper ones.
The default layer depth is 50 and when more than one layer is used,
a column of check boxes appears at the right of the canvas, allowing
to choose what layers are to be displayed.\\
This allows a fine control of the foreground/background issue.
%%
\subsubsection{Compounds}
Compounds are used to glue together in a single branch existing
geometric objects, allowing to move, copy or delete all of them as a
single block.\\
The geometric objects glued are pointed by the pair 
(\textit{type-name, id-number})
and must be homogeneous with respect to
their attachment and  \texttt{loctyp} (viewport or world
coordinates).
%%
\subsubsection{Real Time Input}
\label{RTI}
Real Time Input refers to the ability Grace has to be
fed in real time by an external program in a Unix/Linux
environment.
The Grace process spawned by the driver program is a full featured
Grace process: the user can interact using the GUI at the
same time the program sends data and commands. The process
will adapt itself to the incoming data rate.\\
A less sophisticated alternative but working also in the MS Windows
environment is the use of \hyperlink{hot-links}{\texttt{Hot links}} .
%%  %%
%%  \subsubsection{Hotlinks} \label{hotlinks}
%%  Hotlinks are sources containing varying data. Grace can be
%%  instructed a file or a pipe is a hotlink in which case it
%%  will provide specific commands to refresh the data on a
%%  mouse click (a later version will probably allow automatic
%%  refresh).
%%
\subsubsection{Devices}
\label{devices}
\index{Devices}\index{Drivers}
Grace allows the user to choose between several output
devices to produce its graphics. The current list of
supported devices is:
\begin{itemize}
\item  GTK console (the canvas)
\item  PostScript (level 1 and level 2)
\item  EPS (encapsulated PostScript)
  %% \item  Metafile (which is Grace format, used at the moment mostly
  %%   for debugging purposes)
\item  MIF (Maker Interchange Format used by FrameMaker)
\item  SVG (Scalable Vector Graphics, a language for describing
  two-dimensional vector and mixed vector/raster graphics
  in XML)
\item  PDF
  \index{PDF}
  (see section \ref*{configuration}:
  \hyperlink{extra-lib}{\texttt{Extra libraries}}),
\item  PNM (portable anymap file format),
\item  JPEG
  \index{JPEG}
  (see section \ref*{configuration}:
  \hyperlink{extra-lib}{\texttt{Extra libraries}}),
\item  PNG
  \index{PNG}
  (see section \ref*{configuration}:
  \hyperlink{extra-lib}{\texttt{Extra libraries}}),
\end{itemize}
Note that Grace no longer supports GIF due to
the copyright policy of Unisys. Grace can also be
instructed to launch conversion programs automatically
based on file name. As an example you can produce MIF
(FrameMaker Interchange Format) or Java applets using
pstoedit, or almost any image format using the netpbm suite
(see the  \emph{FAQ} \texttt{\aaiurl}).
%%
\subsubsection{Magic path}
\label{magic-path}
\index{Magic path}
In many cases, when Grace needs to access a file given with a
relative \texttt{pathname}, it searches for the file along the
following path:\\
\texttt{./pathname:./.grace/pathname:\~{}/.grace/pathname:\$GRACE\_HOME/pathname}
%%  %%
%%  \subsubsection{Dynamic modules}\label{dynamic-modules}
%%  Grace can access external functions present in either system
%%  or third-party shared libraries or modules specially compiled
%%  for use with it. The term dynamic refers to the possibility
%%  Grace has to open the library at run time to find the code of
%%  the external function, there is no need to recompile Grace
%%  itself (the functions already compiled in Grace are
%%  "statically linked").
%% ............................
\subsection{Invocation}
%%
The name of the executable is \texttt{ggrace} 
(or \texttt{ggrace.exe} in a Windows environment).
It can be followed by
the  options below\footnote{Note that all the options had not been
  systematically tested when \grace had been changed in \ggtk.
  Please make a report if you encounter problems with these options.
  A known bug is with the -pipe one: GTK waits the end of the run to
  display the curves, wiping intermediate results.
  A workaround is to use the \texttt{ libgrace\_np.a}  library to
  interface your program with \ggtk.}.
%%
\subsubsection{Command line options}
\index{Command line options}
\begin{description}
\item[ -autoscale \textit{ x$|$y$|$xy\/} ]~\\
  Override any parameter file settings
\item[ -barebones ]~\\
  Turn off all toolbars
\item[ -batch \textit{ batch\_file\/} ]~\\
  Execute batch\_file on start up (i.e., after all other options
  have been processed and the UI initialized)
\item[ -block \textit{ block\_data\/} ]~\\
  Assume data file is block data
\item[ -bxy \textit{ x:y:etc.\/} ]~\\
  Form a set from the current block data set using the current set
  type from columns given in the argument
\item[ -datehint \textit{ iso$|$european$|$us$|$days$|$seconds$|$nohint\/} ]~\\
  Set the hint for dates analysis
\item[ -dpipe \textit{ descriptor\/} ]~\\
  Read data from descriptor (anonymous pipe) on startup \linuxonly
\item[ -fixed \textit{ width\/} \textit{ height\/} ]~\\
  Set canvas size fixed to $width*height$
  %% \item[ -free ]~\\
  %%   Use free page layout
\item[ -graph \textit{ graph\_number\/} ]~\\
  Set the current graph number
\item[ -graphtype \textit{ graph\_type\/} ]~\\
  Set the type of the current graph
\item[ -hardcopy ]~\\
  No interactive session, just print and quit
\item[ -hdevice \textit{ hardcopy\_device\_name\/} ]~\\
  Set default hardcopy device
\item[ -install ]~\\
  Install private colormap
\item[ -legend \textit{ load\/} ]~\\
  Turn the graph legend on
\item[ -log \textit{ x$|$y$|$xy\/} ]~\\
  Set the axis scaling of the current graph to logarithmic
\item[ -maxpath \textit{ length\/} ]~\\
  Set the maximal drawing path length
%%  \item[ -mono ]~\\
%%    Run Grace in monochrome mode (affects the display only)
%%  \item[ -netcdf \textit{ file\/} ]~\\
%%    Assume data \textit{ file\/} is in netCDF format. This option is
%%    present only if the netCDF support was compiled in
%%  \item[ -netcdfxy \textit{ X\_var\/} \textit{ Y\_var\/} ]~\\
%%    If -netcdf was used previously, read from the netCDF file
%%    \textit{ X\_var\/} \textit{ Y\_var\/} variables and create a set. If
%%    \textit{ X\_var\/} name is "null" then load the index of Y to X.
%%    This option is present only if the netCDF support was compiled
%%    in
\item[ -noask ]~\\
  Assume the answer is yes to all requests - if the operation would
  overwrite a file, Grace will do so without prompting
\item[ -noinstall ]~\\
  Don't use private colormap
\item[ -noprint ]~\\
  In batch mode, do not print
\item[ -nosafe ]~\\
  Disable safe mode
\item[ -nosigcatch ]~\\
  Don't catch signals
\item[ -npipe \textit{ file\/} ]~\\
  Read data from named pipe on startup  \linuxonly
\item[ -nxy \textit{ nxy\_file\/} ]~\\
  Assume data file is in X Y1 Y2 Y3 ... format
\item[ -param \textit{ parameter\_file\/} ]~\\
  Load parameters from parameter\_file to the current graph
\item[ -pexec \textit{ parameter\_string\/} ]~\\
  Interpret string as a parameter setting
\item[ -pipe ]~\\
  Read data from stdin on startup \linuxonly
\item[ -printfile ]~\\
  \textit{ file\/} Save print output to file
\item[ -remove ]~\\
  Remove data file after read
\item[ -results \textit{ results\_file\/} ]~\\
  Write results of some data manipulations to results\_file
\item[ -rvideo ]~\\
  Exchange the color indices for black and white
\item[ -safe ]~\\
  Run in the safe mode (default) - no file system modifications
  are allowed through the batch language
\item[ -saveall \textit{ save\_file\/} ]~\\
  Save all graphs to save\_file
\item[ -seed \textit{ seed\_value\/} ]~\\
  Integer seed for random number generator
\item[ -settype \textit{ xy$|$xydx$|$...\/} ]~\\
  Set the type of the next data file
\item[ -source \textit{ disk$|$pipe\/} ]~\\
  Source type of next data file \linuxonly
\item[ -timer \textit{ delay\/} ]~\\
  Set allowed time slice for real time inputs to delay (in ms)  \linuxonly
\item[ -timestamp ]~\\
  Add timestamp to plot
\item[ -version ]~\\
  Show the program version
\item[ -viewport \textit{ xmin ymin xmax ymax\/} ]~\\
  Set the viewport for the current graph
%%  \item[ -wd \textit{ directory\/} ]~\\
%%    Set the working directory
\item[ -world \textit{ xmin ymin xmax ymax\/} ]~\\
  Set the world coordinates for the current graph
\item[ -usage$|$-help ]~\\
  This message
\end{description}
%% ............................
\subsection{Customization}
\index{Customization}
\subsubsection{Environment variables}
\label{environment-variables}
\index{Customization!environment variables}
\begin{itemize}
\item  \verb+GRACEGTK_HOME+~\\
\index{GRACEGTK\_HOME}
  Set the location of \ggtk. This will be where help files,
  auxiliary programs, and examples are located.
  Default installation directory is \texttt{/usr/local/gracegtk}.
  If you are unable  to find the location of this directory, contact
  your system  administrator.\\
  The executables are in  \verb+$GRACEGTK_HOME/bin+.%%$
\item  \verb+GRACEGTK_GUI_SIZE+~\\
\index{GRACEGTK\_GUI\_SIZE}
  Allow to choose GUI size when \texttt{ggrace} is launched, e.g.\\
  \verb+export GRACEGTK_GUI_SIZE=900x1200+\\
  allows to launch a window 900 pixels wide and 1200 pixels high.\\
  Default is set to \texttt{900x775}.

\item  \verb+GRACE_PRINT_CMD+~\\
  Print command. If the variable is defined but is an empty
  string, "Print to file" will be selected as default.
\item  \verb+GRACEGTK_HELPVIEWER+~\\
  \ggtk documentation is in PDF format: specify here viewer to use.
  Default is
  \verb+ firefox %s+ for Unix/Linux systems and
  \verb+ acroread %s+ for Windows systems.\\
  The HTML version of the \ggtk guide is not compiled by \texttt{make}. 
  You have to  follow the  instructions in
  \verb+doc/README+ source file to manually compile and install if you
  want an HTML version.
\item  \verb+GRACE_HELPVIEWER+~\\
  The shell command to run a help viewer for on-line browsing of
  the help documents in HTML format.\\
  Must include at least one instance of   "\verb+%s+"
  which will be replaced with the actual URL by Grace.\\
  Default hard coded viewer is presently
  "\verb+firefox %s+" because it
  is found in most systems and allows to display many formats.
\item  \verb+GRACE_EDITOR+~\\
  The editor used for manual editing of dataset values.
\item  \verb+GRACE_FFTW_WISDOM_FILE+ and
  \verb+GRACE_FFTW_RAM_WISDOM+~\\
  These flags control behavior of the \fftw planner (see
  section \ref{fftw-tuning}  for detailed info)
\end{itemize}
%%
\subsubsection{Init file}
\label{gracerc}
\index{Customization!init file}
Upon start-up, Grace loads its init file: \texttt{gracerc}.
The file is searched for in the magic path
(see \ref{magic-path});
once found, the rest of the path is ignored.
It's recommended that in the \texttt{ gracerc} file,
one doesn't use statements which are part of a project file - such
defaults, if needed, should be set in the default template
(see \ref{default-template}).
%%
\subsubsection{Default template}
\label{default-template}
\index{Customization!default template}
\index{template}
\index{Examples}
Whenever a new project is started, Grace loads the default template,
\texttt{ templates/Default.agr}~.\\
The file is searched for in the magic path (see  \ref{magic-path});
once found, the rest of the path is ignored.
It's recommended that in the default template,
one doesn't use statements which are NOT part of a project
file - such defaults, if needed, should be set in the file
\texttt{gracerc} (see \ref{gracerc}).\\
\ggtk examples rely on the default template file to run correctly.

%% ............................
\section{Guide to the graphical user interface}
\label{GUI-guide}
%% ............................
\ggtk window have below its menubar a status line displaying
the \textit{locator} \index{Locator}
(i.e. the mouse pointer) coordinates on the left
and a \textit{status message} on the right.\\
Below, it display on the left a \textit{toolbar} with various buttons
frequently used, and on its right the \textit{canvas}, i.e. the
drawing area.
%% ............................
\subsection{ Using mouse}
%% ............................
%% ............................
\subsubsection{Using left button (button 1)}
\index{Mouse!button 1}
\begin{itemize}
\item
  In the left toolbar a click selects an action to be 
  performed\footnote{The status message in the upper right corner
    reflects it.} (zoom, copy, move,\dots) .
  Then, selecting one object in the canvas allows to perform the
  action on this object\footnote{In this matter, our models are the
    \texttt{xfig} program and Grace.}. 
\item
  In the Explorer popup, clicking one row in the left TreeView
  will select this element and show the corresponding
  menu in the right pane.
  If the \texttt{instantaneous update} option is on (the default) 
  most of the changes in the right pane are immediately displayed in
  the canvas. 
  If not, use the \texttt{Apply} or \texttt{Accept} buttons.
\item
  In the TreeView, the label column is editable. 
  See section \ref{secExplorerWindow} for details.
\item
  In the TreeView, selecting a \texttt{template} in TreeView allows to
  create a new object. 
\item
  It is sometimes difficult to select one object in the canvas when
  neighbouring objects are also selectable, thus action buttons are
  also displayed in the bottom of the right panes. The difference with
  the toolbar buttons is that only one object is selectable if you use
  these buttons.
\item
  In the canvas, the nature of the action of the mouse is the one
  selected previously in the left toolbar.
  In the no ``no action'' state (see below), a click allows to change
  the focus from one graph to another.
\end{itemize}
%% ............................
\subsubsection{Using mouse button 3}
\label{secExplorBt3}
\index{Mouse!button 3}
\texttt{Button3} is usually the right button of the mouse.
\begin{itemize}
\item
  In the canvas, mouse \texttt{Button3} is used to cancel the action
  selected in the left toolbar and returns to the
  ``no action'' state.
\item 
  In the TreeView, it fires menus depending upon the item(s)\footnote{
    Selecting several elements is made using the GTK standard:
    \texttt{shift} to select all elements between two rows,
    \texttt{control} to add a clicked element to the list.}
  selected.
  The idea is to perform actions on selected elements without further
  mouse interaction into the canvas.
  \\
  The meaning of most entries are obvious, we comment only few.
  \begin{itemize}
  \item 
    The \texttt{Update} entries allows collective but selective updates if
    the selected items have all the same type.
    A \texttt{Update} window is fired with
    check buttons to select the parameters used for the update.
    The update values are red in the right pane (visible or hidden)
    and 
    the \texttt{Apply} button to use is the one in the \texttt{Update}
    popup.
  \item 
    \index{Fonts!Font tool}
    The \texttt{Use font tool} entries fires the \texttt{Font tool}
    popup and copy the label into (see section \ref{fonttool}).
  \item 
    For creating or changing compounds, see section \ref{secCompounds}.
  \end{itemize}
\item
  In the right panes, some spin buttons are used to enter floating
  point values (typically, coordinates $x_1, y_1, x_2, y_2$ for
  arcs, \textit{etc}). 
  The program try to figure pertinent  parameter settings for the 
  \texttt{min, max, step} values for these buttons but is not
  very smart. The menu raised with \texttt{Button3} clicked into
  the entry box offers a \texttt{Manage spin button} popup which
  allows   to fix manually the settings and also the value of the
  variable. 
  Moreover, the entries in this popup are scanned by the command
  interpreter, allowing to use variables and formulas.
\item
  The \texttt{Font tool} can also be used to enter some strings
  in the right pane.
\end{itemize}
%% ............................
\subsection{ Left toolbar}
%% ............................
Along the left-hand side of the canvas (if shown) is the
\texttt{ToolBar}.
It is armed with several buttons to provide quick and easy access to
the more commonly used Grace functions.\\
The \texttt{Examples/\ggtk/Explain} menu entry
as well as \textit{tooltips}
show short explanations about the use of the toolbar buttons.
Here is some details.\\
The upper buttons are inherited from \grace.
The new toolbar buttons are inspired by the well-known program
\texttt{ xfig}.
\index{xfig}
\begin{itemize}
\item  \texttt{Draw}:
  This will redraw the canvas and sets.
  Useful if "Auto Redraw" has been deselected in the
  \texttt{Edit/Preferences}   dialog.
\item  \texttt{Lens}:
  A zoom lens.  Click on the lens, then select the
  area of interest on the active graph with the "rubber box".
  The region  enclosed by the  box will fill the entire graph.
\item  \texttt{AS}:
  AutoScale.  Autoscales the active graph to contain
  all  data points of all visible (not hidden) sets.
\item  \texttt{Z/z}:
  Zoom the active graph in/out by 5\%.\\
  The zoom percentage can be set in the Edit/Preferences dialog.
\item  \texttt{Arrows}:
  Scroll active graph by 5\% in the arrow's
  direction.  The scroll percentage can be set in the
  Edit/Preferences dialog.
\item  \texttt{AutoT}:
  AutoTick Axes.  This will find the optimum
  number of major and minor tick marks for both axes.
\item  \texttt{AutoO}:
  Autoscale On set.  Click the \texttt{AutoO} button, then click on
  the graph near the set you wish to use for
  determining the autoscale boundaries of the graph.
\item  \texttt{ZX,ZY}:
  Zoom along an axis.  These buttons work like the
  zoom lens above but are restricted to a single axis.
\item  \texttt{AX,AY}:
  Autoscale one axis only.
  The following buttons deal with the graph stack and there is a good
  example under Examples grace-5/General Intro/World Stack.
\item  \texttt{Pu/Po}:
  Push and pop the current world settings to/from
  the graph stack. When popping, makes the new stack top current.
\item  \texttt{PZ}:
  Push before Zooming.  Functions as the zoom lens,
  but first pushes the current world settings to the stack.
\item  \texttt{Cy}:
  Cycles through the stack settings of the active
  graph.  Each graph may have up to twenty layers on the stack.
\item The \texttt{Edit}
  button pops up the explorer with
  the parameters of the object selected with the mouse
  in the right pane.
  It is not true for graphs, which are a special case.\\
  To select a set in a graph, the graph must be the active graph and
  you must click on a point of the set, not on the interpolating
  line.\\
  In many cases, a double-click on the element produces the same
  effects without clicking the \texttt{Edit} button.
\item The \texttt{Move, copy,\dots }
  buttons are used to perform the actions
  with the mouse on the object selected.
  The check button at the left of the \texttt{Edit}  button can be
  used to show/hide the object.
\item The frame below
  contains buttons to delete, move or add a point
  in a set of the active graph.
\item The \texttt{Import}
  button is a direct access to the
  \hyperlink{import-ascii}{\texttt{Import ASCII}} dialog.
\item The \texttt{TreeView}
  button pops up the explorer window without changing its state.
\item  \texttt{Exit}:
  Pretty obvious, eh?
\end{itemize}
%% ............................
\subsection{Menubar}
It is used to access the following menus.
\subsubsection{File menu}
\begin{description}
\item[\texttt{New}]~\\
  Wipe out present drawing to restart a new one.
\item[\texttt{Open project}]~\\
  As \texttt{New}, but also popup a \textit{Open project} window to read a
  \texttt{.agr} command file, usually a project one.
\item[\texttt{Save}]~\\
  Save the drawing in the present opened project file.
  If no file is opened, save in the file named \verb+Untitled$+%%$
\item[\texttt{Save as\dots}]~\\
  Open a \textit{Save project} window to choose a file to save into.\\
  Be careful that the default format proposed to save data can be not
  precise enough to fill your needs.\\
  The \texttt{Differential} option allows to save only values
  different from the templates. It is useful if you want to edit
  manually the file, but beware that it is not self consistent and the
  result may vary if defaults are changed.
\item[\texttt{Revert to saved}]~\\
  Abandon all modifications performed on the project since the
  last save. A confirmation popup is fired to allow the user
  canceling the operation.
\item[\texttt{Load parameters\dots}]~\\
  Open a \textit{Read parameters} window to read a parameters file
  (see section \ref{project-file}).
\item[\texttt{Save parameters\dots}]~\\
  Open a \textit{Write parameters} window to write a parameters file
  (see section \ref{project-file}).
\item[\texttt{Import ASCII data}]~\\
  \hypertarget{import-ascii}{}
  Open a \textit{Read data file} window to read ASCII data
  (see section \ref{DataFiles}), i.e.
  by default a \texttt{.dat} file.
  A graph selector is used to specify the graph where the
  data should go (except when reading block data, which are
  copied to graphs later on). The \texttt{load type} have following
  meanings.
  \begin{itemize}
  \item
    \textit{Single set} means that if the source contains
    only one column of numeric data, one set will be created
    using the indices (from 1 to the total number of points) as
    abscissas and read values as ordinates and that if the source
    contains more than one column of data, the first two numeric
    columns will be used.
  \item
    \textit{NXY} means that the first
    numeric column will provide the abscissas and all remaining
    columns will provide the ordinates of several sets.
  \item
    \textit{Block data} means all column will be read and
    stored and that another popup will allow to select the abscissas and
    ordinates at will. It should be noted that block data are stored as
    long as you do not override them by a new read. You can still retrieve
    data from a block long after having closed all popups, using the set
    selector.
  \item
    \textit{Select cols.} is an alternative to \textit{Block data}
    making easy to read several sets at a time 
    by the use of a format string called  \textit{Sel.}
    Each blank(s) separated character in the  \textit{Sel.} string  
    stands for one column in the data file 
    and have the following meaning
    \begin{itemize}
    \item $x$: the column is for abscissas (should appear only once)
    \item $y$: the column is for ordinates
    \item $z$: the column is for $z$ values (if relevant with respect
      to set type),
    \item - :  (minus sign) the column is ignored, i.e. no set is
      created, 
    \item To ignore the last columns, just erase the corresponding
      last $y$
    \end{itemize}
    It is possible  in the data file to give a name to each data
    column if the data is headed 
    by a line starting by an exclamation mark (!) followed by the
    wanted names.
    These names (one per column) will be used as legend strings for the
    new sets. \\
    Try \verb+ Examples/GraceGTK/Import ASCII+.
  \end{itemize}
  The set type can be one of the predefined set presentation types
  (see tables \ref{tab_set} and \ref{tab_graphset}).

%%    The data source can be selected as \textit{Disk} or \textit{Pipe}.
%%    In the
%%    first case the text in the "Selection" field is considered to
%%    be a file name (it can be automatically set by the file
%%    selector at the top of the popup). In the latter case the
%%    text is considered to be a command which is executed and
%%    should produce the data on its standard output. On systems
%%    that allows is, the command can be a complete sequence of
%%    programs glued together with pipes.

  If the source contains date fields, they should be
  automatically detected. Several formats are recognized (see appendix
  \ref{dates} {(dates in Grace)}). Calendar dates are converted to
  numerical dates upon reading.\\
  The \textit{Autoscale on read} menu controls whether, upon reading
  in new sets, which axes of the graph should be autoscaled.
%%
\item[\texttt{Export ASCII data}]~\\
  \hypertarget{export-ascii}{}
  Save data sets in a file.
  A set selector is used to specify the set of the active graph to be saved.
  The format to use for saving data points can be specified:
  \textit{beware that the default format may be not large enough to
  fill your needs}.\\
  A warning is displayed if a file with the same name already exists.

%%
\item[\texttt{Print setup\dots}]~\\
  \hypertarget{print-setup}{}
  Set the properties of the printing device.\\
  According to the device, the output can be sent either directly to a
  printer or directed to a file.\\
  Some devices have specific options (see \ref{device-settings}) and
  can emit a 'Printout truncated' warning.\\
  Page dimensions units can be pixels/inches/centimetres.
  The values in pixels depends upon the resolution (dpi) of the device
  and the predefined formats (A4 or Letter) are automatically
  detected; thus if in \texttt{Custom} mode, you give one of these
  values, the \texttt{Size} combobox is changed.\\
%% The global settings available for all devices are
%%   the sizing parameters. The size of the graph is fixed. Changing the
%%   'Page' settings changes the size of the canvas underneath the graph.
%%   Switching between portrait and landscape interchange $x$ and $y$
%%   dimensions of the canvas.
%%   Make
%%   sure the canvas size is large enough to hold your graph.  Otherwise
%%   you get a 'Printout truncated' warning. If your canvas size cannot
%%   easily be changed because, for example, you want to print on letter
%%  size paper, you need to adjust the size of your graph

{ \huge  A TERMINER}

  You can adjust 
  (\textit{Viewport} in   \textit{TreeView/Project/Page}).\\
  In some cases, you can choose between several drivers for the same
  output format. \\
  See
  \hyperlink{extra-lib}{\texttt{Output drivers and extra libraries}}
  section for details.
\item[\texttt{Print}]~\\
  Print the project using the current printer settings
  (either in file or printer).
\item[\texttt{Quit}]~\\
  Exit from Grace. If some work has been done and not saved, a
  warning popup will be displayed to allow the user to cancel the
  operation.
\end{description}
%%
\subsubsection{Edit menu}
\begin{description}
%%
\item[\texttt{Undo/Redo}]~\\
  Commands corresponding to changes applied when the \texttt{Apply}
  button is clicked in the explorer are recorded by this subsystem and
  can be undoed or redoed.This feature works only
  when two reciprocal commands exists: e.g. data transformations and
  killings are excluded.
%%
\item[\texttt{Explorer}]~\\
  Popup the Explorer window, analogous to the \texttt{TreeView} button
  in the toolbar.
%%
\item[\texttt{Data sets...}]~\\
  Using the data set popup, you can view the properties of
  datasets. This include its type, length, associated comment and
  some statistics (min, max, mean, standard deviation).
%%
\item[\texttt{Set operations...}]~\\
  \hypertarget{set-operations}{}
  The set operations popup allows you to interact with sets as a
  whole. If you want to operate on the data ordering of the sets, you
  should use the \hyperlink{data-set-operations}{data set operations}
       popup   from the \texttt{Data} menu.
  The popup allows you to select a source (one set
  within one graph) and a destination and perform some action upon them
  (copy, move, swap). This popup also give you a quick access to several
  graph and set selectors if you want to perform some other operation
  like hiding a graph or creating a new set from block data.
%%
\item[\texttt{Arrange graphs...}]~\\
  \label{arrange-graphs}
  This entry opens the \texttt{Layout} tab of the \texttt{Project} row
  in the Explorer. 
  This allows to dispose several graphs in a
  regular grid given by $M$ rows and $N$ columns.
  \\
  The graph list at the bottom allows one to select a number of
  graphs the arrangement will operate on. 
  If the number of selected graphs isn't equal to $M \times N$, 
  new graphs may be created or extra graphs killed if needed. 
  These options are  controlled by the
  respective check boxes at the top of the pane.
  \\
  The order in which the matrix is filled in with the graphs can be
  selected (first horizontally then vertically or vise versa, with
  either of them inverted). Additionaly, one may choose to fill the matrix
  in the snake-like manner (adjacent "strokes" are anti-parallel).
  \\
  The rest of the controls of the dialog window deal with the matrix
  spacing: \\
  \texttt{left/right/top/bottom} page offsets (in the
  viewport coordinates) and \textit{relative\/} inter-cell distances,
  vertical   and horizontal.
  Next to each of the vertical/horizontal spacing  spinboxes, a
  "\texttt{Pack}" checkbox is found. Enabling it effectively sets
  the respective inter-cell distance to zero and alter axis tickmark
  settings such that only bottom/left-most tickmarks are visible.
  \\
  If you don't want the regular layout this arrangement gives you,
  you can change it afterwards using the mouse or the \texttt{Main}
  tab in \texttt{Graph} explorer right pane.
%%
\item[\texttt{Overlay graphs\label{overlay-graphs}}]~\\
  You can overlay a graph on top of another one.\\
  The main use of
  this feature is to plot several curves using different scales on
  the "same" graph.
  Use the TreeView to choose one between overlayed graphs
%%
\item[\texttt{Autoscale\label{autoscale}}]~\\
  Using this entry, you can autoscale one graph or all graphs
  according to the specified sets only. This is useful if you need
  either to have truly comparable graphs despite every one
  contains data of different ranges, or if you want to focus your
  attention on one set only while it is displayed with other data
  in a complex graph.
%%
\item[\texttt{Regions menu\label{regions-menu}}]~
  \index{Regions!menu}
  \begin{description}
  \item[\texttt{Status}\label{status}]
    This small popup only displays the current state (type and
    whether it is active or not) of the existing regions.
  \item[\texttt{Define}\label{define}]
    You can define a new region (or redefine an existing one),
    the allowed region types are:
    \begin{itemize}
    \item  Inside polygon
    \item  Outside polygon
    \item  Above line
    \item  Below line
    \item  Left of line
    \item  Right of line
    \item  In horizontal range
    \item  In vertical range
    \item  Out of horizontal range
    \item  Out of vertical range
    \end{itemize}
    A region can be either linked to the current graph only or to
    all graphs.
  \item[\texttt{Clear}\label{clear}]
    This kills a region.
  \item[\texttt{Report on}\label{report-on}]
    This popup reports you which sets or points are inside or
    outside of a region.
  \end{description}
\item[\texttt{Hot links }]\hypertarget{hot-links}{}~\\
  \index{Hot links}
  It is a way to update sets when the contents of data files are
  changed without the need to reopen manually the files.\\
  To establish a link between a file and an existing set, 
  in the \texttt{Hot links} window,
  use the \texttt{Files...} button to choose a file, 
  then a set in the
  \texttt{Link to sets} part of the window and push the \texttt{Link}
  button: the link should be displayed in the upper part of the
  window. Then, pushing the \texttt{Update} button will reread all the
  linked files.\\
  It is also possible to use pipes instead of files\footnote{Except in a 
  MS Windows environment.}.
  \\
  Currently, only simple XY sets can be used for hotlinks.
%%
\item[\texttt{Set locator fixed point}\label{set-locator-fixed-point}]~\\
  \index{Locator}
  After having selected this menu entry, you can select a point on
  a graph that will be used as the origin of the locator display
  (just below the menu bar). The fixed point is taken into account
  only when the display type of the locator is set to [DX,DY].
%%
\item[\texttt{Clear locator fixed point }\label{clear-locator-fixed-point}]
  This entry is provided to remove a fixed point set before and
  use the default again: point [0, 0].
%%
\item[\texttt{Locator props}\label{locator-props}]~\\
  The locator props popup allows you to customize the display of
  the locator, mainly its type and the format and precision of the
  display. You can use all the formats that are allowed in the
  graphs scales.
%%
\item[\texttt{Preferences}]~\\
  The preferences popup allows you to set miscellaneous properties
  of your Grace session, such as GUI behavior, cursor type,
  date reading hint and reference date used for calendar conversions.
\end{description}
%%
\subsubsection{Data menu}
\label{preferences}
\begin{description}
\item[\texttt{Data set operations\hypertarget{data-set-operations}{}}]~\\
  \index{sorting}\index{Sets!sorting}
  This popup gathers all operations that are related to the
  ordering of data points inside a set or between sets. If you
  want to operate on the sets as a whole, you should use the
  \hyperlink{set-operations}{\texttt{set operations}} popup
  from the \texttt{Edit}  menu.
  You can sort according to any coordinate ($X, Y, DX, \dots$)
  in ascending or descending order, reverse the order of the
  points, join several sets into one, split one set into several
  others of equal lengths, or drop a range of points from a
  set. The  \texttt{set selector} of the
  popup shows the number of points in each set in square brackets
  like this: G0.S0{[}63], the points are numbered from 0 to $n-1$.
\item[\texttt{Transformations menu }]~\\
  The transformations sub-menu gives you access to all data-mining
  features of Grace.
  \begin{description}
  \item[\texttt{Evaluate expression}]~\\
    \index{formula}\index{Regions}
    Using \texttt{evaluate expression} allows you to create a set by
    applying an explicit formula to another set, or to parts of
    another set if you use regions restrictions.
    \\
    All the classical mathematical functions are available (cos,
    sin, but also lgamma, j1, erf, ...). As usual all
    trigonometric functions use radians by default but you can
    specify a unit if you prefer to say cos (x rad) or sin (3 * y
    deg). For the full list of available numerical functions and
    operators, see sections \ref{expressions} and \ref{sec-functions}.
    \\
    In the formula, you can use X, Y, Y1, ..., Y4 to denote any
    coordinate you like from the source set. An implicit loop
    will be used around your formula so if you say:
\begin{verbatim}
x = x - 4966.5
\end{verbatim}
    you will shift all points of your set 4966.5 units to the left.
    \\
    You can use more than one set in the same formula, like this:
\begin{verbatim}
y = y - 0.653 * sin (x deg) + s2.y
\end{verbatim}
    which means you use both X and Y from the source set but also
    the Y coordinate of set 2. Beware that the loop is a simple
    loop over the indices, all the sets you use in such an hybrid
    expression should therefore have the same number of points
    and point i of one set should really be related to point i of
    the other set. If your sets do not follow these requirements,
    you should first homogenize them using
    \hyperlink{interp-popup}{interpolation} popup.
  \item[\texttt{Histograms}]~\\
    \index{Histograms}
    The \texttt{histograms} popup allows you to compute either standard
    or cumulative histograms from the Y coordinates of
    your data. Optionally, the histograms can be normalized to 1 (hence
    producing a PDF (Probability Distribution Function).
    \\
    The bins can be either a linear mesh defined by its min, max, and
    length values, or a mesh formed by abscissas of another set (in which
    case abscissas of the set must form a strictly monotonic array).
  \item[\texttt{Fourier transformation}]~\\
    \index{Fourier}
    The Fourier transform window is now inspired by \gsix with some
    changes:\\
    try \texttt{Examples \ggtk/Fourier} and look at section
    \ref{secFourier}  for details.\\
    The main novelty is that you can take into account the translation
    needed by the FFT to get the true Fourier transform of the function
    and not the transform of the translated one.\\
    It should work with library \fftw-2 as well as  \fftw-3.
    Legacy code for FFT is not operational thus it is recommended
    to use FFTW to take the transform of lengthy sets.\\
    X is assumed to be equally spaced.\\
    You can filter
    the input data window through triangular, Hanning, Welch, Hamming,
    Blackman and Parzen filters.\\
    If you specify complex input data X is taken as the real part
    and Y as the imaginary part.
  \item[\texttt{Wavelet transformations}]~\\
    \index{Wavelet}
    Compute Daubechies, Haar and Bsplines 1D transforms for datasets
    with $2^n$ points. 
    More details are given in section \ref{secWavelet}.
  \item[\texttt{Running averages}]~\\
    \index{averages}
    The running average popup allows you to compute some values
    on a sliding window over your data. You choose both the value
    you need (average, median, minimum, maximum, standard
    deviation) and the length of the window and perform the
    operation. You can restrict the operation to the points
    belonging to (or outside of) a region.
  \item[\texttt{Differences/derivation}]~\\
    \index{derivation}
    The differences popup is used to compute approximations of
    the first derivative of a function with finite
    differences.
  \item[\texttt{Seasonal differences}]~\\
    \index{Seasonal differences}
    The seasonal differences popup is used to subtract data from
    a period to data of the preceding period (namely y{[}i] - y{[}i +
    period]). Beware that the period is entered in terms of index
    in the set and not in terms of abscissa!
  \item[\texttt{Integration}]~\\
    \index{Integration}
    The integration popup is used to compute the integral of a
    set using the rectangles rule and optionally to load it.
    The numerical value of the integral is shown in the text field
    after computation.
    Selecting "cumulative sum" in the choice item
    will create and load a new set with the integral and compute
    the end value, selecting "sum only" will only compute the end
    value.
  \item[\texttt{Interpolation/Splines}]~\\
    \hypertarget{interp-popup}{}
    \index{Interpolation}\index{Splines}\index{X-splines}
    This popup is used to interpolate a given set and if needed
    create a new one.\\
    Several methods are proposed.
    \begin{itemize}
    \item \texttt{linear} is a straight line interpolation,
    \item \texttt{cubic spline} is based the classical resolution of a
      tridiagonal system, producing often large oscillations,
    \item \texttt{Akima} is a more sophisticated one with less
      oscillations,
    \item \texttt{X-spline} and \texttt{XY-spline} are the
      sophisticated crossed splines interpolation / approximation methods
      described in \cite{xsplines}.
      The last one is already used by program \texttt{xfig}.
    \end{itemize}
    Except for \texttt{XY-spline},
    the user choose a sampling array that can be
    either a linear mesh defined by its min, max, and length values,
    or a mesh formed by abscissas of another set.
    Note that if the sampling mesh is not entirely within the source set
    $x$ bounds, evaluation at the points beyond the bounds will be performed
    using interpolation parameters from the first (or the last) segment
    of the source set, which can be considered as a primitive
    extrapolation.
    This behaviour can be disabled by checking the "Strict" option on the
    popup.\\
    Except for \texttt{linear} and \texttt{XY-spline}, the abscissas
    of the interpolated set must be \textit{monotonic}.\\
    The \texttt{XY-spline} method is a 2D interpolation where the
    number of points of the resulting set is fixed by the routine
    itself. The precision parameter $p$ may change the number of
    interpolating points.\\
    The shape of interleaved splines functions used by
    \texttt{X-spline} and \texttt{XY-spline}
    is controlled by the $s$ parameter ranging in $\in [-1,1]$.
    For negative values, the curve is constrained to cross the data
    points, thus an interpolation is made.
    Sometimes, this constraint does not allow to obtain curves smooth
    enough: in that case, it can be removed by using positive values,
    leading to an approximation of the curve.
    Details can be found in  \cite{xsplines}.\\
    The difference with the \texttt{spline} option in the
    \texttt{Line/connection} combo box in the \texttt{Set} right pane
    of the \texttt{Explorer} is that the latter creates only a temporary set
    when plotting the curve
    and display symbols only at the primitive points.
  \item[\texttt{Regression}]~\\
    \index{Regression}
    The regression popup can be used to fit a set against
    polynomials or some specific functions (y=A*x\^{}B,
    y=A*exp(B*x), y=A+B*ln(x) and y=1/(A+Bx)) for which a simple
    transformation of input data can be used to apply linear
    regression formulas.\\
    You can load either the fitted values, the residuals or the
    function itself. Choosing to load fitted values or residuals
    leads to a set of the same length and abscissas as the
    initial set. Choosing to load the function is almost similar
    to load the fitted values except that you choose yourself the
    boundaries and the number of points. This can be used for
    example to draw the curve outside of the data sample range or
    to produce an evenly spaced set from an irregular one.
  \item[\texttt{Non-linear fit}]~\\
    \hypertarget{nonlfit}{}
    \index{Non-linear fit}\index{fitting curve}
    The \texttt{Non-linear curve fitting} popup allows to fit a set
    against your own formula by use of the
    Levenberg-Marquardt algorithm\footnote{ See
    \url{http://en.wikipedia.org/wiki/Levenberg-Marquardt_algorithm}.\\
    Actually, the program use a C translation of \texttt{lmdif
      subroutine}.
    See \url{http://www.netlib.org/minpack/}
  }
    \\
    With this popup you provide yourself a formula
    (e.g. \verb-y = a0 * cos(a1 * x + a2))-)
    where \texttt{a0, a1, ..., a9} are up to 10 unknowns to be
    computed.\\
    You specify a tolerance, starting values and
    optional bounds and run several steps before ending in the
    display of results in the console window and the plot of the final
    curve.\\
    The fit characteristics (number of parameters, formula, ...)
    can be saved in a file and retrieved as needed using the file
    menu of the popup.\\
    In the \texttt{Advanced} tab, you can additionally apply a
    restriction to the set(s) to be fitted (thus ignoring points not
    satisfying the criteria), use one of preset weighting schemes or
    define your own\footnote{Notice
      that "\texttt{dY}" in the preset "\texttt{1/dY\^{}2}" one
      actually refers to the third column of the data set; use the "Custom"
      function if this doesn't make sense for your data set.}, and choose
    whether to load the fitted values, the residuals or the function
    itself. Choosing to load fitted values or residuals leads to a set of
    the same length and abscissas as the initial set. Choosing to load the
    function is almost similar to load the fitted values except that you
    choose yourself the boundaries and the number of points. This can be
    used for example to draw the curve outside of the data sample range or
    to produce an evenly spaced set from an irregular
    one.\\
    \emph{N.B. The} \texttt{Tolerance} \emph{parameter is used to
      check the residuals between two iteration steps, i.e. the
      iteration stops when it is stabilised and this does not mean
      that the distance between the fit and the data has the}
    \texttt{tol} \emph{value}.
    \\
    The library of functions  proposed by Nicola Ferralis
    is incorporated in \ggtk and accessed via the "\texttt{Library}"
    menu. It gives a set of predefined functions and allows to choose
    the values of some starting parameters (peak position\dots)
    simply with the mouse.\\
    Try \verb+Examples/GraceGTK/NL fit+.\\
    See section \ref{nl-fit-library} for a detailed list of the
    functions available.\\
    \emph{N.B. This has been programmed and written in a <<blind>> manner and
      needs some checking and testing.}
  \item[\texttt{Correlation/covariance}]~\\
    \index{Correlation}\index{Covariance}
    This popup can be used to compute autocorrelation
    of one set or cross correlation between two sets. You only
    select the set (or sets) and specify the maximum lag. A check
    box allows one to evaluate covariance instead of correlation.
    The result is normalized so that $abs(C(0)) = 1$.
  \item[\texttt{Digital filter }]~\\
    \index{Filter}
    You can use a set as a weight to filter another set. Only the
    Y part and the length of the weighting set are important, the
    X part is ignored.
  \item[\texttt{Linear convolution }]~\\
    \index{Convolution}
    The convolution popup is used to ... convolve two sets. You
    only select the sets and apply.
  \item[\texttt{Geometric transforms}]~\\
    \index{Geometric transforms}
    You can rotate, scale or translate sets using the geometric
    transformations popup. You specify the characteristics of
    each transform and the application order.
  \item[\texttt{Sample points}]~\\
    \index{Sampling}
    This popup provides two sampling methods. The first one is
    to choose a starting point and a step, the second one is to
    select only the points that satisfy a boolean expression you
    specify.
  \item[\texttt{Prune data}]~\\
    \index{Prune!data}
    This popup is devoted to reducing huge sets (and then saving
    both computation time and disk space).\\
    The interpolation method can be applied only to ordered sets:
    it is based on the assumption that if a real point and an
    interpolation based on neighboring points are closer than a
    specified threshold, then the point is redundant and can be
    eliminated.\\
    The geometric methods (circle, ellipse, rectangle) can be
    applied to any set, they test each point in turn and keep
    only those that are not in the neighborhood of previous
    points.
  \end{description}
\item[\texttt{Feature extraction}]~\\
  \index{Extraction of features}
  Given a set of curves in a graph, extract a feature from each
  curve and use the values of the feature to provide the Y values
  for a new curve (see table \ref{extract-features}).
\begin{table}[htbp]
    \begin{center}
      \begin{tabular}{||l|p{10cm}||} \hline \hline
        Feature       &  Description \\ \hline \hline
        Y minimum     &  Minimum Y value of set \\
        Y maximum     &  Maximum Y value of set \\
        Y average     &  Average Y value of set \\
        Y std. dev.   &  Standard deviation of Y values \\
        Y median      &  Median Y value \\  \hline
        X minimum     &  Minimum X value of set \\
        X maximum     &  Maximum X value of set \\
        X average     &  Average X value of set \\
        X std. dev.   &  Standard deviation of X values \\
        X median      &  Median X value \\  \hline
        Frequency     &  Perform DFT (or FFT) to find largest frequency component \\
        Period        &  Inverse of above \\  \hline
        Zero crossing &  Time of the first zero crossing, + or - going \\  \hline
        Rise time     &  Assume curve starts at the minimum and rises to the maximum, get time to go from 10\% to 90\% of rise. For single exponential curves, this is 2.2*time constant \\  \hline
        Fall time     &  Assume curve starts at the maximum and drops to the minimum, get time to go from 90\% to 10\% of fall \\  \hline
        Slope         &  Perform linear regression to obtain slope \\
        Y intercept   &  Perform linear regression to obtain Y-intercept \\  \hline
        Set length    &  Number of data points in set \\  \hline
        Half maximal width &  Assume curve starts from the minimum, rises to the maximum and drops to the minimum again.
                               Determine the time for which the curve is elevated more than 50\% of the maximum rise. \\  \hline
        Barycenter X  &  Barycenter along X axis \\
        Barycenter Y  &  Barycenter along Y axis \\  \hline
        X (Y max)     &  X of Maximum Y \\
        Y (X max)     &  Y of Maximum X \\  \hline
        integral      &  cumulative sum \\  \hline
        \hline
      \end{tabular}
    \end{center}
    \caption{Extractable features}
    \label{extract-features}
  \end{table}
\item[\texttt{Import/ASCII}]~\\
  Is here for backward compatibility with \grace.
  See  \hyperlink{import-ascii}{\texttt{Import ASCII}} dialog.
\item[\texttt{Export/ASCII}]~\\
  Is here for backward compatibility with \grace.
  See  \hyperlink{export-ascii}{\texttt{Export ASCII}} dialog.
\end{description}
%%
\subsubsection{Plot menu}
\index{Menus!Plot}
This menu is present  for backward compatibility with \grace
but is not updated when \ggtk is changed, thus
the new features  are not available and the synchronisation with the
\texttt{Explorer} can fails.
In brief, its usage is discouraged and it is deactivated by default.
Use the Menubar/View menu to activate it.\\
Refer to \grace documentation for a detailed account on the Plot submenus.
%%
\subsubsection{View menu}
\index{Menus!View}
\begin{description}
\item[\texttt{Page zoom +, Page zoom -,Page zoom reset}]~\\
  Change the scaling of the page displayed on the screen.
  The page size of the printed output must be checked in the
  \hyperlink{print-setup}{\texttt{Print setup}} window.
\item[\texttt{Show locator bar, Show status bar, Show tool bar}]~\\
  Toggle the display of the corresponding elements.
\item[\texttt{Page setup}]~\\
  More general than the \texttt{Explorer/Project/Page} tab,
  this popup is the same as the
  \hyperlink{print-setup}{\texttt{Print setup}} window.
\item[\texttt{Redraw}]~\\
  This menu item triggers a redrawing of the canvas.
\item[\texttt{White  background}]~\\
  is the default setting for the screen.
\item[\texttt{Black  background}]~\\
  Sets the screen background to be black as the \texttt{-rvideo}
  command option do, but does not change the output in a file or a
  printer.
\item[\texttt{Update all}]~\\
Usually, everything in the GUI is updated automatically, but if this fails,
you can update it manually.
\emph{Note: this command is not up-to-date}.
\end{description}
%%
\subsubsection{Window menu}
\index{Menus!Window}
\begin{description}
\item[\texttt{Commands}]~\\
  \hypertarget{command-window}{}
  This window allows to execute directly \textit{commands}
  in \ggtk language.
  See section \ref{Commandinterpreter} for details on the \ggtk
  \texttt{.agr} language.\\
  The "\texttt{Follow me}" mode can be selected with the check button
  at the bottom of the window: it is a help to write your own
  scripts.
  The commands corresponding to changes made in right pane menus are 
  printed in the window when this option is selected\footnote{Beware
    that it is not sure that all changes are taken into account.}.\\
  You can edit lines into this window.
  Clicking the \texttt{Apply} or \texttt{Accept} buttons execute the
  lines selected with the mouse.\\
  All the command lines must begin with a \texttt{@}.\\
  You can read in files and save the content of
  the window with the "\texttt{File}" menu at the top of the command
  window.
\item[\texttt{Font tool}]~\\
  It is a tool to help writing strings with escape sequences and non
  ASCII characters. See details in section \ref{fonttool}.
\item[\texttt{Console}]~\\
  The console window displays errors and results of some numerical
  operations, e.g. nonlinear fit.\\
  The window is popped up automatically whenever an error occurs
  or new result messages appear. This can be altered by checking the
  "\texttt{Options/Popup only on errors}" option.
\end{description}
%%
\subsubsection{Help menu}
\index{Menus!Help}
Try it.\\
If the menu does not work correctly (a bad installation),
you can access directly to the files
(manual, FAQ, \dots) in the \texttt{doc} directory
(in a standard installation, \texttt{/usr/local/gracegtk/doc}).\\
Try the \texttt{Examples}, it is a very good way to get an idea of
\ggtk possibilities. The files are in the \texttt{examples} directory.
%% ............................
\subsection{Explorer window}
\label{secExplorerWindow}
\index{Menus!Explorer}
\index{Explorer}
%% ............................
It is displayed when the \texttt{TreeView} button is clicked
in the toolbar or with the \verb+Edit/Explorer+ menu in the menubar.
It shows a left pane, a right pane and two buttons at the bottom.
\subsubsection{Left pane}
\index{Explorer!Left pane}
The first column gives a tree view of the drawing components.
Visible components are in \textbf{bold normal} and hidden in
\textit{light italic}.
\\
The second column of the TreeView displays a \texttt{label} (see below).
\\
Clicking \emph{one } tree element in the tree with the mouse
\texttt{Button1} (usually the left button)
shows the corresponding menu in the right pane, and the \texttt{Apply}
button at the bottom allows to apply the values to the selected
element\footnote{Note that if more than one element is selected, the
  \texttt{apply} button is inactived.}.
\\
The \texttt{ Label} column  is  editable:
\index{Mouse!double-click}
double-click on the item to edit it and press the \textit{enter key}
to record the change.
\begin{itemize}
\item For graphs, axis, sets and string this allows to edit graph title,
  axis label, set legend or the string itself.
\item For  arcs, lines, boxes and compounds the label is just informative.
\item For time stamp, legend boxes and templates, editing the label is
  not relevant and it will return to its initial state when you press
  the enter key.
\end{itemize}
If you need special characters or special formatting in your
label, you can use the \texttt{font tool} (see section \ref{fonttool}).
%% ............................
\subsubsection{Arcs, boxes,  circles, lines, polylines and strings}
\index{Arc}\index{Box}\index{Line}\index{Polyline}
\index{Ellipse}\index{String}
These geometric objects can be created by using the \textit{template}
entries in the \texttt{TreeView} and clicking the
"\texttt{Create \& place with mouse}" button.
They are always created in the tree as child of the template
and in viewport coordinates.
By editing them, it is possible to attach to a given graph\footnote{
Note that polylines are not intended as a replacement of  XY sets and
should have a moderate number of points.
}
 and in that case to define them in world coordinates.
%% ............................
\subsubsection{Right pane menus}
\index{Explorer!Right pane}
Up to now, these menus are copied from \grace with few changes, but it can be
changed in future versions.
If the "instant update" feature is on (the default), most of the
changes are immediately taken into account; if it not the case,
you must click on the bottom \texttt{ Apply} button to make your
changes effective. 
The \texttt{ Close} button hide the explorer window with no change; if no  item
selection is made during the interval,
rising again the explorer with the \texttt{ TreeView} button will show the window
in the state it had when  you hide it.\\
Beware that the synchronisation of selections between the TreeView and
the canvas is a touchy business  
and that \ggtk may sometimes behave not as you expected in this
matter.\\ 
Thus, if it seems that the right pane menu does not work check that
in the TreeView
\begin{enumerate}
\item the desired item is actually selected,
\item only one item is selected.
\end{enumerate}
\begin{description}
\item[\texttt{Project}]
  menus allows to choose page format and color background,
  to scatter several graphs on the page, add sets defined by a given
  formula in various graphs.
  The \texttt{ Apply}
  button does not behave here like for the other menus.
  \begin{itemize}
  \item The \texttt{Page} tab  is applied each time the
    \texttt{Apply} button is clicked.
  \item The \texttt{ Layout} tab is applied only if the tab is the
    visible tab.
    For a detailed description of this notebook page, see
    "\texttt{Arrange graphs...}"
    section \ref{arrange-graphs}.
  \item Specialized buttons are placed in other tabs to make an action.
  \end{itemize}
\item[\texttt{TimeStamp}]
  menu is used to control the appearance of
  the time stamp and set the \ggtk configuration for dates
\item[\texttt{Graph}]
  main tab includes the properties you will need more
  often (title for example), and other tabs are used to fine tune some
  less frequently used options (fonts, sizes, colors, placements).
  The \texttt{sets} tab allows actions on several sets belonging to
  the same graph.
\item[\texttt{Axis}]
\index{Axis} menu make possible to display a second or
  \textit{alternate axis} in 
  addition to the normal one, using
  the \texttt{choose}  combo box at the top of the menu.
  As long as this axis is marked hidden, it is not displayed in the
  TreeView, thus you have to uncheck the hide button in the bottom of
  the right pane menu to make it appearing in the left pane.\\
  The start and stop fields depict the displayed range.\\
  Five types of scales are available: 
  \texttt{linear, logarithmic,  reciprocal, logit and degrees} 
  (for polar graph only).
  and you can invert the axis direction (which normally
  increases from left to right and from bottom to top).\\
  The main tab includes the
  properties you will need more often (axis label, tick
  spacing and format for example), and other tabs are used to fine
  tune some less frequently used options (fonts, sizes, colors,
  placements, stagger, grid lines, special ticks, ...).\\
  \texttt{Special} tab allows to choose individual positions and
  labels for ticks.
  The default is \texttt{None}, i.e. are defined in the \texttt{Main}
  and \texttt{Tick marks} tabs.
  If you change the settings, the list is populated by the default
  list i.e.  major and minor ticks are displayed.\\
  The \texttt{Nb} spin box allows to choose the number of ticks to
  use and you can change positions and labels of ticks, then
  \texttt{Apply} to finalise your choice.\\
  Beware that returning to \texttt{None} will destroy the present list
  and return to the default one.\\
  It is possible to use an algebraic expression for the location and
  specials for strings  label, e.g. to display a tick at
  location $3\pi/2 $ and display the label:
  \begin{center}
    \verb+ 3*pi/2+ and \verb+ 3\f{Symbol}p/2+    
  \end{center}
\item[\texttt{Set}]
  menu is used to control set appearance and add
  or delete points with the mouse.
  The tabs displayed vary with the type of the set.\\
  The \texttt{Line} tab allows various types of connection for data
  points, including spline interpolation.
  For spline interpolation a temporary set is created at drawing time
  and immediately killed after drawing is done.
  If you want to create a permanent  interpolating set use
  \texttt{Data/transformation} menu.\\
  More details about spline interpolation are given in
   \hyperlink{interp-popup}{Interpolation/Splines} section
   about data transformation.
\item[\texttt{Leg.Box}]
  allows to display the \textit{legend} of
  sets i.e the line type and symbol used as well as a comment.
\item[\texttt{Line, Arc, String and Box}]
  templates are used to
  create new objects, attached directly to  the page
  (by choosing -1 as graph number)
  or  to a given graph.
  In the latest case, it is possible to choose between viewport
  coordinates and graph coordinates. The difference appears when you
  move or rescale the graph. Also, automatic scaling take into
  account object in world coordinates and not in viewport coordinates.
\end{description}
The examples can be a good help to have a better understanding of the
detailed behaviour of the program.
%% ............................
\subsection{Using layers}
\index{Layers}
When all the drawing is made on the same layer, the right hand column
of check boxes used to toggled layers visibility is not displayed and
this layer is putted automatically visible.\\
If you want to display an object in front of another, use the spin
boxes in the Explorer right pane menus to attach it to a upper
layer.\\
Objects glued into a \textit{compound} can be attached to different
layers, thus compounds does not have a given depth, but the
\textit{Collapse} button allows to put all its objects on the same
layer.\\
It is the same for \textit{graphs}.
Note that \textit{graph frame, title} and \textit{subtitle} can be
drawn on different layers.
%% ............................
\subsection{Some hints}
\subsubsection{Polar graphs}
\label{polarhint}
\index{Graphs!polar type}\index{Polar graph}
The interface for polar type is not well polished.
\begin{itemize}
\item
  The X-axis is in fact the angle axis and the Y-axis the modulus one.
\item
  For the angle (or phi) axis,
  \begin{itemize}
  \item
    \textit{scale}=\texttt{linear} display tick labels in radians
    and the x-autoticking choose rounded values in radians,
  \item
    \textit{scale}=\texttt{degrees} display tick labels in degrees
    and the x-autoticking choose rounded values as 30$^\circ$ multiples.
  \end{itemize}

\end{itemize}
\subsubsection{Set types}
Beware that changing the type of sets can produce a loss of data: if
the new set use less data columns than the old one,
and the data had not been imported with the \texttt{block data} popup,
the columns in excess are lost.
In both cases, you are warned by a message  and asked to proceed if in the
interactive mode.
%%%
%% ............................
\section{Behavior different from \grace}
%% ............................
Some differences with \grace.
%%
\subsection{Arcs}
\index{Arc}\index{Compound}\index{xfig}
\grace users already know the \texttt{line, box, string} and
\texttt{ellipse} objects.
In \ggtk, the \texttt{ellipse} type is replaced by the more general
\texttt{arc} object, i.e. an arc of ellipse with possibly arrows at its
ends.
\subsection{Compounds}
\label{secCompounds}
\index{Compound}
The new \texttt{compound} type is similar to compounds in
\texttt{xfig}: several geometric objects can be glued together and
 selected, hide or shown as well as moved as a single block.\\
No direct scaling of the block is available.\\
To access one component of the compound, select it alone in the
TreeView.\\  
Two methods are possible to manage compounds.
\begin{itemize}
\item 
  Using mouse in the canvas. 
  If you click buttons in the canvas left toolbar, as for other
  objects, 
  any of the eligible objects are selectable.
  If you click buttons in the Explorer right pane, only the item
  selected in the tree is selectable.
\item 
  Use TreeView and mouse button 3 for following actions.
\index{Mouse!button 3}
  \begin{itemize}
  \item 
    \texttt{Create a new compound and glue} can be used with several
    items selected. All the items must be geometric, attached on the
    same level to the same graph (or to templates), with the same
    loctyp. Thus, if you want to create new objects and glue them into
    a compound belonging to a graph, create them with the template(s),
    change attachment, if needed change  loctyp 
    and finally select and glue them.
  \item 
    \texttt{Break compound}: obvious.
  \item 
    \index{Compound!prune}\index{Prune!object}
    \texttt{Prune} works only when one item is selected.
    The result is to use templates nodes as a sort of clipboard:
    object is moved into a template branch,
    the compound shift is added to its coordinates and
    the loctyp is set as coord. view.
  \item 
    \index{Compound!insert}\index{Insert into a compound}
    \texttt{Insert into a compound} is the inverse of \texttt{Prune}:
    you are asked to choose an existing  compound then, the object is
    moved into it and parameters are set according to the compound
    ones. 
  \end{itemize}
\end{itemize}
\subsection{Comments and legends}
\index{Comments}\index{Legend}
In \grace, the nature of new sets is automatically described in the
comment string,  not in the legend displayed in the graph: you have, attached to the
    same graph (or to the templates
to load comments as legends to see them. In \ggtk this is done
automatically by default, but you can disable this feature in the
Edit/Preference menu.
%% ............................
\subsection{Command window}
This window is now directly editable and only selected lines are
executed when the \texttt{Apply} or \texttt{Accept}
buttons are clicked.\\
All the command lines must begin with a \texttt{@}.\\
A "\texttt{Follow me}" mode had been added: see 
\hyperlink{command-window}{\texttt{Commands} in  Window menu}.
%% ............................
\subsection{Font tool}
\label{fonttool}
\index{Fonts!Font tool}
\index{Colors!Font tool}
\index{superscript!Font tool}
\index{underscript!Font tool}
\index{escape sequences!Font tool}
It is a tool to help writing strings with Grace escape sequences and
non ASCII characters that will be displayed onto the canvas with a
pretty printing.\\
Normally, it is fired clicking mouse button 3 into
the entries where it usage makes sense.
More often, if instant update is on, clicking the \texttt{Apply}
button into the Font tool windows will be enough to take into account
the changes, except for the \texttt{Special} tab in \texttt{Set} menu,
where this will change only the Label entry and it is necessary to
click also the \texttt{Apply} button of the Explorer.\\
When the Font tool is called by the 
\texttt{Menubar/Window/Font tool}
menu entry, it is displayed into it precedent state, i.e. if a
previous connection to an entry exists, it remains active.
\subsection{Non-linear fit}
\label{nl-fit-library}
\index{Non-linear fit}\index{fitting curve}
The library of functions  proposed by Nicola Ferralis for the non
linear popup is incorporated in \ggtk and accessed via the "Library"
menu.\\
\textit{N.B. This has been programmed and written in a <<blind>> manner and
needs some checking and testing.}
\subsubsection{Gaussian Functions}
\index{Non-linear fit!Gaussian}
\begin{description}
\item[Gaussian simple]
\index{Non-linear fit!Gaussian}\index{Gauss}
  %%% $ y = A0 + (A3*2*sqrt(ln(2)/pi)/A2)*exp(-4*ln(2)*((x-A1)/A2)^2)$
  \begin{displaymath}
    y \: = \: A_0 + \frac{A_3}{A_2} \: 2 \sqrt{\frac{\ln(2)}{\pi}} \:
    \: e^{-4\ln(2) \left(\frac{x-A_1}{A_2}\right)^2}
    \qquad \mbox{where}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak,
  \item $A_2$: Full width at half maximum,
  \item $A_3$: Peak area.
  \end{itemize}
  The center and initial amplitude of the peak can be set from
  user input (via mouse coordinates).
  %%
  \vspace{3mm}
\item[Gaussian Function (Chromatography)]
  %%% y = A0 + (1/sqrt(2*pi))*(A3/A2)*exp(-(x-A1)^2/2*A2^2)
  %%% y = A0 + (1/sqrt(2*pi))*(A3/A2)*exp(-(x-A1)^2/2/A2^2) <<<<<<<< correction
  \begin{displaymath}
    y \: = \: A_0 + \frac{1}{\sqrt{2\pi}} \: \frac{A_3}{A_2}  \:
    \: e^{- \frac{1}{2} \: \left(\frac{x-A_1}{A_2}\right)^2}
    \qquad \mbox{where}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak (retention time),
  \item $A_2$: Standard deviation of the peak,
  \item $A_3$: Peak area.
  \end{itemize}
  The center and initial amplitude of the peak can be set from
  user input (via mouse coordinates).
  %%
  \vspace{3mm}
\item[Gaussian double]
\index{Non-linear fit!Gaussian}
  %%% y = A0 + (A3*2*sqrt(ln(2)/pi)/A2)*exp(-4*ln(2)*((x-A1)/A2)^2) + (A6*2*sqrt(ln(2)/pi)/A5)*exp(-4*ln(2)*((x-A4)/A5)^2)
  \begin{displaymath}
    y \: = \: A_0 +  \: 2 \sqrt{\frac{\ln(2)}{\pi}} \: \left(
      \frac{A_3}{A_2} \: e^{-4\ln(2) \left(\frac{x-A_1}{A_2}\right)^2}
      \: + \:
      \frac{A_6}{A_5} \: e^{-4\ln(2) \left(\frac{x-A_4}{A_5}\right)^2}
    \right)
    \qquad \mbox{where}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1, A_4$: Center of the peaks 1,2,
  \item $A_2, A_5$: Full width at half maximum of peaks 1, 2,
  \item $A_3, A_6$: Area of peaks 1, 2.
  \end{itemize}
  %%
  \vspace{3mm}
\item[Gaussian triple]
\index{Non-linear fit!Gaussian}
  %%% ,"y = A0 + (A3*2*sqrt(ln(2)/pi)/A2)*exp(-4*ln(2)*((x-A1)/A2)^2) + (A6*2*sqrt(ln(2)/pi)/A5)*exp(-4*ln(2)*((x-A4)/A5)^2)+ (A9*2*sqrt(ln(2)/pi)/A8)*exp(-4*ln(2)*((x-A7)/A8)^2)"
  \begin{displaymath}
    y \: = \: A_0 +  \: 2 \sqrt{\frac{\ln(2)}{\pi}} \: \left(
      \frac{A_3}{A_2} \: e^{-4\ln(2) \left(\frac{x-A_1}{A_2}\right)^2}
      \: + \:
      \frac{A_6}{A_5} \: e^{-4\ln(2) \left(\frac{x-A_4}{A_5}\right)^2}
      \: + \:
      \frac{A_9}{A_8} \: e^{-4\ln(2) \left(\frac{x-A_7}{A_8}\right)^2}
    \right)
  \end{displaymath}
  %%
\end{description}
%%
\subsubsection{Lorentzian Functions}
\index{Non-linear fit!Lorentzian}\index{Lorentz}
\begin{description}
\item[Lorentzian simple]
  %%% ,"y = A0 + (2*A2*A3/pi)/(4*(x-A1)^2 + A2^2)"
  \begin{displaymath}
    y \: = \: A_0 + \frac{2}{\pi} \: \frac{A_2 A_3}{4(x-A_1)^2 + A_2^2}
    \qquad \mbox{where}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak,
  \item $A_2$: Full width at half maximum,
  \item $A_3$: Peak area.
  \end{itemize}
  %%
  \vspace{3mm}
\item[Lorentzian double]
  %%% y = A0 + (2*A2*A3/pi)/(4*(x-A1)^2 + A2^2) + (2*A5*A6/pi)/(4*(x-A4)^2 + A5^2)
  \begin{displaymath}
    y \: = \: A_0 + \frac{2}{\pi} \: \left(
              \frac{A_2 A_3}{4(x-A_1)^2 + A_2^2}
      \: + \: \frac{A_5 A_6}{4(x-A_4)^2 + A_5^2}
    \right)
  \end{displaymath}
  %%
  \vspace{3mm}
\item[Lorentzian triple]
  %%% y = A0 + (2*A2*A3/pi)/(4*(x-A1)^2 + A2^2) + (2*A5*A6/pi)/(4*(x-A4)^2 + A5^2) + (2*A8*A9/pi)/(4*(x-A7)^2 + A8^2)
  \begin{displaymath}
    y \: = \: A_0 + \frac{2}{\pi} \: \left(
              \frac{A_2 A_3}{4(x-A_1)^2 + A_2^2}
      \: + \: \frac{A_5 A_6}{4(x-A_4)^2 + A_5^2}
      \: + \: \frac{A_8 A_9}{4(x-A_7)^2 + A_8^2}
    \right)
  \end{displaymath}
\end{description}
%%
\subsubsection{Peak Functions}
%%
\index{Non-linear fit!Peak Functions}
\begin{description}
  %%
\item[Pseudo Voigt 1]
  \index{Non-linear fit!Pseudo Voigt}\index{Voigt}
  %%% y = A0 + A3 * (A4*(2/pi)*A2/(4*(x-A1)^2+A2^2) + (1-A4)*exp(-4*ln(2)*(x-A1)^2/A2^2)*(sqrt(4*ln(2))/(A2*sqrt(pi))))
  \begin{displaymath}
    y \: = \: A_0 + A_3 \left[ \frac{2}{\pi} \: \frac{A_4  A_2}{4*(x-A_1)^2+A_2^2}
      \: + \: \sqrt{\frac{4\, \ln(2)}{\pi}}
      \: \frac{1-A_4}{A_2} \: e^{-4 \ln(2) \left(\frac{x-A_1}{A_2}\right)^2 }
    \right]
    \qquad \mbox{where}
  \end{displaymath}
  Gaussian and Lorentzian have the same width and
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak,
  \item $A_2$: Full width at half maximum,
  \item $A_3$: Amplitude,
  \item $A_4$: Profile shape factor.
  \end{itemize}
  %%
  \vspace{3mm}
\item[Pseudo Voigt 2]
  %%% y = A0 + A3 * (A5*(2/pi)*A2/(4*(x-A1)^2+A2^2) + (1-A5)*exp(-4*ln(2)*(x-A1)^2/A4^2)*(sqrt(4*ln(2))/(A2*sqrt(pi))))
  \begin{displaymath}
    y \: = \: A_0 + A_3 \left[ \frac{2}{\pi} \: \frac{A_5  A_2}{4*(x-A_1)^2+A_2^2}
      \: + \: \sqrt{\frac{4\, \ln(2)}{\pi}}
      \: \frac{1-A_5}{A_4} \: e^{-4 \ln(2) \left(\frac{x-A_1}{A_2}\right)^2 }
    \right]
    \qquad \mbox{where}
  \end{displaymath}
  Gaussian and Lorentzian have different widths.
  %%
  \vspace{3mm}
\item[Doniach-Sunjic]
  \index{Non-linear fit!Doniach-Sunjic}\index{Doniach-Sunjic}
  %%% y = A0 + A3*cos((pi*A4/2)+(1-A4)*atan((x-A1)/A2))/(A2^2+(x-A1)^2)^((1-A4)/2)
  \begin{displaymath}
    y \: = \: A_0 +  A_3 \cos\left[ \frac{\pi}{2} A_4
      \: + \: \frac{1-A_4}{ (A_2^2 + (x-A_1)^2)^{(1-A_4)/2} }
      \:       \arctan \left(\frac{x-A_1}{A_2}\right)
    \right]
    \qquad \mbox{where}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak,
  \item $A_2$: Full width at half maximum,
  \item $A_3$: Peak area,
  \item $A_4$: Asymmetry parameter.
  \end{itemize}
  %%
  \vspace{3mm}
\item[Asymmetric double sigmoidal function]
  \index{Non-linear fit!Asymmetric double sigmoidal function}\index{sigmoidal}
  %%% y = A0 + A3*(1/(1+exp(-(x-A1+A2/2)/A4)))*(1-(1/(1+exp(-(x-A1-A2/2)/A5))))
  \begin{displaymath}
    y \: = \: A_0 + A_3
    \,        \frac{1}{1+e^{-\frac{x-A_1+ \frac{1}{2} A_2}{A_4}}} \:
    \left[1 - \frac{1}{1+e^{-\frac{x-A_1- \frac{1}{2} A_2}{A_5}}} \right]
    \qquad \mbox{where}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak,
  \item $A_2$: Width 1,
  \item $A_3$: Amplitude,
  \item $A_4$: Width 2.
  \item $A_5$: Width 3.
  \end{itemize}
  %%
  \vspace{3mm}
\item[Log Normal Function]
  \index{Non-linear fit!Log Normal Function}\index{Log Normal}
  %%% y = A0 + A3*exp(-((ln(x)-ln(A1))^2)/(2*A2))
  \begin{displaymath}
    y \: = \: A_0 + A_3\, e^{-\frac{(\ln x - \ln A_1)^2}{2 A_2}}
    \qquad \mbox{where}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak,
  \item $A_2$: Width,
  \item $A_3$: Amplitude.
  \end{itemize}
  %%
  \vspace{3mm}
\item[Gram-Charlier A-Series]
  \index{Non-linear fit!Gram-Charlier}\index{Gram-Charlier}
  %%% y = A0 + A3/(A2*sqrt(2*pi))*exp(-0.5*((x-A1)/A2)^2)*(1+(A4/6)*(((x-A1)/A2)^3-3*(x-A1)/A2)+(A5/24)*(((x-A1)/A2)^4-6*((x-A1)/A2)^3+3))
  %%% y = A0 + A3/(A2*sqrt(2*pi))*exp(-0.5*          X^2)*(1+(A4/6)*(          X^3-3*        X)+(A5/24)*(          X^4-6*          X^3+3))
  \begin{displaymath}
    y \: = \: A_0 + \frac{ A_3}{A_2 \sqrt{2 \pi}}
    \:               \left[1 + \frac{A_4}{6}  \: (X^3 - 3 X) \: + \frac{A_5}{24} (X^4 - 6X^3 + 3)  \right]
    \:              e^{-\frac{1}{2} X^2}
    \qquad \mbox{ where }  X = \frac{x-A_1}{A_2}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak,
  \item $A_2$: Standard deviation,
  \item $A_3$: Peak Area,
  \item $A_4$: Skew,
  \item $A_5$: Excess.
  \end{itemize}
  %%
  \vspace{3mm}
\item[Edgeworth-Cramer Series]
  \index{Non-linear fit!Edgeworth-Cramer}\index{Edgeworth-Cramer}
  %%% y = A0 + A3/(A2*sqrt(2*pi))*exp(-0.5*((x-A1)/A2)^2)*(1+(A4/6)*(((x-A1)/A2)^3-3*(x-A1)/A2)+(A5/24)*(((x-A1)/A2)^4-6*((x-A1)/A2)^3+3) + (A5^2/720)*(((x-A1)/A2)^6-15*((x-A1)/A2)^4+45*((x-A1)/A2)^2-15))"
  %%% y = A0 + A3/(A2*sqrt(2*pi))*exp(-0.5*          X^2)*(1+(A4/6)*(          X^3-3*        X)+(A5/24)*(          X^4-6*          X^3+3) + (A5^2/720)*(          X^6-15*          X^4+45*          X^2-15))"
  \begin{displaymath}
    y \: =  A_0 +   \frac{A_3}{A_2\sqrt{2\pi}}
    \left[ 1 + \frac{A_4}{6} ( X^3 - 3X)
      + \frac{A_5}{24} (X^4 - 6X^3 + 3)
      + \frac{A_5^2}{720} ( X^6 - 15X^4 + 45X^2 - 15)
    \right]  \: e^{-\frac{1}{2} X^2}
  \end{displaymath}
  where
  \begin{displaymath}
    X = \frac{x-A_1}{A_2}
  \end{displaymath}
  and parameters as for Gram-Charlier A-Series.
  %%
  \vspace{3mm}
\item[Inverse Polynomial Function]
  %%% y = A0 + A3/(1+ A4*(2*(x-A1)/A2)^2 + A5*(2*(x-A1)/A2)^4 + A6*(2*(x-A1)/A2)^6)
  %%% y = A0 + A3/(1+ A4*            X^2 + A5*            X^4 + A6*            X^6)
  \begin{displaymath}
    y \: =  A_0 +   \frac{A_3}{1 +  A_4 X^2 + A_5 X^4 + A_6 X^6}
    \qquad \mbox{where } X = 2 \: \frac{x-A_1}{A_2}
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center of the peak,
  \item $A_2$: Standard deviation,
  \item $A_3$: Peak Area,
  \item $A_4, A_5, A_6$: Parameters.
  \end{itemize}
\end{description}
%%
\subsubsection{Periodic Peak Functions}
  \index{Non-linear fit!Periodic}
\begin{description}
\item[Sine Function]
  \index{Non-linear fit!Periodic}
  %%% y = A0 + A3*sin(pi*(x-A1)/A2)
  \begin{displaymath}
    y \: = \: A_0 + A_3  \; \sin \left(\pi \frac{x-A_1}{A_2} \right)
  \end{displaymath}
  \begin{itemize}
  \item $A_0$: Baseline offset,
  \item $A_1$: Center,
  \item $A_2$: Width,
  \item $A_3$: Amplitude,
  \item $A_4, A_5, A_6$: Parameters.
  \end{itemize}
  %%
\item[Sine Square Function]
  \index{Non-linear fit!Periodic}
  %%% y = A0 + A3*sin(pi*(x-A1)/A2)^2
  \begin{displaymath}
    y \: =  A_0 + A_3  \: \sin^2 \left(\pi \frac{x-A_1}{A_2} \right)
  \end{displaymath}
  and parameters as for Sine Function.
  %%
\item[Sine Damp Function]
  \index{Non-linear fit!Periodic}
  %%% y = A0 + A3*exp(-x/A4)*sin(pi*(x-A1)/A2)
  \begin{displaymath}
    y \: = \: A_0 + A_3  \: \sin\left(\pi \frac{x-A_1}{A_2} \right) \: e^{-x/A_4}
  \end{displaymath}
  and parameters as for Sine Function.
  %%
\end{description}
%%
\subsubsection{Baseline Functions}
  \index{Non-linear fit!Baseline}
\begin{description}
  %%
\item[Exponential Decay 1]
  %%% y = A0 + A3*exp(-(x-A1)/A2)
  \begin{displaymath}
    y \: =\:  A_0 + A_3 \: e^{- \frac{x-A_1}{A_2}}
  \end{displaymath}
  %%
\item[Exponential Decay 2]
  %%% y = A0 + A3*exp(-(x-A1)/A2)+A6*exp(-(x-A4)/A5)
  \begin{displaymath}
    y \: =\:  A_0 + A_3 \: e^{- \frac{x-A_1}{A_2}} + A_6 \: e^{- \frac{x-A_4}{A_5}}
  \end{displaymath}
  %%
\item[Exponential Growth 1]
  %%% y = A0 + A3*exp(-(x-A1)/A2)
  \begin{displaymath}
    y \: =\:  A_0 + A_3 \: e^{ \frac{x-A_1}{A_2}}
  \end{displaymath}
  %%
\item[Exponential Growth 2]
  %%% y = A0 + A3*exp(-(x-A1)/A2)+A6*exp(-(x-A4)/A5)
  \begin{displaymath}
    y \: = \: A_0 + A_3 \: e^{ \frac{x-A_1}{A_2}} + A_6 \: e^{ \frac{x-A_4}{A_5}}
  \end{displaymath}
  %%
\item[Hyperbolic]
  %%% y = A0 + (A1*x)/(A2+x)
  \begin{displaymath}
    y \: = \: A_0 + \frac{A_1 \, x}{A_2 + x}
  \end{displaymath}
  %%
\item[Bradley]
\index{Bradley}
  %%% y = A0  * ln(-A1*ln(x))
  \begin{displaymath}
    y \: = \: A_0 \:  \ln(-A_1 \:\ln x)
  \end{displaymath}
  %%
\item[Logarithm 3 Parameters]
  %%% y = A0  - A1*ln(x+A2)"
  \begin{displaymath}
    y \: = \:  A_0 - A_1 \ln(x + A_2)
  \end{displaymath}
  %%
\item[Weibull Probability Density]
\index{Weibull}
  %%% y = (A0/A1) * ((x/A1)^(A0-1)) * exp(-(x/A1)^A0)
  \begin{displaymath}
    y \: =  \: \frac{A_0}{A_1}
    \:         \left(\frac{x}{A_1} \right)^{(A_0-1)}
    \:          e^{-(x/A_1)^{A_0}}
  \end{displaymath}
  %%
\item[Weibull Cumulative Distribution]
  %%% y = 1 - exp(-(x/A1)^A0)
  \begin{displaymath}
    y \: =  \: 1 - e^{-(x/A_1)^{A_0}}
  \end{displaymath}
  %%
\end{description}
%% ............................
\section{2D graphs}
\ggtk can draw vector and colours maps.
\subsection{Color map and contour sets}
\index{XYCMAP}
\index{Contour}
\ggtk can represent $z = f(x,y)$ if $x$ and $y$ values form a regular
rectangular grid in two ways:
\begin{itemize}
\item associate a color to each value of $z$, i.e. a colormap,
\item draw level curves.
\end{itemize}
The set must be defined as a \textit{XYCMAP} set and the contour line
option is possible only if a Fortran compiler had been detected and
used during the compilation of the program.
\index{Sets!XYCMAP}
\\
Note that you must supply two new parameters when the set is defined:
$nx$ and $ny$, the number of different values for $x$ and $y$.
\\
In the \texttt{Explorer}, the \texttt{Color map} tab shows a
\texttt{Contour line} frame: by default, level curves are not
computed, i.e. the \texttt{Hide} check box is active.
To draw level curves, deactivate the box and click \texttt{Apply}.
The levels defined by the colorbar ticks are accessed by selecting the
\texttt{Colorbar} associated to the set.\\
It is possible to add labels on the level curves with the mouse by
clicking first the appropriate button in the Contour lines frame, then
clicking on the contour curve at the place chosen.
Beware that  contour lines and labels are not duplicated with the
other components of a set.\\
The computation of contour lines\footnote{It is made using algorithm
  toms 626 (www.netlib.org) proposed by A. Preusser.
} is based on a triangulation of the surface that can take some time,
thus we store the resulting mesh and try to avoid to recompute it.
If something goes wrong in refreshing the level curves, use the
\texttt{Kill} button to force a new computation.\\
More details about computation of contour lines can be found in
\cite{algo626}.

\textit{N.B.} only the Postscript \grace driver had been adapted
to deal with \texttt{XYCMAP} colours: use CAIRO drivers instead
for other formats.
%%%
%% ............................
\section{Undo and Redo}
\index{Undo}\index{Redo}
If you have compiled with the \texttt{libundo} library, it is possible to use
  the \texttt{Undo/Redo} buttons in the \texttt{Edit} menu.
  The method is inspired by the follow-me mode: each time a change in the
  parameters is detected, two command lines (using the grace .agr
  language) are recorded: one with the old values for the undo action,
  one with the new ones for the redo action.\\
  N.B.
  \begin{itemize}
  \item 
    This feature works only when two reciprocal commands exists and if the
    registering is programmed: e.g.
    data transformations and  killings are excluded.
  \item
    An attempt is made to discard intermediate values when the
    parameters are varied at high frequency by using spin buttons
    arrows, but, the delay to start repetition makes that  several
    ``undo'' are anyway recorded recorded in that case.
  \end{itemize}
%% ............................
\section{Command interpreter}
\label{Commandinterpreter}
\index{Interpreter}\index{Commands}
%% ............................
Preferred extensions are \texttt{.agr} for command/data files and
\texttt{.dat} for data files.\\
The input stream is parsed in a line-by-line manner
i.e. an instruction cannot spread over several lines.\\
First, leading blanks and tabs as well as empty lines are discarded,
then, the first significant character is used to determine the type of
the line or change the mode:
\begin{itemize}
\item \verb+#+ means a comment line,
\item \verb+@+ means a command line,
\item \verb+!+ means a heading line for columns of data
  (see \hyperlink{import-ascii}{\texttt{Import ASCII data}}),
\item \verb+&+ is the mark for the end of a data sequence.
\item After that, the default is to try to parse the line as a data
  line, i.e. a list of numbers and quoted strings.
  If this later fails and the line is in the first ten, it is simply
  discarded. This behavior allows to read data files produced by other
  programs with non \ggtk standard headings.
\end{itemize}
The parsing of commands is case-insensitive.\\
In command lines, there
may be several statements per line, separated
by semicolon (\texttt{;}) and no \verb+@+ after the semicolon.
\\
The command language is an extension of \grace language, with all the
subsequent constraints. The user is encouraged to examine the files in
the \texttt{examples} directory. In this directory, files whose name begins with
\texttt{ng\_} are new \ggtk examples.

\ggtk language is based on numerous reserved words but a simple
grammar without elaborated constructs spreading on several lines.
%% ............................
\subsection{Definitions}
\subsubsection{Version number}
\index{Version number}
Saved project files start with: \texttt{@ VERSION} \nexpr{} where
$nexpr =~$1$xxyyzz$
where: $xx$ is the \textit{major} and $yy$ the \textit{minor} revision
numbers and $zz$ the \textit{patchlevel}.
The leading 1 is used to differentiate \ggtk from Grace.
\subsubsection{Constant}
\index{constant}
\texttt{PI} is the $\pi$ constant.
\subsubsection{Variables}
\index{variables}
Three types of numerical variables are possibles\footnote{
For simplicity we use \textit{vector} and \textit{matrix} although it
is simply arrays without reference to there exact mathematical definition.
}:
\begin{itemize}
\item \textit{var}  : scalar variable
\item \textit{vvar} : vector variable (one index array)
\item \textit{mvar} : matrix variable (two indexes array)
\end{itemize}
The indices in arrays start at zero, as it is the case in the C language.\\
It is possible to define user's variables if the
name is not already used\footnote{Switching from one project to
  another one does not reset the user space name,
  thus it is a good practise to
  \texttt{CLEAR~ALLVARS}, i.e. all user created variables at the end
  of a project file.}.
The table below gives the syntax to define and clear variables.
\begin{center}
  \begin{tabular}{||T| p{7cm} |T||} \hline \hline
    Statement                        & Description                              &  Example \\ \hline \hline
    DEFINE \textit{var}              & define new scalar variable \textit{var}  & DEFINE myvar \\
    DEFINE \textit{vvar}[]           & define new vector variable \textit{vvar}
                                                                 of zero length & DEFINE myvvar{[}{]} \\
    DEFINE \textit{vvar}[\textit{n}] & define new vector variable \textit{vvar}
                                                           of length \textit{n} & DEFINE myvvar{[}10{]} \\ \hline
    DEFINE \textit{mvar}[\textit{m}][\textit{n}]
                                     & define new matrix with \textit{m} rows and
                                       \textit{n} columns                       &  \\ \hline
    CLEAR \textit{var}               & undefine new variable \textit{var}
                                              and deallocate associated storage & CLEAR myvar \\
    CLEAR ALLVARS                    & undefine all user defined variables      &             \\  \hline
    \textit{vvar} LENGTH \textit{n}  & reallocate vector variable \textit{vvar} & myvvar LENGTH 25 \\
    \hline \hline
  \end{tabular}
Note that vectors length is dynamic, i.e. it can be changed after its
definition, but that matrices  dimensions are static.
\end{center}
\vspace{1em}
We use a special denomination for
some particular variables created by the program:
\begin{center}
  \begin{tabular}{||T|l|p{8cm}||} \hline \hline
    Name                     & Type      & Description \\ \hline\hline
    \textit{datacolumn}      & vector    & a data column of the current ("active") set \\ \hline
    \textit{set.datacolumn}  & vector    & a data column of set \\ \hline
    \textit{vvariable[i:j]}  & vector    &  segment of a vector variable
                                           (elements from i-th to j-th inclusive, i $<$= j) \\  \hline
    \textit{vvariable[i]}    & scalar    &  i-th element of a vector variable \\   \hline
    \hline
  \end{tabular}
\end{center}
%%
\vspace{1em}
The selection of a \textit{datacolumn} of a dataset is done
with the following syntax
\begin{center}
  \begin{tabular}{||T| l | l |T||} \hline\hline
    Expression  &  Description               &  Types             &  Example \\ \hline
    X           & the first column           & -                  & X \\
    Y           & the second column          & -                  & Y \\
    Y\textit{n} & (\textit{n} + 2)-th column & \textit{n} = 0 - 4 & Y3 \\
    \hline\hline
  \end{tabular}
\end{center}
%%
\vspace{1em}
Before selecting a \textit{datacolumn}, you must select a \textit{graph}
and a \textit{set} in the graph:
\begin{center}
  \begin{tabular}{||T| l | l |T||} \hline \hline
    Expression                  &  Description      &  Types &  Example \\ \hline
    \texttt{GRAPH}[\textit{id}] & graph \textit{id} & indx \textit{id} & GRAPH[0] \\
    G\textit{nn}                & graph \textit{nn} & \textit{nn}: 0-99 & G0 \\
    \hline\hline
  \end{tabular}\\
  Graph selection
  \index{Graphs!commands}
\end{center}
%%
\vspace{1em}
\begin{center}
  \begin{tabular}{||T| p{7cm} |T||}
    \hline
    Expression                           &  Description                             &  Example \\ \hline \hline
    \textit{graph}.SETS{[}\textit{id}{]} & set \textit{id} in graph \textit{graph}  &  GRAPH{[}0{]}.SETS[1] \\
    \textit{graph}.S\textit{nn}          & set \textit{nn} in graph \textit{graph}  & G0.S1 \\  \hline
    SET{[}\textit{id}{]}                 & set \textit{id} in the current graph     & SET{[}1{]} \\
    S\textit{nn}                         & set \textit{nn} in the current graph     & S1 \\  \hline
    S\_                                  & the last implicitly (i.e. as a result
                                           of a data transformation) allocated set
                                           in the current graph                     &  S\_ \\  \hline
    S\$                                  & the active set in the current graph      &  S\$ \\
    \hline\hline
  \end{tabular}\\
  Set selection
  \index{Sets!commands}
\end{center}
%%
\subsubsection{Colors, patterns and regions}
\begin{center}
  \begin{tabular}{||T|p{40mm}|P{35mm}||}
    \hline
    Expression                 &  Description                       &  Example \\ \hline \hline
    COLOR \textit{"colorname"} & a mapped color \textit{colorname}  & COLOR "red" \\
    COLOR \textit{id}          & a mapped color with ID \textit{id} & COLOR 2 \\ \hline \hline
    MAP COLOR \textit{id} TO \textit{(r,g,b), sexpr}
                               & define new color or remap old one  & MAP COLOR 5 TO (255, 255, 0), "yellow"\\ \hline
    PATTERN \textit{id}        & pattern with ID \textit{id}        & PATTERN 1 \\  \hline \hline
    R\textit{n}                & region \textit{n} , $n \in [0,4]$. & R0 \\ \hline
    \hline
  \end{tabular}
  \index{Colors}
\end{center}
In the following, $color$ can be the $id$ number as well as the the
quoted $colorname$.
%%
\subsection{Expressions}
\label{expressions}
\subsubsection{Elements and operators}
\ggtk can compute the value of algebraic expressions
and also concatenate strings using the '.' operator.
The following types of expressions are defined:
\begin{center}
  \begin{tabular}{||l|p{4cm}|T||} \hline \hline
    Name   &  Description           &  Examples \\ \hline
    \expr  & Any numeric expression & 1.5 + sin(2) \\
    \iexpr & Any expression that evaluates to an integer & 25, \textrm{the integer cast of}  0.1 + 1.9, PI/asin(1) \\
    \nexpr & Non-negative \iexpr    & 2 - 1 \\
    \indx  & Non-negative \iexpr    & ~     \\
    \vexpr & Vector expression      & "2*x" \\ \hline
    \mexpr & Matrix expression      & mx[][0:ylen-1] = mesh(0,2*pi,360)    \\ \hline
    \sexpr & String expression      & "a string", "a " . "string",\\ ~&~& "square root of 4 = " . sqrt(4) \\
    \hline \hline
  \end{tabular}
  \index{Expressions}
\end{center}
%%
\vspace{1em}
The following operators can be used in numerical expressions:
\begin{center}
  \begin{tabular}{ccc}
    \begin{tabular}{||T|l||} \hline \hline
      +         &  addition     \\  \hline
      -         &  substraction  \\  \hline
      *         &  multiplication \\  \hline
      /         &  division        \\  \hline
      \%        &  modulus          \\  \hline
      \^{}      &  raising to power  \\  \hline\hline
    \end{tabular}
    &
    \begin{tabular}{||TcT||}  \hline  \hline
      AND &or& \&\&   \\  \hline
      OR  &or& $|$$|$  \\  \hline
      NOT &or& !      \\  \hline\hline
    \end{tabular}
    &
    \begin{tabular}{||TcT|l||}   \hline \hline
      EQ &or& ==   &  equal           \\ \hline
      NE &or& !=   &  not equal        \\ \hline
      LT &or& $<$  &  less than         \\ \hline
      LE &or& $<$= &  less than or equal \\ \hline
      GT &or& $>$  &  greater than        \\ \hline
      GE &or& $>$= &  greater than or equal \\ \hline\hline
    \end{tabular}
    \\
    Arithmetic operators & Logical operators & Comparison operators
    \index{operators}
  \end{tabular}
\end{center}
%% $
\vspace{1em}
Another conditional operator is the "$?~:$" (or ternary) operator, which
operates as in C and many other languages:
\begin{displaymath}
  (expr1)~~?~~(expr2)~~:~~(expr3);
\end{displaymath}
This expression evaluates to $expr2$ if $expr1$ evaluates to \texttt{TRUE},
and $expr3$ if $expr1$ evaluates to \texttt{FALSE}.
\subsubsection{Grammar rules}
In the following, let us write
\texttt{a} for scalars,
\texttt{m ,n} for integers positive or nul,
\texttt{u, v, w} for vectors and
\texttt{M}, for matrices.
\begin{itemize}
\item
  Algebra for scalars obeys the usual rules.
\item
  For homogeneous vectors or matrices expressions operators are
  applied element by element, i.e. $v * w$ is not the scalar
  product of the two vectors, but produces a vector $w$ with
  $ w_i \: = \: u_i \: v_i     \quad \forall i$
\item
  For vectors or matrices expressions with a scalar,
  the operator applies the scalar to all the elements of the
  array.
\end{itemize}
For assignations, the not obvious following rules are defined:
\begin{itemize}
\item \texttt{w = v[m:n]}
\item \texttt{M[][n] = v}   and  \texttt{~M[n][] = v}
\item \texttt{M[m:n][] = v} and  \texttt{~M[][m:n] = v}
\item \texttt{v = M,~~ M = v~} and \texttt{~M = a}
\end{itemize}
If you have a doubt or want to add new rules, the \texttt{Grammar
  rules} section of file \texttt{pars.yacc} is the good place.
%%
\newpage
%%%%
\subsection{Functions}
\label{sec-functions}
\index{Functions}
\subsubsection{Elementary functions}
The list is given in table \ref{table-functions}.
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{||T|l||}      \hline \hline
      Function            &  Description \\ \hline \hline
      abs$(x)$            &  absolute value \\  \hline
      acos$(x)$           &  arccosine \\
      acosh$(x)$          &  hyperbolic arccosine \\
      asin$(x)$           &  arcsine \\
      asinh$(x)$          &  hyperbolic arcsine \\
      atan$(x)$           &  arctangent \\
      atan2$(y,x)$        &  arc tangent of two variables \\
      atanh$(x)$          &  hyperbolic arctangent \\  \hline
      ceil$(x)$           &  greatest integer function \\
      cos$(x)$            &  cosine \\
      cosh$(x)$           &  hyperbolic cosine \\
      exp$(x)$            &  $e^x$ \\
      fac$(n)$            &  factorial function, n! \\
      floor$(x)$          &  least integer function \\
      irand$(n)$          &  random integer less than $n$ \\   \hline
      ln$(x)$             &  natural log \\
      log10$(x)$          &  log base 10 \\
      log2$(x)$           &  base 2 logarithm of $x$ \\   \hline
      maxof$(x,y)$        &  returns greater of x and y \\
      mesh$(n)$           &  mesh array  $(0 \dots , n - 1)$ \\
      mesh$(x_1, x_2, n)$ &  mesh array of n equally spaced points between $x_1$ and $x_2$ inclusive \\
      minof$(x,y)$        &  returns lesser of x and y \\
      mod$(x,y)$          &  mod function  (also x \% y) \\  \hline
      rand                &  pseudo random number distributed uniformly on  (0.0,1.0) \\
      rand$(n)$           &  array of n random numbers \\
      rint$(x)$           &  round to closest integer \\
      rsum$(x)$           &  running sum of x \\
      sgn$(x)$            &  signum function \\   \hline
      sin$(x)$            &  sine function \\
      sinh$(x)$           &  hyperbolic sine \\
      sqr$(x)$            &  x\^{}2 \\
      sqrt$(x)$           &  x\^{}0.5 \\
      tan$(x)$            &  tangent function \\
      tanh$(x)$           &  hyperbolic tangent \\
      \hline \hline
    \end{tabular}
  \end{center}
  \caption{Elementary functions}
  \label{table-functions}
  \index{Functions!elementary}
\end{table}
%%
\subsubsection{Min, max and others}
\begin{center}
  \begin{tabular}{||T|l||}      \hline \hline
    Function   &  Description \\ \hline \hline
    MIN$(x)$   &  min value of array $x$ \\
    MAX$(x)$   &  max value of array $x$ \\  \hline
    AVG$(x)$   &  average of array $x$ \\
    SD$(x)$    &  standard deviation of array $x$ \\  \hline
    SUM$(x)$   &  sum of all elements of array $x$ \\
    INT$(x,y)$ &  integral of $y~dx$ \\  \hline
    IMIN$(x)$  &  index of min value of array $x$ \\
    IMAX$(x)$  &  index of max value of array $x$ \\
    \hline\hline
  \end{tabular}
  \index{Functions!min, max and others}
\end{center}
%%
\subsubsection{Statistical functions}
The list is given in table \ref{stat-functions}.
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{||T|l||}      \hline \hline
      Function          &  Description \\ \hline\hline
      chdtr$(df, x)$     &  chi-square distribution \\
      chdtrc$(v, x)$     &  complemented Chi-square distribution \\
      chdtri$(df, y)$    &  inverse of complemented Chi-square distribution \\  \hline
      erf$(x)$           &  error function \\
      erfc$(x)$          &  complement of error function \\  \hline
      fdtr$(df1, df2, x)$&  F distribution function \\
      fdtrc$(x)$         &  complemented F distribution \\
      fdtri$(x)$         &  inverse of complemented F distribution \\  \hline
      gdtr$(a, b, x)$    &  gamma distribution function \\
      gdtrc$(a, b, x)$   &  complemented gamma distribution function \\  \hline
      ndtr$(x)$          &  Normal distribution function \\
      ndtri$(x)$         &  inverse of Normal distribution function \\  \hline
      norm$(x)$          &  gaussian density function \\  \hline
      pdtr$(k, m)$       &  Poisson distribution \\
      pdtrc$(k, m)$      &  complemented Poisson distribution \\
      pdtri$(k, y)$      &  inverse Poisson distribution \\  \hline
      rnorm$(xbar,s)$    &  pseudo random number distributed $N (xbar,s)$ \\  \hline
      stdtr$(k, t)$      &  Student's t distribution \\
      stdtri$(k, p)$     &  functional inverse of Student's t distribution \\
      \hline\hline
    \end{tabular}
  \end{center}
  \caption{Statistical functions}
  \label{stat-functions}
  \index{Functions!statistical}
\end{table}
%%
\clearpage
%%
\subsubsection{Special math functions}
The list is given in table \ref{spec-functions}.
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{||T|p{11cm}||}      \hline \hline
      Function                   &  Description \\ \hline \hline
      ai$(x)$, bi$(x)$           &  Airy functions (two independent solutions of
                                   the differential equation $y''(x) = xy)$\\ \hline
      beta$(x)$                  &  beta function              \\ \hline
      chi$(x)$                   &  hyperbolic cosine integral \\
      ci$(x)$                    &  cosine integral            \\ \hline
      dawsn$(x)$                 &  Dawson's integral          \\ \hline
      ellie$(\phi, m)$           &  incomplete elliptic integral of the second kind \\
      ellik$(\phi, m)$           &  incomplete elliptic integral of the first kind \\
      ellpe$(m)$                 &  complete elliptic integral of the second kind \\
      ellpk$(m)$                 &  complete elliptic integral of the first kind \\  \hline
      expn$(n, x)$               &  exponential integral      \\  \hline
      fresnlc$(x)$               &  cosine Fresnel integral   \\
      fresnls$(x)$               &  sine Fresnel integral     \\  \hline
      gamma$(x)$                 &  gamma function            \\  \hline
      hyp2f1$(a, b, c, x)$       &  Gauss hyper-geometric function \\
      hyperg$(a, b, x)$          &  confluent hyper-geometric function \\  \hline
      i0e$(x)$                   &  modified Bessel function of order zero, exponentially scaled \\
      i1e$(x)$                   &  modified Bessel function of order one, exponentially scaled \\  \hline
      igam$(a, x)$               &  incomplete gamma integral \\
      igamc$(a, x)$              &  complemented incomplete gamma integral \\
      igami$(a, p)$              &  inverse of complemented incomplete gamma integral \\  \hline
      incbet$(a, b, x)$          &  incomplete beta integral \\
      incbi$(a, b, y)$           &  Inverse of incomplete beta integral   \\  \hline
      iv$(v, x)$                 &  modified Bessel function of order $v$ \\
      jv$(v, x)$                 &  Bessel function of order $v$ \\
      k0e$(x)$                   &  modified Bessel function, third kind, order zero, exponentially scaled \\
      k1e$(x)$                   &  modified Bessel function, third kind, order one, exponentially scaled \\
      kn$(n, x)$                 &  modified Bessel function, third kind, integer order \\  \hline
      lbeta$(x)$                 &  natural log of $|$\texttt{beta}$(x)|$ \\  \hline
      lgamma$(x)$                &  log of gamma function \\
      psi$(x)$                   &  psi (digamma) function \\
      rgamma$(x)$                &  reciprocal gamma function \\  \hline
      shi$(x)$                   &  hyperbolic sine integral \\
      si$(x)$                    &  sine integral \\  \hline
      spence$(x)$                &  dilogarithm \\  \hline
      struve$(v, x)$             &  Struve function \\  \hline
      voigt$(\gamma, \sigma, x)$ &  Voigt function  (convolution of Lorentzian and Gaussian)\\  \hline
      yv$(v, x)$                 &  Bessel function of order v \\  \hline
      zeta$(x, q)$               &  Riemann zeta function of two arguments \\
      zetac$(x)$                 &  Riemann zeta function \\
      \hline\hline
    \end{tabular}
  \end{center}
  \caption{Special math functions}
  \label{spec-functions}
  \index{Functions!special}
\end{table}
%%
\newpage
%% ............................
\subsection{Procedures to transform and create new sets}
\index{Sets!transformation}
Methods of directly manipulating the sets and their data,
corresponding to simple actions accessed trough 
\texttt{Edit/Set operations}  and \texttt{Data/Data sets operations}
are given below
\begin{center}
  \begin{tabular}{||P{3cm}|p{7cm}|P{4.2cm}||}      \hline \hline
      Statement                                &  Description &  Example \\  \hline \hline
      COPY $src$ TO $dest$                     & Copies $src$ to $dest$                                                             & COPY S0 TO S1 \\
      MOVE $src$ TO $dest$                     & Moves $src$ to $dest$                                                              & MOVE G0.S0 TO G1.S0 \\
      SWAP $src$ AND $dest$                    & Interchanges $src$ and $dest$                                                      & SWAP G0.S0 AND G0.S1 \\
      KILL $set$                               & Kills $set$                                                                        & KILL G0.S0 \\ \hline
      REVERSE $set$                            & reverse abscissas of $set$                                                         & REVERSE G0.S0 \\
      SORT $set, col ,dir$                     & Sort points with respect to $col$ and direction $dir$                              & SORT G0.S0 Y ASCENDING\\ \hline
     $set$ POINT $x, y$                        & Add a point at the end of  $set$                                                   & G0.S0 POINT 10.0 ,5.0\\
     $set$ DROP $n1, n2$                       & Drop points $n1$ to $n2$                                                           & G0.S0 DROP 5 , 10\\ \hline
     APPEND $set2$ TO $set1$                   & Append sets from the same graph                                                    & \\ \hline 
     \hline
   \end{tabular}
  To \texttt{SORT}, the $col$ can be \verb+X, Y+, the $dir$ \texttt{ASCENDING, DESCENDING}
 \end{center}
 The more sophisticated operations accessed be 
\texttt{Data/Transformation}
menu are described in table \ref{transformations}.
To evaluate expressions, you can directly submit
them to the command interpreter like you would in the evaluate expression
window.\\
As an example, S1.X = S1.X * 0.000256 scales the x-axis
coordinates. The functionality of the 'Sample points' menu entry can be
obtained through RESTRICT.
\begin{table}[htbp]
  \index{Non-linear fit}\index{fitting curve}
  \begin{center}
    \begin{tabular}{||P{4.5cm}|p{7.5cm}|P{4.2cm}||}      \hline \hline
      RUNAVG$(set, npoints)$                   & running average of \textit{set} using \textit{npoints} number of points            & RUNAVG (S0, 100) \\ \hline
      RUNMED$(set, npoints)$                   & running median of \textit{set} using \textit{npoints} number of points             & RUNMED (S0, 100) \\ \hline
      RUNMIN$(set, npoints)$                   & running minimum of \textit{set} using \textit{npoints} number of points            & RUNMIN (S0, 100) \\ \hline
      RUNMAX$(set, npoints)$                   & running maximum of \textit{set} using \textit{npoints} number of points            & RUNMAX (S0, 100) \\ \hline
      RUNSTD$(set, npoints)$                   & running standard deviation of \textit{set} using \textit{npoints} number of points & RUNSTD (S0, 100) \\ \hline\hline
      INTERPOLATE$(set, mesh,$ $method, strict)$ & interpolate \textit{set} on a sampling \textit{mesh} using
                                                \textit{method}. \textit{strict} flag controls whether result should be
                                                bound within the source set                                                        & {\small INTERPOLATE~(S0, S1.X, ASPLINE, OFF)} \\ \hline
      XYSPLINE$(set, s ,p)$                    & interpolate \textit{set} using XY-splines with parameters $s$ and $p$.
(see \hyperlink{interp-popup}{\texttt{Interpolation/Splines}})
& XYSPLINE (G1.s0 ,0.5 ,0.002)\\ \hline\hline
      HISTOGRAM$(set, bins,$ $cumulative, normalize)$ & calculate histogram of \textit{set} on defined \textit{bins}.
                                                     \textit{cumulative} and \textit{normalize} flags control whether to
                                                     calculate cumulative and normalized (aka PDF) histograms, respectively.
                                                     Data points are placed at upper limit of the bin                              & {\small HISTOGRAM(S0, MESH(0, 1, 11), OFF, ON)} \\ \hline
      XCOR$(set1, set2,$ $maxlag, covar)$       & calculate cross-correlation (or -covariance if the \textit{covar} flag is set)
                                                of \textit{set1} with \textit{set2} with maximum lag \textit{maxlag}.              & XCOR (S0, S0, 50, OFF) \\ \hline
      LINCONV$(set1, set2)$                   & calculate linear convolution of the array of ordinates of \textit{set1}
                                                with that of \textit{set2}.                                                        & LINCONV (S0, S1) \\ \hline
      RESTRICT$(set, restriction)$            & filter \textit{set} according to logical \textit{restriction}.
                                                The original set will be overwritten                                               & {\small RESTRICT (S0, S0.X {$<$} 0)} \\ \hline
      RESTRICT$(set, region,$ $negate)$         & filter \textit{set} by keeping only points lying inside/outside \textit{region}.
                                                The original set will be overwritten                                               & RESTRICT (S0, R1, OFF) \\ \hline\hline
      NONLFIT$(set, nsteps)$                     & Non linear fit on set $set$ with $nsteps$ steps. See Data menu \hyperlink{nonlfit}{\texttt{Non linear fit}} & \\\hline
      NONLFIT$(set, wheight, nsteps)$            & $idem$ + a weight array  $wheight$                                              & \\\hline
      \multicolumn{2}{||T|}{NONLFIT$(set, params, nsteps, formula ,trace)$}  &  \\ &
                                                 $params$ is an array for starting values of parameters.
                                                 See \texttt{examples/ng\_nonlfitb.agr}                                            & NONLFIT (G0.s0 ,nlparms ,10 ,"y = A0 + A1*x + A2*x\^{}2)" ,ON) \\ \hline
                            FFT$(set ,filter)$ & See section (\ref{fftCommands})                                                   &\\
      \multicolumn{2}{||T|}{FFT$(set ,intyp ,filter ,xscale ,outtyp)$           }&\\
      \multicolumn{2}{||T|}{FFT$(set ,intyp ,filter ,xscale ,outtyp ,outseg)$   }&\\ \hline
      \multicolumn{2}{||T|}{WAVELET$(set ,type ,stride ,k ,invflag)$\hfill  see section (\ref{waveletCall})}&\\ \hline
      \hline
    \end{tabular}
  \end{center}
  The $set$(s) arguments are any set selector, and $npoints$ is a \textit{nexpr}.
  The $mesh$ argument is a \textit{vexpr}.\\
  To  \texttt{INTERPOLATE}, the $method$ can be \texttt{LINEAR, SPLINE ,ASPLINE}, or \texttt{XSPLINE}.\\
  $strict, cumulative, normalize, covar, trace$ and $negate$
  arguments are \textit{onoff}.\\
  $restriction$ is a $vexpr$ and $region$ a region selector.
  \caption{Commands to transform datasets}
  \label{transformations}
\end{table}

Not finished yet...
%%
\clearpage
%% ............................
\subsection{Page loading, sizing, saving and printing}
\index{Save}
The following commands are used:
\begin{center}
  \begin{tabular}{||T|l|T||}\hline
    Statement          &  Description           &  Example          \\ \hline \hline
    LOAD $"file"$      & load project $file$    & LOAD "foo.agr"    \\
    SAVEALL $"file"$   & save project to $file$ & SAVEALL "foo.agr" \\
    PRINT              & execute print job      & PRINT             \\ \hline \hline
  \end{tabular}
\end{center}
%%
For producing "hard copy", several parameters can be set via the command
interpreter.
They are summarized in table \ref{device-parameters}.
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{||T|p{7cm}||}\hline \hline
      Command &  Description \\ \hline\hline
      PAGE SIZE $xdim, ydim$             &  set page dimensions of all devices  (in pp)\\
      PAGE SIZE $"stdsize", orientation$ &  set page dimensions of all devices:  
                                           \parbox{6.5cm}{
                                             $stdsize$ can be "Letter" ,"A0", \dots "A9", "B0",\dots ,"B9"
                                             (into double quotes)\\
                                             $orientation$ is \texttt{portrait} or \texttt{landscape}} 
                                           (without double quotes)\\ \hline
      PAGE RESIZE $xdim, ydim$          &  same as above plus rescale the current plot accordingly \\
      PAGE RESIZE $"stdsize", orientation$ &   \\ \hline
      DEVICE $"devname"$ PAGE SIZE $xdim, ydim$ &  set page dimensions (in pp) of device$devname$ \\ \hline
      DEVICE $"devname"$ DPI $dpi$      &  set device's dpi (dots per pixel) \\ \hline
      DEVICE $"devname"$ FONT $onoff$   &  enable/disable usage of built-in fonts for device $devname$ \\ \hline
      DEVICE $"devname"$ FONT ANTIALIASING $onof$f &  enable/disable font aliasing for device $devname$ \\ \hline
      DEVICE $"devname"$ OP $"options"$ &  set device specific options (see \ref{device-settings} {(Device-specific settings)}) \\ \hline
      HARDCOPY DEVICE $"devname"$       &  set device $devname$ as current hardcopy device \\ \hline
      PRINT                             & execute print job  \\ \hline
      PRINT TO $"filename"$             &  set print output to $filename$ (but do not print) \\ \hline
      PRINT TO DEVICE                   &  set print output to hardcopy device (but do not print) \\
      \hline\hline
    \end{tabular}
  \end{center}
  \caption{Commands to set device parameters}
  \index{print}
  \label{device-parameters}
\end{table}
%% ............................
\subsection{Flow control and GUI interaction}
\begin{center}
  \begin{tabular}{||T| p{6.5cm} | l |T||}\hline \hline
    Statement &  Description &  Types &  Example \\ \hline \hline
    EXIT(\textit{status}) & cause normal program termination with exit status \textit{status}      & iexpr \textit{status} & EXIT(0) \\
    EXIT                  & cause normal program termination; same as \texttt{EXIT(0)} & ~         & EXIT \\ \hline
    HELP \textit{url}     & open a HTML document pointed to by \textit{url}   & sexpr \textit{url} & HELP "doc/FAQ.html" \\
    HELP                  & open User's Guide                                 & ~                  & HELP   \\ \hline
    REDRAW                & refresh the canvas to reflect the current project state & ~            & REDRAW  \\ \hline
    SLEEP \textit{n}      & sleep for \textit{n} seconds                      & expr \textit{n}    & SLEEP(3) \\
    \hline\hline
  \end{tabular}
\end{center}
%% ............................
\clearpage
%%
\subsection{Graphs}
%%
\subsubsection{General graphs operation}
\index{Graphs}
See table \ref{graph-op}.
\begin{table}[htbp]
  \begin{tabular}{||p{9cm}|P{5cm}||}\hline \hline
    \texttt{Command} \hfill Description &  Example \\ \hline\hline
    \texttt{ARRANGE(\textit{nrows}, \textit{ncols}, \textit{offset},
    \textit{hgap}, \textit{vgap})}
    & ARRANGE(2, 2, 0.1, 0.15, 0.2) \\
    Arrange existing graphs (or add extra if needed)
    to form an
    \textit{nrows} by \textit{ncols} matrix, leaving \textit{offset} at
    each page edge with \textit{hgap} and \textit{vgap} relative
    horizontal and vertical spacings
    nexpr \textit{nrows}, \textit{ncols}, expr \textit{offset},
    \textit{hgap}, \textit{vgap}
    &~\\ \hline
    \texttt{ARRANGE(\textit{nrows}, \textit{ncols}, \textit{offset},
    \textit{hgap}, \textit{vgap}, \textit{hvinv}, \textit{hinv},
    \textit{vinv})}
    & ARRANGE(2, 2, 0.1, 0.15, 0.2, ON, OFF, ON)
    \\
    Same as above, plus additional \textit{hvinv},
    \textit{hinv}, and \textit{vinv} flags allowing to alter the order of
    the matrix filling
    nexpr \textit{nrows}, \textit{ncols}, expr \textit{offset},
    \textit{hgap}, \textit{vgap}, onoff \textit{hvinv}, \textit{hinv},
    \textit{vinv}
    &~\\ \hline
    \texttt{ARRANGE(\textit{nrows}, \textit{ncols}, \textit{offset},
    \textit{hgap}, \textit{vgap}, \textit{hvinv}, \textit{hinv},
    \textit{vinv}, \textit{snake})}
    & ARRANGE(2, 2, 0.1, 0.15, 0.2, ON, OFF, ON, ON)
    \\
    Same as above, plus additional \textit{snake} flag allowing to fill
    the matrix in a snake-like fashion
    nexpr \textit{nrows}, \textit{ncols}, expr \textit{offset},
    \textit{hgap}, \textit{vgap}, onoff \textit{hvinv}, \textit{hinv},
    \textit{vinv}, \textit{snake}
    &~\\ \hline
    \texttt{AUTOSCALE}              \hfill scale the graph                & AUTOSCALE       \\ \hline
    \texttt{AUTOSCALE XAXES}        \hfill scale the graph in x only      & AUTOSCALE XAXES \\ \hline
    \texttt{AUTOSCALE YAXES}        \hfill scale the graph in y only      & AUTOSCALE YAXES \\ \hline
    \texttt{AUTOSCALE} $set$        \hfill scale to a specific set        & AUTOSCALE S0    \\ \hline
    \texttt{AUTOTICKS}              \hfill autotick all axes              & AUTOTICKS       \\ \hline
    \texttt{FOCUS} $graph$                                                & FOCUS G0        \\
                                    \hfill Makes  $graph$ current and unhides it if necessary &~\\ \hline
    \texttt{KILL}  $graph$          \hfill Kills $graph$                  & KILL G0         \\ \hline
    \texttt{WITH}  $graph$          \hfill Makes $graph$ current          & WITH G0         \\ \hline
    \texttt{TYPE}  $type$           \hfill Sets  $type$ of current graph  & TYPE XY
                                    \hfill (see table \ref{tab_set})\\
    $graph$ \texttt{TYPE} $type$    \hfill  Sets $type$ of $graph$        &  G0 TYPE XYDY   \\ \hline
    $graph~~onoff$                  \hfill (De)Activates selected $graph$ &  G0 ON          \\ \hline
    $graph$ \texttt{HIDDEN} $onoff$ \hfill  Hides selected $graph$        &  G1 HIDDEN TRUE \\ \hline
    \hline
    $graph$ \texttt{AUTOSCALE TYPE} $atype$ \hfill Sets autoscale type   &  G1 AUTOSCALE TYPE SPEC  \\ \hline
  \end{tabular}
  \caption{Commands for general graphs operation}
  \label{graph-op}
\end{table}
%%
\subsubsection{Axis parameters}
\index{Axis}
See table \ref{axis-param-commands}.
\begin{table}[htbp]
  \begin{tabular}{||P{9cm}|P{5cm}||}\hline \hline
    Command \hfill\textrm{Description} &  Example \\ \hline\hline
    AUTOSCALE ONREAD \textit{type} &~\\ \pvr{ Set automatic scaling on read according to \textit{type}}             &  AUTOSCALE ONREAD NONE \\ \hline
    WORLD $x_{min}, y_{min}, x_{max}, y_{max}$ &~\\ \pvr{ Sets world scaling}                                          &  WORLD -1.0 ,-1.0 ,1.0 ,10.0 \\ \hline
    WORLD XMIN \textit{xmin}       &~\\ \pvr{ Sets minimum value of current graph's x axis to \textit{xmin}}        &  WORLD XMIN -10 \\ \hline
    WORLD XMAX \textit{xmax}       &~\\ \pvr{ Sets maximum value of current graph's x axis to \textit{xmin}}        &  WORLD XMAX 22.5 \\ \hline
    VIEW XMIN \textit{xmin}        &~\\ \pvr{ Sets left edge of current graph at x=\textit{xmin} in the viewport}   &  VIEW XMIN .2 \\ \hline
    VIEW XMAX \textit{xmax}        &~\\ \pvr{ Sets right edge of current graph at x=\textit{xmax} in the viewport}  &  VIEW XMAX 1.0 \\ \hline
    VIEW $x_{min}, y_{min}, x_{max}, y_{max}$  &~\\ \pvr{ Sets graph's viewport }                                      &  VIEW 0.15, 0.15, 1.15, 0.85 \\ \hline
    XAXES SCALE \textit{type}           \pvr{ Set scaling of the x axes to \textit{type}}                           &  XAXES SCALE NORMAL \\
    XAXES INVERT onoff             &~\\ \pvr{ If \texttt{ON}, draws xmin to xmax from right to left}                &  XAXES INVERT OFF \\ \hline
    XAXIS  onoff                        \pvr{ Set axis visibility}                                                  &  XAXIS  ON        \\ \hline
    XAXIS  TYPE ZERO onoff              \pvr{ Set if axis ordinate is zero}                                         &  XAXIS  TYPE ZERO FALSE\\ \hline
    \hline
  \end{tabular}
\caption{Commands to set axis parameters}
\label{axis-param-commands}
\end{table}
%%
\subsubsection{Titles and legends}
\index{Titles}\index{Legend}
See table \ref{graphlegend-pars}.
\begin{table}[htbp]
  \begin{tabular}{||P{9cm}|P{5cm}||}\hline \hline
    Command                              \pvr{ Description                                        }& Example \\ \hline\hline
    TITLE \textit{title}                 \pvr{ Sets the title of current graph                    }& TITLE "Foo" \\
    TITLE FONT \textit{font}             \pvr{ Selects font of title string                       }& TITLE FONT 1 \\
    TITLE SIZE \textit{size}             \pvr{ Sets size of title string                          }& TITLE SIZE 1.5 \\
    TITLE COLOR \textit{color}           \pvr{ Sets color of title string                         }& TITLE COLOR 1 \\ \hline
    SUBTITLE \textit{subtitle}           \pvr{ Sets the subtitle of current graph                 }& SUBTITLE "Bar" \\
    SUBTITLE FONT \textit{font}          \pvr{ Selects font of subtitle string                    }& SUBTITLE FONT "Times-Italic" \\
    SUBTITLE SIZE \textit{size}          \pvr{ Sets size of subtitle string                       }& SUBTITLE SIZE .60 \\
    SUBTITLE COLOR \textit{color}        \pvr{ Sets color of subtitle string                      }& SUBTITLE COLOR "blue" \\ \hline
    LEGEND onoff                         \pvr{ Toggle legend display                              }& LEGEND ON \\ \hline
    LEGEND LOCTYPE \textit{type}         \pvr{ Position legend in \textit{type} coordinates       }& LEGEND LOCTYPE WORLD \\ \hline
    LEGEND \textit{xloc, yloc}           \pvr{ Set location of legend box (upper left corner)     }& LEGEND .5,.75 \\ \hline
    LEGEND FONT \textit{font}            \pvr{ Set legend font type                               }& LEGEND FONT "Helvetica" \\
    LEGEND CHAR SIZE \textit{size}       &~\\
    \pvr{ Sets size of legend label characters (1 is normal)                                      }& LEGEND CHAR SIZE .30 \\
    LEGEND \textit{color}                \pvr{ Set color of legend text                           }& LEGEND COLOR 1 \\ \hline
    LEGEND VGAP \textit{gap}             \pvr{ Sets vertical gap between legend entries           }& LEGEND VGAP 1 \\ \hline
    LEGEND HGAP \textit{gap}             \pvr{ Sets horizontal gap between symbol and description }& LEGEND HGAP 4 \\ \hline
    LEGEND LENGTH \textit{length}        \pvr{ Sets \textit{length} of legend                     }& LEGEND LENGTH 5 \\ \hline
    LEGEND INVERT onoff                  &~\\
    \pvr{\parbox{6cm}{Determines relationship between order of sets and order of legend labels}   }& LEGEND INVERT true \\ \hline
    LEGEND BOX onoff                     &~\\ \pvr{ Determines if the legend bounding box is drawn}& LEGEND BOX off      \\ \hline
    LEGEND BOX COLOR \textit{color}      &~\\ \pvr{ Sets color of legend bounding box             }& LEGEND BOX COLOR 1   \\ \hline
    LEGEND BOX PATTERN \textit{pattern}  &~\\ \pvr{ Sets pattern of legend bounding box           }& LEGEND BOX PATTERN 2  \\ \hline
    LEGEND BOX LINESTYLE \textit{style}  &~\\ \pvr{ Sets line style of bounding box               }& LEGEND BOX LINESTYLE 1 \\ \hline
    LEGEND BOX LINEWIDTH \textit{width}  &~\\ \pvr{ Sets line width of bounding box               }& LEGEND BOX LINEWIDTH 1.5 \\ \hline
    LEGEND BOX FILL onoff                &~\\ \pvr{ Determines if the legend bounding box is filled }& LEGEND BOX FILL false \\ \hline
    LEGEND BOX FILL COLOR \textit{color} &~\\ \pvr{ Sets color of legend box fill                 }& LEGEND BOX COLOR 3 \\ \hline
    LEGEND BOX FILL \textit{pattern}     &~\\ \pvr{ Sets pattern of legend box fill               }& LEGEND BOX FILL PATTERN 1\\ \hline
    \hline
  \end{tabular}
  \caption{Commands for graphs titles and legend}
  \label{graphlegend-pars}
\end{table}
%% ............................
\clearpage
%%
\subsection{Sets}
%%
\index{Sets}
\subsubsection{General sets operation}
See table \ref{set-io}.
\begin{table}[htbp]
  \begin{tabular}{||P{9cm}|P{5cm}||}\hline \hline
    Command                                         \pvr{ Description                                      }& Example                      \\ \hline\hline
    READ \textit{file}                              \pvr{ Reads $file$ as a single set                     }& READ "foo.dat"               \\ \hline
    READ \textit{settype~file}                 &~\\ \pvr{ Reads $file$ into a single set of type $settype$ }& READ xydy "bar.dat"          \\ \hline
    READ NXY \textit{file}                          \pvr{ Reads $file$ as NXY data                         }& READ NXY "gad.dat"           \\ \hline
    READ BLOCK \textit{file}                        \pvr{ Reads $file$ as block data                       }& READ BLOCK "zooks.dat"       \\ \hline
    KILL BLOCK                                 &~\\ \pvr{\parbox{6cm}{
        Kills the current block data and frees the associated memory}                                      }& KILL BLOCK \\ \hline
    BLOCK \textit{settype~columns}             &~\\ \pvr{\parbox{6cm}{
        Forms a data set of type \textit{settype} using \textit{columns} from current block data file.}    }& BLOCK xydxdy "0:2:1:3" \\[0.7em] \hline
    \textit{set} TYPE \textit{settype}              \pvr{ Defines the type of the set                      }& G0.s0 TYPE XY                \\ \hline
    WRITE \textit{set}                              \pvr{ writes $set$ to stdout                           }& WRITE G0.S1 \\ \hline
    WRITE \textit{set} FORMAT $formatstring$   &~\\ \pvr{\parbox{6cm}{
        writes \textit{set} to stdout using format specification \textit{formatstring}}                    }& WRITE G0.S1 FORMAT "\%18.8g" \\ \hline
    WRITE \textit{set} FILE $file$                  \pvr{ writes $set$ to $file$                           }& WRITE G0.S1 FILE "data.dat" \\ \hline
    WRITE \textit{set} FILE $file$ FORMAT \textit{formatstring} &~\\ \pvr{ \parbox{6cm}{
        writes \textit{set} to $file$ using format specification $formatstring$}                           }& WRITE G0.S1 FILE "data.dat" FORMAT "\%18.8g" \\ \hline\hline
    COPY \textit{src} TO \textit{dest}       \pvr{ Copies $src$ to $dest$                                  }& COPY S0 TO S1 \\
    MOVE \textit{src} TO \textit{dest}       \pvr{ Moves $src$ to $dest$                                   }& MOVE G0.S0 TO G1.S0 \\
    SWAP \textit{src} AND \textit{dest}      \pvr{ Interchanges $src$ and $dest$                           }& SWAP G0.S0 AND G0.S1 \\
    KILL \textit{set}                        \pvr{ Kills $set$                                             }& KILL G0.S0 \\
    \hline
  \end{tabular}
  \caption{Commands for set operation}
~\\Note that XYCMAP is a special case: \textit{set} \texttt{TYPE XYCMAP} \textit{nx , ny}
  \label{set-io}
  \index{Sets!commands}
\end{table}
%%
\clearpage
%%
\subsubsection{Commands for  XYCMAP sets}
\index{XYCMAP}
\index{Sets!XYCMAP}
\index{Contour}
%%
This type of sets implies some changes compared to the rules for other
types of sets.\\ 
First the command defining the type of the set is
\begin{center}
\textit{selectset} \texttt{ TYPE XYCMAP } \textit{nx ,ny}
\end{center}
where $nx$ and $ny$ are the width and height in number of points of
the rectangular grid.\\
Second, the \textit{Colorbar} is an object (see table \ref{geom1}, of course
not all command are pertinent) with special commands.
Also, it is possible to choose the colormap used.
\begin{center}
  \begin{tabular}{||T|p{5cm}|l||}
      \hline \hline
      Command &  Description &  Remarks \\
      \hline \hline
    \textit{set}  COLORBAR ZSCALE $z1 ,z2$ & the scale in $z$                           & ~ \\ \hline
    \textit{set}  COLORBAR NTICKS $n$      & the number of ticks and level for contours & ~ \\ \hline
    \textit{set}  COLORBAR AUTOSCALE       & computes the $z$ scale for the colors      & ~ \\ \hline
    \textit{set}  CMAP $n$                 & choose the color map                       & ~ \\
    \textit{set}  CMAP \textit{"name"}     & choose the color map                       & ~ \\
    \hline
  \end{tabular}
\end{center}
Color map 0 is the current \ggtk colormap used when you fix a line, symbol or pattern color.
The other names of color maps are borrowed to Scilab (http://www.scilab.org):
\textit{
"Jet colormap", "Hot colormap", "Grey colormap", "Winter colormap", "Spring colormap",
"Summer colormap", "Autumn colormap", "Rainbow colormap", "Bone colormap",
"Copper colormap", "Ocean colormap" and "White colormap".}
\\
Contour curves use the  commands in table \ref{tacontour}:
  \begin{table}[htbp]
\begin{center}
  \begin{tabular}{||T|p{3.3cm}|T||}
      \hline \hline
      Command &  Description &  Remarks \\
      \hline \hline
    \textit{set}  CONTOUR \textit{onoff}           & show/hide                  & G1.s0 CONTOUR ON  \\ \hline
    \textit{set}  CONTOUR COLOR \textit{} $<$\textit{ n} $|$\textit{ "colorname"}$>$
                                                   & show/hide                  & G1.s0 CONTOUR COLOR "white"  \\ \hline
    \textit{set}  CONTOUR LINEWIDTH \textit{width} &                            &      \\ \hline
    \textit{set}  CONTOUR LABEL $x, y, z$          & define a label on a curve  & ~     \\ \hline
    \hline
  \end{tabular}\\
 Note that the \texttt{LABEL} command is not designed for user, but for internal (save) use:
 if no curve crosses the point, it is ineffective.
\end{center}
    \caption{Command defining parameters of contour curves}
    \label{tacontour}
  \end{table}
%%
%%
\clearpage
%% ............................
\subsection{Geometric objects}
\index{Objects!definition}
\index{Arc}\index{Box}\index{Line}\index{Polyline}
\index{Ellipse}\index{String}
This section deal about
arcs, boxes, lines, polylines and circles.
Compared to \grace
The \texttt{ELLIPSE} object is replaced by the more general \texttt{ARC}.\\
  Let us define \textit{objtyp}  and \textit{selobj} .
  \begin{table}[htbp]
    \begin{center}
      \begin{tabular}{||l|l|l||} \hline \hline
        Name           &  Values &  Remarks \\  \hline \hline
        \textit{objtyp}&  ARC, BOX, LINE ,POLYLINE ,STRING &   \\ \hline
        \textit{selobj}&  \textit{objtyp  id}    &  for update \\ \hline
        \hline
      \end{tabular}
    \end{center}
    \caption{\textit{objtyp} and \textit{selobj} definition}
    \label{selobj}
  \end{table}

  These non terminal symbols can be used to create new objects, make
  an object current or update objects parameters.
  \begin{table}[htbp]
    \begin{center}
      \begin{tabular}{||l|l|l||}
        \hline \hline
        Command &  Action &  Example \\
        \hline \hline
        WITH \textit{objtyp} & Creates a new object                    & \texttt{WITH Line} \\ \hline
        WITH \textit{selobj} & The object \textit{id} is made  current & \texttt{WITH Box 2}\\ \hline
       \hline
      \end{tabular}
    \end{center}
    \caption{WITH command}
    \label{objwith}
  \end{table}
  N.B. 
  \begin{itemize}
  \item 
    Some parameters have no meaning when used with some values of
    \textit{selobj}, but they will be accepted by the interpreter without
    any message.
  \item 
    Some old \grace commands with $objtyp$ in place of $selobj$ are
    not in the table but are still working.
  \end{itemize}

Commands are summarized in table \ref{geom1}.
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{||T|p{5cm}|l||*{5}{c|}|}
      \hline \hline
      &&& \multicolumn{5}{|c||}{$selobj$} \\  \cline{4-8} 
      Command &  Description & Remarks 
      & \Vcol{A\\r\\c} 
      & \Vcol{B\\o\\x} 
      & \Vcol{L\\i\\n\\e} 
      & \Vcol{P\\o\\l\\y}
      & \Vcol{S\\t\\r\\i\\n\\g}
      \\
      \hline%                      % A   B   L   P   S
      $selobj$ : $x1 ,y1 ,x2 ,y2$              &  Object coordinates 
                                                  &  the : is needed 
                                   & x & x & x & x &   \\ \cline{3-3}
      $selobj$ ANCHOR $x1 ,y1 $              & &
                                   &   &   &   &   & x \\ \hline
      $selobj$ "the string itself"          &  &
                                   &   &   &   &   & x \\
      $selobj~sexpr$                           & Name of the object &
                                   & x & x & x & x &   \\ \hline\hline
      $selobj$ ARROW $n$                       &  0:no arrows, 1:at start, 2:end, 3:both &
                                   & x &   & x & x &   \\
      $selobj$ ARROW LENGTH $length$           &   &
                                   & x &   & x & x &   \\
      $selobj$ ARROW TYPE $type$               &   &
                                   & x &   & x & x &   \\
      $selobj$ ARROW LAYOUT $a , b$            &   &
                                   & x &   & x & x &   \\ \hline
      $selobj$ CHAR SIZE $size$             &  &
                                   &   &   & x &   & x \\ \hline
      $selobj$ COLOR $color$                   &   &
                                   & x & x & x & x & x \\ \hline
      $selobj$ FILL COLOR $color$              &   &
                                   &   & x &   &   & x \\
      $selobj$ FILL PATTERN $color$            &   &
                                   &   & x &   &   & x \\ \hline
      $selobj$ FONT $n$                     &  Font selection &
                                   &   &   & x &   & x \\ \hline
      $selobj$ HIDDEN $onoff$                  &              &
                                   & x & x & x & x & x \\ \hline
      $selobj$ JUST $n$                        &  justification &
                                   &   &   &   &   & x \\ \hline
      $selobj$ LINESTYLE $style$               &  $style$ 0: no line, 1: continuous, etc &
                                   & x & x & x & x & x \\
      $selobj$ LINEWIDTH $width$               &  &
                                   & x & x & x & x & x \\ \hline
      $selobj$ LOCTYPE $worldview$             &  Object coordinates are in world ones or in view ones &
                                   & x & x & x & x & x \\
      $selobj$ ROT $angle$                     & Rotation & in degrees 
                                   &   &   &   &   & x \\ \hline
      $selobj$ TYPE $n$                        &  Arc subtype&
                                   & x &   &   &   &   \\[2mm] \hline \hline
      NEW COMPOUND $selobj$                    & Create a new compound with  $selobj$ as first element &
                                   & x & x & x & x & x \\ \hline
      COMPOUND $id$ $selobj$                   & Add $selobj$ to compound $id$ &
                                   & x & x & x & x & x \\ \hline
      COMPOUND $id$ HIDDEN $onoff$             &  &
                                   &   &   &   &   &   \\ \hline
      COMPOUND $id$ LOCTYPE  $worldview$       &  &
                                   &   &   &   &   &   \\ \hline
      COMPOUND $id$ BREAK                      & Breaks the compound &
                                   &   &   &   &   &   \\ \hline
      COMPOUND $id$  : $x1 ,y1 ,x2 ,y2$        &
      Object coordinates: up to now only $(x1, y1)$ are used (for translation, $(x2, y2)$ are reserved for scaling)
      & the : is needed
                                   &   &   &   &   &   \\ \hline
      \hline
    \end{tabular}
  \end{center}
  \caption{Commands related to geometrical objects.}
  \label{geom1}
\end{table}

Anyway, you are encouraged to hack the examples files and use the follow-me mode
to write your own scripts. In particular, Fourier examples show how to create
sets from formulas.
%%
\clearpage
%%
\section{Details on Fourier transformation in \ggtk}
\label{secFourier}
\subsection{Few words about \fftw}
In short, this package allows one to do non-power-of-2
length FFT's along with the normal ones.  It seems to work
very efficiently for any set length which factors into
$2^a 3^b 5^c 7^d$ for integer $a, b, c, d$. The great feature here
is that set lengths which are powers of 10 (e.g. 1000,
10000) and integer multiples of these (500, 2000, 2500,
5000, etc.) can be computed with no significant penalty
(maybe 20\%) over power-of-2 transforms. Very often, real
datasets come in these sizes, and not in powers of 2.

\subsection{Classical Fourier transformation}
\label{secCF}
\index{Fourier}
Let us define the Fourier integral by
\begin{equation}
  \label{eqFI}
  F(X) \: = \: a \int_{-\infty}^{+\infty} f(x) \: \exp(\pm i c X x) \;  dx
  \quad \Leftrightarrow \quad
  F \: = \: \mathcal{F}^{\pm}_{a,c} \,f,
\end{equation}
where $a$ and $c$ are two real constants and $i^2=-1$.
Various values for the two
constants and the sign in the exponential are commonly used.
\subsection{Discrete Fourier Transform}
\label{secDFT}
The discrete Fourier transform (DFT) is defined in FFTW library by
\begin{equation}
  \label{eqDFT}
  \tilde F_k \: = \: \sum_{j=0}^{N-1} f_j
  \: \exp\left( \pm i 2 \pi \, \frac{k}{N} \: j \right).
\end{equation}
Let us identify (\ref{eqDFT}) with a discrete computation of
(\ref{eqFI}) for a function $\tilde f$ null outside $[0,N-1]$,
with $f_j = \tilde f(j)$ and $\tilde X_k = k/N$:
\begin{equation}
  \label{eqFt}
  \tilde F(\tilde X) \: = \: \int_{-\infty}^{+\infty} \tilde f(\tilde x)
  \exp\left( \pm i 2 \pi  \: \tilde X \tilde x \right)
  \: d\tilde x.
  \quad \Leftrightarrow \quad
  \tilde F = \mathcal{F}^{\pm}_{1,2\pi} \,\tilde f
\end{equation}
Let us now connect $\tilde F$ to the wanted transform $F$.\\
Noting $  x = A + b \, \tilde x, \quad b>0\;$
and substituting $\tilde x$ to $x$ into (\ref{eqFI}), we get
\begin{eqnarray}
  F(X) &=&  a \int_{-\infty}^{+\infty}  f(A+b\tilde x)
  \:  \exp[\pm i c X ( A + b \, \tilde x)] \:  b \, d\tilde x
  \\
  \label{eqFtx}
  &=& ab\: \exp(\pm i c A X)
  \int_{-\infty}^{+\infty} \tilde f(\tilde x)
  \:  \exp(\pm i b c X \, \tilde x) \:  d\tilde x
\end{eqnarray}
We can identify (\ref{eqFt}) with the integral in (\ref{eqFtx})
if $b c X \equiv 2 \pi  \: \tilde X$.\\
Thus,
\begin{equation}
  \label{eqFtF}
  X_k = \frac{2 \pi}{bc} \: \frac{k}{N}
  \quad \Rightarrow \quad
  F(X_k) \: = \: ab\: \exp(\pm i c A X_k) \: \tilde F_k
\end{equation}
For a function $f$ null outside $[A,B]$, the coefficient $b$ is given by
\begin{displaymath}
  B = A + b(N-1)
\quad \Rightarrow \quad
b = (B-A) / (N-1).
\end{displaymath}
%%
\subsection{Fourier transform in \texttt{GraceGTK}}
\subsubsection{Choice of parameters}
\texttt{GraceGTK} interface gives the following choices.
\begin{itemize}
\item
  \textit{Forward} transform: the sign in the exponential is minus.
\item
 \textit{Backward} transform: the sign in the exponential is plus.
\item
  \textit{Input segment}: as explain above, classical Fourier
  transforms and DFT are related but not identical. If you choose
  \begin{itemize}
  \item
    \textit{Index}, you compute only the DFT,
  \item
    \textit{[Xmin ,Xmax]}, you compute the classical Fourier transform
  \end{itemize}
\item
  $X$-scale: allows to choose $a$ and $c$ in formula (\ref{eqFI}):
  \begin{itemize}
  \item
    \textit{index} means $a = 1, \; c = 1$,
  \item
    \textit{frequency} means $a = 1, \; c = 2 \pi$
  \item
    \textit{angular frequency} means $a = 1/\sqrt{2 \pi}, \; c=1$.
  \end{itemize}
\item
  \textit{Output segment}~\\
  The DFT is periodical, i.e. $\tilde F_{k+N} = \tilde F_k$, thus it
  is possible to choose the abscissas interval for the computed
  transform.
  Moreover, the transform of a real function shows the Hermitian
  symmetry, i.e. $\tilde F_{N-k} = \tilde F_k^*$ and in that case the full
  period is not needed, thus the program offers three possible answers:
  \textit{``Positive'', "Positive half length"} and \textit{"Centered"}.
\end{itemize}
\subsubsection{Call in \texttt{GraceGTK} scripts}
\label{fftCommands}
Three forms are possibles, the first is not compatible with Grace-5.
\begin{enumerate}
\item
  \texttt{FFT(set ,intyp ,filter ,xscale ,outtyp ,outseg)}
\item
  \texttt{FFT(set ,intyp ,filter ,xscale ,outtyp)}
\item
  \texttt{FFT(set ,filter)}
\end{enumerate}
The arguments are:
\begin{itemize}
\item
  \texttt{set}: the set ident, e.g. \texttt{G1.S0}
\item
  \texttt{intyp}: \texttt{REAL} or \texttt{COMPLEX}
\item
  \texttt{filter}: \texttt{NONE, TRIANGULAR, WELCH, HANNING, HAMMING} or \texttt{PARZEN}
\item
  \texttt{xscale}: \texttt{INDEX, FREQUENCY} or \texttt{PERIOD}
\item
  \texttt{outtyp}: \texttt{MAGNITUDE, PHASE, COEFFICIENTS} or \texttt{COMPLEX}
\item
  \texttt{outseg}: \texttt{POSITIVE, HALF} or \texttt{CENTER}
\end{itemize}
%%
\subsubsection{Examples}
Two examples are given in doc/examples directory:
\begin{center}
\texttt{ng\_fourier.agr} and \texttt{ng\_fourier2.agr}
\end{center}
and can be launched via \texttt{Examples GraceGTK} menu.
%%
\subsection{\fftw  tuning}
\label{fftw-tuning}
\index{Fourier!FFTW}\index{FFTW}
%%
When the \fftw capabilities are compiled in, Grace looks at two environment
variables to decide what to do with the \fftw 'wisdom' capabilities.
First, a quick summary of what this is. The FFTW package is capable of
adaptively determining the most efficient factorization of a set to give
the fastest computation.  It can store these factorizations as 'wisdom',
so that if a transform of a given size is to be repeated, it does not
have to re-adapt.  The good news is that this seems to work very well.
The bad news is that, the first time a transform of a given size is
computed, if it is not a sub-multiple of one already known, it takes a LONG
time (seconds to minutes).

The first environment variable is \verb+GRACE_FFTW_WISDOM_FILE+.
\begin{itemize}
\item
  If this is set to the name of a file which can be read and written
  (e.g., \verb+$HOME/.grace_fftw_wisdom+)%%$ 
  then Grace will automatically create this file (if needed) and
  maintain it.
\item
  If the file is read-only, it will be read,
  but not updated with new wisdom.
\item
  If the symbol \verb+GRACE_FFTW_WISDOM_FILE+
  either doesn't exist, or evaluates to an empty string, Grace will drop the
  use of wisdom, and will use the fftw estimator
  (\verb+FTW_ESTIMATE+ flag sent to the planner)
  to guess a good factorization, instead of adaptively
  determining it.
\end{itemize}
The second variable is \verb+GRACE_FFTW_RAM_WISDOM+.
If this variable is defined
to be non-zero, and \verb+GRACE_FFTW_WISDOM_FILE+ variable is not
defined (or is an empty string),
Grace will use wisdom internally, but maintain no
persistent cache of it. This will result in very slow execution times the
first time a transform is executed after Grace is started, but very fast
repeats. I am not sure why anyone would want to use wisdom without
writing it to disk, but if you do, you can use this flag to enable it.
%%
%% ............................
\section{Wavelet transformations in \ggtk}
%% ............................
\label{secWavelet}
\index{Wavelet}
The code is based on the GNU Scientific Library (GSL)
\url{ http://www.gnu.org/software/gsl/}.
If the library is not installed, a bundled small part of the library
is used.
The first subsection reproduce here the introductory section of 
GSL documentation. 
\subsection{Continuous and discrete wavelet transforms}
The continuous wavelet transform and its inverse are defined by
the relations,
\begin{displaymath}
  w(s, \tau) = \int_{-\infty}^\infty f(t) * \psi^*_{s,\tau}(t) dt  
\end{displaymath}
and
\begin{displaymath}
  f(t) = \int_0^\infty ds \int_{-\infty}^\infty w(s, \tau) * \psi_{s,\tau}(t) d\tau
\end{displaymath}
where the basis functions $\psi_{s,\tau}$ are obtained by scaling
and translation from a single function, referred to as the 
\textit{mother wavelet}.\\
The discrete version of the wavelet transform acts on equally-spaced
samples, with fixed scaling and translation steps $(s,\tau)$.
The frequency and time axes are sampled dyadically
on scales of $2^j$ through a level parameter $j$.
The wavelet $\psi$
can be expressed in terms of a scaling function $\varphi$,
\begin{displaymath}
  \psi(2^{j-1},t) = \sum_{k=0}^{2^j-1} g_j(k) * \bar{\varphi}(2^j t-k) 
\end{displaymath}
and
\begin{displaymath}
  \varphi(2^{j-1},t) = \sum_{k=0}^{2^j-1} h_j(k) * \bar{\varphi}(2^j t-k)
\end{displaymath}
The functions $\psi$ and $\varphi$ are related through the
coefficients
\begin{displaymath}
g_{n} = (-1)^n h_{L-1-n},\qquad g_{n} = (-1)^n h_{L-1-n},
\qquad  n=0 \dots L-1,
\end{displaymath}
where $L$ is the total number of coefficients.  The two sets of
coefficients $h_j$ and $g_i$ define the scaling function and
the wavelet.\\
The centered forms of the wavelets align the coefficients of the various
sub-bands on edges.  Thus the resulting visualization of the
coefficients of the wavelet transform in the phase plane is easier to
understand.\\
More details and references can be found in GSL documentation and
Wikipedia.
Also, the \textit{Numerical recipes} \cite{numrecipes} gives a
comprehensive account on the subject.
%%
\subsection{Wavelets families}
Available families in GSL are the following.
\begin{description}
\item[Daubechies] 
  This is the Daubechies wavelet family of maximum phase with $k/2$
  vanishing moments. 
  See \url{http://en.wikipedia.org/wiki/Daubechies_wavelet}
\item[Haar] Simple, but discontinuous.
  See \url{http://en.wikipedia.org/wiki/Haar_wavelet}
\item[Bspline]
  This is the biorthogonal B-spline wavelet family of order $(i,j)$.
  The $k$ parameter is defined by $k = 100\,i + j$.
\end{description}
%% 
\subsection{Wavelets parameters}
GLS allows only the following values for the wavelet parameter $k$ for
the different families of wavelet:
\begin{description}
\item[Daubechies] $k=4, 6, \dots, 20\qquad$ with $k$ even,
\item[Haar] the only legal value is 2,
\item[Bspline]  $k =  103, 105, 202, 204,
  206, 208, 301, 303, 305, 307, 309$.
\end{description}
%% 
\subsection{Some hints}
\begin{itemize}
\item 
  The main interest of wavelet transforms is to compress the information
  into a small number of coefficients.
  If the wavelet and its parameters are well chosen,
  a dense vector $v$ gives a vector $w$ with a small
  number of significant components.
  In \ggtk, if $v$ has a large number of components, $w$ have the same
  number of components i.e. is also large.
  In order to save only the useful information, 
  selecting the set of wavelet coefficients, you can
  \begin{itemize}
  \item pop up  \verb+ Data/Transformation/Sample points..+ menu,
  \item choose \verb+ Sample type: Expression +
  \item give formula \verb+ y = (abs(y) > xx) ? y : 0; +
    where \verb+xx+ is the  threshold of your choice
  \item and thus create a new set that you can save with 
    \verb+ File/Export ASCII data  +.\\
    The abscissas of the new set are the index of the components above
    threshold, and the ordinates the significant components of $w$.
  \end{itemize}
\item 
  Beware that the abscissa range for the transformed set is the index 
  and that the $x$ scale is often different from the one of the
  original data.
  Thus creating a new graph and moving the coefficients to this graph
  is often a good option.
\item 
  Remember also  that 
  if you wont to retrieve the original data with same scale by backward
  transformation, you will have to rescale abscissas properly.
\item 
  If your data have not $2^j$ points, 
  it is possible (but not very satisfactory) to
  interpolate it on a regular mesh before taking the wavelet transform.
\end{itemize}
%% 
\subsection{Call in \texttt{GraceGTK} scripts}
\label{waveletCall}
The following function creates a new set with the wavelet coefficients:\\
\verb+ WAVELET (+$set ,type ,stride ,k ,invflag$\verb+) +\\
where
\begin{description}
\item[$set$] is the set selector for the input vector (e.g. \verb+ G0.s0+ ),
\item[$type$] is one of the following\\
\texttt{DAUBECHIES, DAUBECHIES\_CENTERED, HAAR, HAAR\_CENTERED, 
  BSPLINE, BSPLINE\_CENTERED},
\item[$stride$] is the stride to use in the input data vector (1 means all
  the components)
\item[$k$] is the parameter described above,
\item[$invflag$] 0: forward, 1: backward transform.
\end{description}
Example : \verb+ @ WAVELET (s_ ,DAUBECHIES ,1 ,4 ,0 ,0) +
%%
%% ............................
\section{Advanced topics}
%% ............................
\subsection{Fonts}
\label{fonts}
\index{Fonts}
%% ............................
\subsubsection{Font configuration}
The file responsible for the font configurations of Grace is
\texttt{ fonts/FontDataBase}. The first line contains a positive integer
specifying the number of fonts declared in that file. All remaining lines
contain declarations of one font each, composed out of three fields:
\begin{enumerate}
\item
  Font name. The name will appear in the font selector controls.
  Also, backend devices that has built-in fonts, will be given the
  name as a font identifier.
\item
  Font fall-back. Grace will try to use this in case the real
  font is not found.
\item
  Font filename. The file with the font outline data.
\end{enumerate}
Here is the default \texttt{FontDataBase} file:
\begin{verbatim}
14
Times-Roman             Times-Roman             n021003l.pfb
Times-Italic            Times-Italic            n021023l.pfb
Times-Bold              Times-Bold              n021004l.pfb
Times-BoldItalic        Times-BoldItalic        n021024l.pfb
Helvetica               Helvetica               n019003l.pfb
Helvetica-Oblique       Helvetica-Oblique       n019023l.pfb
Helvetica-Bold          Helvetica-Bold          n019004l.pfb
Helvetica-BoldOblique   Helvetica-BoldOblique   n019024l.pfb
Courier                 Courier                 n022003l.pfb
Courier-Oblique         Courier-Oblique         n022023l.pfb
Courier-Bold            Courier-Bold            n022004l.pfb
Courier-BoldOblique     Courier-BoldOblique     n022024l.pfb
Symbol                  Symbol                  s050000l.pfb
ZapfDingbats            ZapfDingbats            d050000l.pfb
\end{verbatim}
%%
\subsubsection{Font data files}
For text rastering, three types of files are used.
\begin{enumerate}
\item  \texttt{.pfa}-/\texttt{.pfb}-files: These contain the character
  outline descriptions. The files are assumed to be in the
  \texttt{fonts/type1} directory; these are the filenames
  specified in the \texttt{FontDataBase} configuration file.
\item  \texttt{.afm}-files: These contain high-precision font metric
  descriptions as well as some extra information, such as kerning
  and ligature information for a particular font. It is assumed
  that the filename of a font metric file has same basename as the
  respective font outline file, but with the \texttt{.afm} extension; the metric files are expected to be found in the
  \texttt{fonts/type1} directory, too.
\item  \texttt{.enc}-files: These contain encoding arrays in a special
  but simple form. They are only needed if someone wants to load
  a special encoding to re-encode a font. Their place is
  \texttt{fonts/enc}
\end{enumerate}
%%
\subsubsection{Custom fonts}
It is possible to use custom fonts with Grace. One mostly needs to use
extra fonts for the purpose of localization. For many European
languages, the standard fonts supplied with Grace should contain all the
characters needed, but encoding may have to be adjusted. This is done by
putting a \texttt{Default.enc} file with proper encoding scheme into the
\texttt{fonts/enc} directory. Grace comes with a few encoding files in
the directory; more can be easily found on the Internet. (If the
\texttt{Default.enc} file doesn't exist, the IsoLatin1 encoding will be
used). Notice that for fonts having an encoding scheme in themselves
(such as the Symbol font, and many nationalized fonts) the default
encoding is ignored.

If you do need to use extra fonts, you should modify the
\texttt{FontDataBase} file accordingly, obeying its format. However,
if you are going to exchange Grace project files with other people who
do not have the extra fonts configured, an important thing is to define
reasonable fall-back font names.

For example, let us assume I use Hebrew fonts, and the configuration file
has lines like these:
\begin{verbatim}
    ...
Courier-Hebrew              Courier                 courh___.pfa
Courier-Hebrew-Oblique      Courier-Oblique         courho__.pfa
    ...

\end{verbatim}
 My colleague, who lives in Russia, uses Cyrillic fonts with Grace
configured like this:
\begin{verbatim}
    ...
Cronix-Courier              Courier                 croxc.pfb
Cronix-Courier-Oblique      Courier-Oblique         croxco.pfb
    ...

\end{verbatim}
 The font mapping information (Font name $<$-$>$ Font fall-back) is
stored in the Grace project files. Provided that all the localized fonts
have English characters in the lower part of the ASCII table unmodified,
I can send my friend files (with no Hebrew characters, of course) and be
sure they render correctly on his computer.

Thus, with properly configured national fonts, you can make localized
annotations for plots intended for internal use of your institution,
while being able to exchange files with colleagues from abroad. People
who ever tried to do this with MS Office applications should appreciate
the flexibility :-).
%%
\subsubsection{\ggtk internal encoding}
GTK API assume a UTF-8 encoding and \grace programming is Latin1 by
default thus, the strings are converted back and forth between the two
when displayed through a GTK widget\footnote{Except of course for the
  canvas where characters are drawn through T1lib library.}.
Note that only strings that are normally drawn on the canvas and can
contains non ASCII characters are concerned.
This can produce strange results if you use a different coding scheme.\\
The font tool use a workaround: character in the 128-255 range are
coded with their number (e.g. \verb+ \#{e0} + ) and decoded by the
command interpreter.
%% ............................
\subsection{Interaction with other applications}
%%
\subsubsection{Using pipes}
\index{pipes}
Not finished \dots
%%
\subsubsection{Using grace\_np library}
The grace\_np library is a set of compiled functions that
allows you to launch and drive a Grace subprocess from your C or
Fortran application. Functions are provided to start the
subprocess, to send it commands or data, to stop it or detach
from it.\\
See table \ref{C-functions} for a list of C functions.\\
See table \ref{fortran-functions} for a list of Fortran functions.\\
%%
\begin{table}[htbp]
  \hrulefill
    \begin{description}
      \item [\texttt{int GraceOpenVA (char *\textit{exe}, int \textit{buf\_size}, ...)}]~\\
        launch a Grace executable \textit{exe} and open a
        communication channel with it using \textit{buf\_size} bytes
        for data buffering. The remaining \texttt{NULL}-terminated list of
        options is command line arguments passed to the Grace process
      \item [\texttt{int GraceOpen (int \textit{buf\_size})}]~\\
        equivalent to \texttt{GraceOpenVA("ggrace", buf\_size, "-nosafe", "-noask", NULL)}
      \item [\texttt{int GraceIsOpen (void)}]~\\
        test if a Grace subprocess is currently connected
      \item [\texttt{int GraceClose (void)}]~\\
        close the communication channel and exit the Grace subprocess
      \item [\texttt{int GraceClosePipe (void)}]~\\
        close the communication channel and leave the Grace subprocess alone
      \item [\texttt{int GraceFlush (void)}]~\\
        flush all the data remaining in the buffer
      \item [\texttt{int GracePrintf (const char* \textit{format}, ...)}]~\\
        format a command and send it to the Grace subprocess
      \item [\texttt{int GraceCommand (const char* \textit{cmd})}]~\\
        send an already formated command to the Grace subprocess
      \item [\texttt{GraceErrorFunctionType GraceRegisterErrorFunction (GraceErrorFunctionType \textit{f}) }]~\\
        register a user function \textit{f} to display library errors
    \end{description}
    \hrulefill
  \caption{grace\_np library C functions.}
  \label{C-functions}
  \index{C}\index{grace\_np}\index{library}
\end{table}
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{P{5cm}lp{5cm}}
      \hline
      Function &  Arguments &  Description \\
      \hline
      integer GraceOpenF &  (integer \textit{buf\_size})&  launch a Grace subprocess and open a communication channel with it \\
      integer GraceIsOpenF &  (void) &  test if a Grace subprocess is currently connected \\
      integer GraceCloseF &  (void) &  close the communication channel and exit the Grace subprocess \\
      integer GraceClosePipeF &  (void) &  close the communication channel and leave the Grace subprocess alone \\
      \hline
      integer GraceFlushF &  (void) &  flush all the data remaining in the buffer \\
      integer GraceCommandF &  (character*(*) \textit{cmd})&  send an already formatted command to the Grace subprocess \\
      \hline
      GraceFortranFunctionType GraceRegisterErrorFunctionF&  (GraceFortranFunctionType \textit{f})&  register a user function \textit{f} to display library errors \\
      \hline
    \end{tabular}
  \end{center}
  \caption{grace\_np library F77 functions.}
  \label{fortran-functions}
  \index{Fortran}
\end{table}
There is no Fortran equivalent for the GracePrintf function,
you should format all the data and commands yourself before
sending them with GraceCommandF.

The Grace subprocess listens for the commands you send and
interprets them as if they were given in a batch file. You can
send any command you like (redraw, autoscale, ...). If you want
to send data, you should include them in a command like "g0.s0
point 3.5, 4.2".

Apart from the fact it monitors the data sent via an anonymous
pipe, the Grace subprocess is a normal process. You can interact
with it through the GUI. Note that no error can be sent back to
the parent process. If your application send erroneous commands,
an error popup will be displayed by the subprocess.

If you exit the subprocess while the parent process is still
using it, the broken pipe will be detected. An error code will
be returned to every further call to the library (but you can
still start a new process if you want to manage this situation).
\clearpage
Here is an example use of the library, you will find this
program in the distribution.
\begin{verbatim}
#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>
#include <grace_np.h>

#ifndef EXIT_SUCCESS
#  define EXIT_SUCCESS 0
#endif

#ifndef EXIT_FAILURE
#  define EXIT_FAILURE -1
#endif

void my_error_function(const char *msg)
{
    fprintf(stderr, "library message: \"%s\"\n", msg);
}

int
main(int argc, char* argv[])
{
    int i;

    GraceRegisterErrorFunction(my_error_function);

    /* Start Grace with a buffer size of 2048 and open the pipe */
    if (GraceOpen(2048) == -1) {
        fprintf(stderr, "Can't run Grace. \n");
        exit(EXIT_FAILURE);
    }

    /* Send some initialization commands to Grace */
    GracePrintf("world xmax 100");
    GracePrintf("world ymax 10000");
    GracePrintf("xaxis tick major 20");
    GracePrintf("xaxis tick minor 10");
    GracePrintf("yaxis tick major 2000");
    GracePrintf("yaxis tick minor 1000");
    GracePrintf("s0 on");
    GracePrintf("s0 symbol 1");
    GracePrintf("s0 symbol size 0.3");
    GracePrintf("s0 symbol fill pattern 1");
    GracePrintf("s1 on");
    GracePrintf("s1 symbol 1");
    GracePrintf("s1 symbol size 0.3");
    GracePrintf("s1 symbol fill pattern 1");

    /* Display sample data */
    for (i = 1; i <= 100 && GraceIsOpen(); i++) {
        GracePrintf("g0.s0 point %d, %d", i, i);
        GracePrintf("g0.s1 point %d, %d", i, i * i);
        /* Update the Grace display after every ten steps */
        if (i % 10 == 0) {
            GracePrintf("redraw");
            /* Wait a second, just to simulate some time needed for
               calculations. Your real application shouldn't wait. */
            sleep(1);
        }
    }

    if (GraceIsOpen()) {
        /* Tell Grace to save the data */
        GracePrintf("saveall \"sample.agr\"");

        /* Flush the output buffer and close Grace */
        GraceClose();

        /* We are done */
        exit(EXIT_SUCCESS);
    } else {
        exit(EXIT_FAILURE);
    }
}
\end{verbatim}
%%
\hrulefill\\
To compile this program, type
\begin{verbatim}
 cc example.c -lgrace_np
\end{verbatim}
 If Grace wasn't properly installed, you may need to instruct the
compiler about include and library paths explicitly, e.g.
\begin{verbatim}
 cc -I/usr/local/grace/include example.c -L/usr/local/grace/lib -lgrace_np
\end{verbatim}
%%
%% ............................
\subsection{DL modules }
\label{dl-modules}
\index{Functions!loading}
\index{Dynamic libraries}
Grace can access external functions present
in either system or third-party shared libraries or modules
specially compiled for use with Grace.
\subsubsection{Function types}
One must make sure, however, that the external function is of one
of supported by Grace types:
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{||T|l||}
      \hline
      Grace type &  Description \\
      \hline
      f\_of\_i &  a function of 1 \texttt{int} variable \\
      f\_of\_d &  a function of 1 \texttt{double} variable \\
      f\_of\_nn &  a function of 2 \texttt{int} parameters \\
      f\_of\_nd &  a function of 1 \texttt{int} parameter and 1 \texttt{double} variable \\
      f\_of\_dd &  a function of 2 \texttt{double} variables \\
      f\_of\_nnd &  a function of 2 \texttt{int} parameters and 1 \texttt{double} variable \\
      f\_of\_ppd &  a function of 2 \texttt{double} parameters and 1 \texttt{double} variable \\
      f\_of\_pppd &  a function of 3 \texttt{double} parameters and 1 \texttt{double} variable \\
      f\_of\_ppppd &  a function of 4 \texttt{double} parameters and 1 \texttt{double} variable \\
      f\_of\_pppppd &  a function of 5 \texttt{double} parameters and 1 \texttt{double} variable \\
      \hline
    \end{tabular}
  \end{center}
  \caption{Grace types for external functions}
  \label{grace-types}
\end{table}
%
\subsubsection{Examples}
Caution: the examples provided below (paths and compiler flags)
are valid for Linux/ELF with gcc. On other operating systems,
you may need to refer to compiler/linker manuals or ask a guru.
%%
\paragraph{Example 1}
Suppose I want to use function \texttt{pow(x,y)} from the Un*x math
library (libm). Of course, you can use the "\verb+^+" operator defined
in the Grace language, but here, for the sake of example, we
want to access the function directly.
\\
First run \texttt{ggrace} and open \texttt{Window/Commands}.
Paste the command to make \texttt{pow} accessible:
\begin{verbatim}
@ USE "pow" TYPE f_of_dd FROM "/usr/lib/libm.so"
\end{verbatim}
select the line and "\texttt{Apply}".\\
We can now compare "\texttt{pow}" with "\verb+^+":
paste in the command window:
\begin{verbatim}
@ with g0
@ title "Fonction pow"
@ g0.s0 length 100
@ g0.s0.x = mesh(-2 ,3 ,100)
@ g0.s0.y = x^2
@ g0.s1 length 100
@ g0.s1.x = mesh(-2 ,3 ,100)
@ g0.s1.y = pow(x,2)
@  s1  symbol 8
@  s1  line type 0
@ autoscale
\end{verbatim}
select this sequence  and "\texttt{Apply}".\\
Another method to build sets from functions is to use
\texttt{TreeView/Project/Functions} menu.
%%
\paragraph{Example 2}
Now, let us try to write a function ourselves.\\
We will define function \texttt{my\_function} which simply returns its
(second) argument multiplied by integer parameter transferred as the
first argument.\\
In a text editor, type in the following C code and save it as
"\verb+my_func.c+":
\begin{verbatim}
 double my_function (int n, double x)
 {
     double retval;
     retval = (double) n * x;
     return (retval);
 }
\end{verbatim}
OK, now compile it:
\begin{verbatim}
 gcc -c -fPIC my_func.c
 gcc -shared my_func.o -o /tmp/my_func.so

\end{verbatim}
(You may strip it to save some disk space):
\begin{verbatim}
 strip /tmp/my_func.so
\end{verbatim}
That's all! Ready to make it visible to Grace as "myf" - we are
too lazy to type the very long string "my\_function" many times.
\begin{verbatim}
 USE "my_function" TYPE f_of_nd FROM "/tmp/my_func.so" ALIAS "myf"
\end{verbatim}
%%
\paragraph{Example 3}
A more serious example. There is a special third-party library
available on your system which includes a very important for
you yet very difficult-to-program from the scratch function
that you want to use with Grace.  But, the function prototype
is NOT one of any predefined table \ref{grace-types}.
The solution is to write a simple function wrapper.
Here is how:\\
Suppose, the name of the library is
"\verb+special_lib+"
and the function you are interested in is called
"\verb+special_func+"
and according to the library manual, should be accessed as \\
\verb+void special_func(double *input, double *output, int parameter)+.
\\
The wrapper would look like this:
\begin{verbatim}
 double my_wrapper(int n, double x)
 {
     extern void special_func(double *x, double *y, int n);
     double retval;
     (void) special_func(&x, &retval, n);
     return (retval);
 }
\end{verbatim}
Compile it:
\begin{verbatim}
 gcc -c -fPIC my_wrap.c
 gcc -shared my_wrap.o -o /tmp/my_wrap.so -lspecial_lib -lblas
 strip /tmp/my_wrap.so
\end{verbatim}
Note that I added \texttt{-lblas} assuming that the
\verb+special_lib+ library uses some functions from the BLAS.
Generally, you have to add \textit{all} libraries which your module
depends on (and all libraries those libraries rely upon etc.), as if
you wanted to compile a plain executable.\\
Fine, make Grace aware of the new function
\begin{verbatim}
USE "my_wrapper" TYPE f_of_nd FROM "/tmp/my_wrap.so" ALIAS "special_func"
\end{verbatim}
so we can use it with its original name.
%%
\paragraph{Example 4}
An example of using Fortran\footnote{This example is a little
  out-of-date because Fortran2003 norm introduce a systematic
  interface with C called \texttt{ISO\_C\_BINDING} (and of course
  prefer free form).}
modules.\\
Here we will try to achieve the same functionality as in
Example 2, but with the help of gfortran.
\begin{verbatim}
       DOUBLE PRECISION FUNCTION MYFUNC (N, X)
       IMPLICIT NONE
       INTEGER N
       DOUBLE PRECISION X
C
       MYFUNC = N * X
C
       RETURN
       END
\end{verbatim}
As opposite to C, there is no way to call such a function from
Grace directly - the problem is that in Fortran all arguments
to a function (or subroutine) are passed by reference. So, we
need a wrapper:
\begin{verbatim}
  double myfunc_wrapper(int n, double x)
  {
      extern double myfunc_(int *, double *);
      double retval;
      retval = myfunc_(&n, &x);
      return (retval);
  }
\end{verbatim}
Note that most of f77 compilers by default add underscore to
the function names and convert all names to the lower case,
hence I refer to the Fortran function \verb+MYFUNC+ from my C
wrapper as \verb+myfunc_+, but in your case it can be different!
\\
Let us compile the whole stuff:
\begin{verbatim}
  gfortran -c -fPIC myfunc.f
  gcc -c -fPIC myfunc_wrap.c
  gcc -shared myfunc.o myfunc_wrap.o -o /tmp/myfunc.so -lf2c -lm
  strip /tmp/myfunc.so
\end{verbatim}
And finally, inform Grace about this new function:
\begin{verbatim}
USE "myfunc_wrapper" TYPE f_of_nd FROM "/tmp/myfunc.so" ALIAS "myfunc"
\end{verbatim}
%%
%% ............................
\section{References}
%% ............................
\subsection{Typesetting}
\label{typesetting}
\index{Typesetting}\index{print}\index{DVI}\index{LaTeX}
Grace permits quite complex typesetting on a per string basis.
Any string displayed (titles, legends, tick marks,...) may contain
special control codes to display subscripts, change fonts within the
string \textit{etc}.
\\
The escape sequences frequently used can be produced easily with the
\texttt{Font tool} (see section \ref{fonttool}).
\\
More complex output need the use of sequences in table
\ref{control-codes}.
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{Tl}
      \hline
      Control code &  Description \\
      \hline
      $\backslash$f$\{$x$\}$ &  switch to font named "x" \\
      $\backslash$f$\{$n$\}$ &  switch to font number n \\
      $\backslash$f$\{$$\}$ &  return to original font \\
      $\backslash$R$\{$x$\}$ &  switch to color named "x" \\
      $\backslash$R$\{$n$\}$ &  switch to color number n \\
      $\backslash$R$\{$$\}$ &  return to original color \\
      $\backslash$\#$\{$x$\}$ &  treat "x" (must be of even length) as list of hexadecimal char codes \\
      $\backslash$t$\{$xx xy yx yy$\}$ &  apply transformation matrix \\
      $\backslash$t$\{$$\}$ &  reset transformation matrix \\
      $\backslash$z$\{$x$\}$ &  zoom x times \\
      $\backslash$z$\{$$\}$ &  return to original zoom \\
      $\backslash$r$\{$x$\}$ &  rotate by x degrees \\
      $\backslash$l$\{$x$\}$ &  slant by factor x \\
      $\backslash$v$\{$x$\}$ &  shift vertically by x \\
      $\backslash$v$\{$$\}$ &  return to unshifted baseline \\
      $\backslash$V$\{$x$\}$ &  shift baseline by x \\
      $\backslash$V$\{$$\}$ &  reset baseline \\
      $\backslash$h$\{$x$\}$ &  horizontal shift by x \\
      $\backslash$n &  new line \\
      $\backslash$u &  begin underline \\
      $\backslash$U &  stop underline \\
      $\backslash$o &  begin overline \\
      $\backslash$O &  stop overline \\
      $\backslash$Fk &  enable kerning \\
      $\backslash$FK &  disable kerning \\
      $\backslash$Fl &  enable ligatures \\
      $\backslash$FL &  disable ligatures \\
      $\backslash$m$\{$n$\}$ &  mark current position as n \\
      $\backslash$M$\{$n$\}$ &  return to saved position n \\
      $\backslash$dl &  LtoR substring direction \\
      $\backslash$dr &  RtoL substring direction \\
      $\backslash$dL &  LtoR text advancing \\
      $\backslash$dR &  RtoL text advancing \\
      \hline
      $\backslash$x &  switch to Symbol font (same as $\backslash$f$\{$Symbol$\}$) \\
      $\backslash$+ &  increase size (same as $\backslash$z$\{$1.19$\}$ ; 1.19 = sqrt(sqrt(2))) \\
      $\backslash$- &  decrease size (same as $\backslash$z$\{$0.84$\}$ ; 0.84 = 1/sqrt(sqrt(2))) \\
      $\backslash$s &  begin subscripting (same as $\backslash$v$\{$-0.4$\}$$\backslash$z$\{$0.71$\}$) \\
      $\backslash$S &  begin superscripting (same as $\backslash$v$\{$0.6$\}$$\backslash$z$\{$0.71$\}$) \\
      $\backslash$T$\{$xx xy yx yy$\}$ &  same as $\backslash$t$\{$$\}$$\backslash$t$\{$xx xy yx yy$\}$ \\
      $\backslash$Z$\{$x$\}$ &  absolute zoom x times (same as $\backslash$z$\{$$\}$$\backslash$z$\{$x$\}$) \\
      $\backslash$q &  make font oblique (same as $\backslash$l$\{$0.25$\}$) \\
      $\backslash$Q &  undo oblique (same as $\backslash$l$\{$-0.25$\}$) \\
      $\backslash$N &  return to normal style (same as $\backslash$v$\{$$\}$$\backslash$t$\{$$\}$) \\
      \hline
      $\backslash$$\backslash$ &  print $\backslash$ \\
      \hline
      $\backslash$n &  switch to font number n (0-9) (deprecated) \\
      $\backslash$c &  begin using upper 128 characters of set (deprecated) \\
      $\backslash$C &  stop using upper 128 characters of set (deprecated) \\
      \hline
    \end{tabular}
  \end{center}
  \caption{Typesetting control codes.}
  \label{control-codes}
  \index{Fonts}\index{Colors}\index{superscript}\index{underscript}
  \index{escape sequences}
\end{table}
%%
Example:\\
F$\backslash$sX$\backslash$N($\backslash$xe$\backslash$f$\{$$\}$) =
sin($\backslash$xe$\backslash$f$\{$$\}$)$\backslash$\#$\{$b7$\}$e$\backslash$S-X$\backslash$N$\backslash$\#$\{$b7$\}$cos($\backslash$xe$\backslash$f$\{$$\}$)
\\
prints roughly
\begin{displaymath}
       F_x (\epsilon) = \sin(\epsilon).e^{-x}  .\cos(\epsilon)
\end{displaymath}
using string's initial font ( e prints as epsilon from the Symbol font).
\\
Note that an extension named \texttt{dvi2gr} and available on Grace
site can be used to convert some DVI files produced by \LaTeX{}
in Grace strings.
%% ............................
\subsection{Device-specific limitations}
\label{device-limitations}
\index{Devices}\index{Drivers}
Grace can output plots using several device backends. The list of
available devices can be seen (among other stuff) by specifying the
"-version" command line switch.
\begin{itemize}
\item  GTK, PostScript and EPS are full-featured devices
\item
  Cairo PDF, PNG and SVG drivers have no restrictions different from
  the Cairo ones but no specific options are available
  and the output is not at all optimized.
\end{itemize}
The drivers below does not display correctly xycmap sets.
\begin{itemize}
\item  Raster (\grace) drivers (PNM/JPEG/PNG):
  \index{JPEG}\index{PNG}
  \begin{itemize}
  \item  only even-odd fill rule is supported
  \item  patterned lines are not implemented
  \end{itemize}
\item  PDF (PDFlib) driver:
  \index{PDF}
  \begin{itemize}
  \item  bitmapped text strings are not transparent
  \item  PDFlibLite does not display correctly xycmap sets.
  \end{itemize}
\item  MIF driver:
  \begin{itemize}
  \item  some of patterned fills not implemented
  \item  bitmapped text strings not implemented
  \end{itemize}
\item  SVG (\grace) driver:
  \begin{itemize}
  \item  bitmapped text strings not implemented
  \end{itemize}
\end{itemize}
%% ............................
\subsection{Device-specific settings}
\label{device-settings}
%%
Some of the output devices accept several configuration options. You can
set the options by passing a respective string to the interpreter
using the "DEVICE {\itshape "devname"\/} OP {\itshape "options"\/}" command (see
\ref{device-parameters} {(Device parameters)}). A few options
can be passed in one command, separated by commas.
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{Tl}
      \hline
      Command            &  Description \\       \hline
      grayscale          &  set grayscale output \\
      color              &  set color output \\
      level1             &  use only PS Level 1 subset of commands \\
      level2             &  use also PS Level 2 commands if needed \\
      docdata:7bit       &  the document data is 7bit clean \\
      docdata:8bit       &  the document data is 8bit clean \\
      docdata:binary     &  the document data may be binary \\
      xoffset:\textit{x} &  set page offset in X direction \textit{x} pp \\
      yoffset:\textit{y} &  set page offset in Y direction \textit{y} pp \\
      mediafeed:auto     &  default input tray \\
      mediafeed:match    &  select input with media matching page dimensions \\
      mediafeed:manual   &  manual media feed \\
      hwresolution:on    &  set hardware resolution \\
      hwresolution:off   &  do not set hardware resolution \\
      \hline
    \end{tabular}
  \end{center}
  \caption{PostScript driver options}
  \index{PostScript}
  \index{Drivers!PS}
\end{table}
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{Tl}
      \hline
      Command    &  Description \\       \hline
      grayscale  &  set grayscale output \\
      color      &  set color output \\
      level1     &  use only PS Level 1 subset of commands \\
      level2     &  use also PS Level 2 commands if needed \\
      bbox:tight &  enable "tight" bounding box \\
      bbox:page  &  bounding box coincides with page dimensions \\
      \hline
    \end{tabular}
  \end{center}
  \caption{EPS driver options}
  \index{EPS}
  \index{Drivers!EPS}
\end{table}
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{Tl}
      \hline
      Command           &  Description \\       \hline
      PDF1.3            &  set compatibility mode to PDF-1.3 \\
      PDF1.4            &  set compatibility mode to PDF-1.4 \\
      compression:value &  set compression level (0 - 9) \\
      patterns:on       &  enable use of patterns \\
      patterns:off      &  disable use of patterns \\
      \hline
    \end{tabular}
  \end{center}
  \caption{PDF (PDFlib) driver options}
  \index{Drivers!PDF}
\end{table}
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{Tl}
      \hline
      Command     &  Description \\       \hline
      format:pbm  &  output in PBM format \\
      format:pgm  &  output in PGM format \\
      format:ppm  &  output in PPM format \\
      rawbits:on  &  "rawbits" (binary) output \\
      rawbits:off &  ASCII output \\
      \hline
    \end{tabular}
  \end{center}
  \caption{PNM driver options}
  \index{PNM}
  \index{Drivers!PNM}
\end{table}
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{Tl}
      \hline
      Command            &  Description \\       \hline
      grayscale          &  set grayscale output \\
      color              &  set color output \\
      optimize:on/off    &  enable/disable optimization \\
      quality:value      &  set compression quality (0 - 100) \\
      smoothing:value    &  set smoothing (0 - 100) \\
      baseline:on/off    &  do/don't force baseline output \\
      progressive:on/off &  do/don't output in progressive format \\
      dct:ifast          &  use fast integer DCT method \\
      dct:islow          &  use slow integer DCT method \\
      dct:float          &  use floating-point DCT method \\
      \hline
    \end{tabular}
  \end{center}
  \caption{JPEG driver options}
  \index{JPEG}
  \index{Drivers!JPEG}
\end{table}
%%
\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{Tl}
      \hline
      Command           &  Description \\       \hline
      interlaced:on     &  make interlaced image \\
      interlaced:off    &  don't make interlaced image \\
      transparent:on    &  produce transparent image \\
      transparent:off   &  don't produce transparent image \\
      compression:value &  set compression level (0 - 9) \\
      \hline
    \end{tabular}
  \end{center}
  \caption{PNG (\grace) driver options}
  \index{PNG}
  \index{Drivers!PNG}
\end{table}
%% ............................
\subsection{Dates in Grace }
\label{dates}
\index{Dates}
We use two calendars in Grace: the one that was established in
532 by Denys and lasted until 1582, and the one that was created
by Luigi Lilio (Alyosius Lilius) and Christoph Klau
(Christophorus Clavius) for pope Gregorius XIII. Both use the
same months (they were introduced under emperor Augustus, a few
years after Julian calendar introduction, both Julius and
Augustus were honored by a month being named after each one).

The leap years occurred regularly in Denys's calendar: once
every four years, there is no year 0 in this calendar (the leap
year -1 was just before year 1). This calendar was not compliant
with earth motion and the dates were slowly shifting with regard
to astronomical events.

This was corrected in 1582 by introducing Gregorian
calendar. First a ten days shift was introduced to reset correct
dates (Thursday October the 4th was followed by Friday October
the 15th). The rules for leap years were also changed: three
leap years are removed every four centuries. These years are
those that are multiple of 100 but not multiple of 400: 1700,
1800, and 1900 were not leap years, but 1600 and 2000 were (will
be) leap years.

We still use Gregorian calendar today, but we now have several
time scales for increased accuracy. The International Atomic
Time (TAI) is a linear scale: the best scale to use for
scientific reference. The Coordinated Universal Time (UTC, often
confused with Greenwich Mean Time) is a legal time that is
almost synchronized with earth motion. However, since the earth
is slightly slowing down, leap seconds are introduced from time
to time in UTC (about one second every 18 months). UTC is not a
continuous scale ! When a leap second is introduced by
International Earth Rotation Service, this is published in
advance and the legal time sequence is as follows: 23:59:59
followed one second later by 23:59:60 followed one second later
by 00:00:00. At the time of this writing (1999-01-05) the
difference between TAI and UTC was 32 seconds, and the last leap
second was introduced in 1998-12-31.

These calendars allow to represent any date from the mist of the
past to the fog of the future, but they are not convenient for
computation. Another time scale is possible: counting only the
days from a reference. Such a time scale was introduced by
Joseph-Juste Scaliger (Josephus Justus Scaliger) in 1583. He
decided to use "-4713-01-01T12:00:00" as a reference date
because it was at the same time a Monday, first of January of a
leap year, there was an exact number of 19 years Meton cycle
between this date and year 1 (for Easter computation), and it
was at the beginning of a 15 years \textit{Roman indiction} cycle. The day number counted from this reference is
traditionally called \textit{Julian day}, but it has really
nothing to do with the Julian calendar.

Grace stores dates internally as reals numbers counted from a
reference date. The default reference date is the one chosen by
Scaliger, it is a classical reference for astronomical
events. It can modified for a single session using the \ref{preferences} {(Edit-$>$Preferences)} popup of the GUI. If
you often work with a specific reference date you can set it for
every sessions with a REFERENCE DATE command in your
configuration file (see \ref{default-template} {(Default template)}).

The following date formats are supported (hour, minutes and
seconds are always optional):

\begin{enumerate}
\item iso8601  : 1999-12-31T23:59:59.999
\item european : 31/12/1999 23:59:59.999 or 31/12/99 23:59:59.999
\item us       : 12/31/1999 23:59:59.999 or 12/31/99 23:59:59.999
\item Julian   : 123456.789
\end{enumerate}
One should be aware that Grace does not allow to put a space in
one data column as spaces are used to separate fields. You
should always use another separator (:/.- or better T) between
date and time in data files. The GUI, the batch language and the
command line flags do not have this limitation, you can use
spaces there without any problem. The T separator comes from the
ISO8601 standard. Grace support its use also in european and us
formats.

You can also provide a hint about the format ("ISO8601",
"european", "us") using the -datehint command line flag or the
ref name="Edit-{$>$}Preferences" id="preferences"{$>$} popup of the GUI.
The formats are tried in the following order: first the hint
given by the user, then iso, european and us (there is no
ambiguity between calendar formats and numerical formats and
therefore no order is specified for them). The separators
between various fields can be any characters in the set: " :/.-T"
(one or more spaces act as one separator, other characters can
not be repeated, the T separator is allowed only between date and time,
mainly for iso8601), so the string "1999-12 31:23/59" is allowed
(but not recommended).  The '-' character is used both as a
separator (it is traditionally used in iso8601 format) and as
the unary minus (for dates in the far past or for numerical
dates). By default years are left untouched, so 99 is a date far
away in the past. This behavior can be changed with the
\ref{preferences} {(Edit-{$>$}preferences)} popup, or with the
\texttt{DATE WRAP on} and \texttt{DATE WRAP YEAR year}
commands. Suppose for example that the wrap year is chosen as 1950, if
the year is between 0 and 99 and is written with two or less digits,
it is mapped to the present era as follows:

range {[}00 ; 49] is mapped to {[}2000 ; 2049]

range {[}50 ; 99] is mapped to {[}1950 ; 1999]

with a wrap year set to 1970, the mapping would have been:

range {[}00 ; 69] is mapped to {[}2000 ; 2069]

range {[}70 ; 99] is mapped to {[}1970 ; 1999]

this is reasonably Y2K compliant and is consistent with current
use.  Specifying year 1 is still possible using more than two
digits as follows: "0001-03-04" is unambiguously March the 4th,
year 1. The inverse transform is applied for dates written by
Grace, for example as tick labels. Using two digits only for
years is not recommended, we introduce a \textit{wrap year +
100} bug here so this feature should be removed at some
point in the future ...

The date scanner can be used either for Denys's and Gregorian
calendars. Inexistent dates are detected, they include year 0,
dates between 1582-10-05 and 1582-10-14, February 29th of non
leap years, months below 1 or above 12, ...  the scanner does
not take into account leap seconds: you can think it works only
in International Atomic Time (TAI) and not in Coordinated
Unified Time (UTC). If you find yourself in a situation were you
need UTC, a very precise scale, and should take into account
leap seconds ... you should convert your data yourself (for
example using International Atomic Time). But if you bother with
that you probably already know what to do.


%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Developper's section}
Some hints to help to enter into the program.
%% ............................
\subsection{Program structure}
%% ............................
Like its ancestors, \ggtk has a GUI independent \textit{kernel} using
\textit{display drivers} for its output, a \textit{command
  interpreter} to read command files and a GUI.
%% ............................
\subsubsection{The kernel}
The kernel is mainly the same as in \grace but two significant
additions:
\begin{itemize}
\item
  Each drawing element visible in the TreeView correspond to a
  \texttt{QDobject} struct (see \texttt{defines.h}) element
  realised in the  \texttt{objs} array,
\item
  these elements are linked to form a tree and managed by the
  functions defined in \verb+nn_tree.c+ and \verb+ng_objects.c+~.
\end{itemize}
%% ............................
\subsubsection{The display drivers}
One driver is essential: the GTK driver in the
\verb+gg_gtkdrv.c+ file. It is used to draw the project on the
canvas and replace the X11/Motif driver of \grace.
\\
Each driver fills a \verb+Device_entry+ struct
and provides the following drawing functions
\begin{enumerate}
\item
  \texttt{devupdatecmap}: update color map,
\item
  \texttt{devsetfrgbcolor}: added to \grace functions
  allows a direct access to colors without the cmap
  indirection\footnote{Note that not all the drivers have this
    functionality, thus the ability to draw xycolormap sets.}
.
\item
  \texttt{devdrawpixel}: draw one pixel,
\item
  \texttt{devdrawpolyline}: draw a polygon (or polyline),
\item
  \texttt{devfillpolygon}
\item
  \texttt{devdrawarc}: draw an arc of ellipse,
\item
  \texttt{devfillarc}: fill an arc of ellipse,
\item
  \texttt{devputpixmap}: draw a pixmap, i.e. an array of pixels,
\item
  \texttt{devputtext}: draw a string,
\item
  \texttt{devleavegraphics}: finalise the drawing.
\end{enumerate}
Actually, these names are aliases for the local names used in the
drivers files and this aliasing is made effective by a call to
\verb+initgraphics()+ in \verb+drawgraph()+~.\\
The  drivers are registered in \texttt{main}
and GTK driver is initialised by a call to \verb+gg_init()+
in \verb+gg_start_gtk_gui()+ function.\\
The list of drivers is build by the  registering functions listed in
\verb+devlist.h+~.\\
Three \texttt{CAIRO} drivers had been added to old \grace drivers.
They don't need external libraries
(\texttt{CAIRO} is included in GTK) and
allow a correct output of \texttt{XYCMAP}, but are not at all
optimized;
e.g. the \texttt{CAIROpdf} driver don't define local fonts, thus
letters are drawn pixel by pixel using \texttt{T1lib}.\\
A good thing to do should be to switch to Freetype2 fonts, wich
include T1lib fonts and are the natural fonts for \texttt{CAIRO},
but this needs to code a new interface in replacement
of \verb+t1fonts.c+.
%% ............................
\subsubsection{The command interpreter}
A first  parsing done in \verb+uniread()+
separates data from commands, then the commands strings are
passed to \verb+scanner()+ and finally to \verb+parser()+,
defined in \verb+pars.yacc+~.\\
Finally, the parser apply the rules defined in the
grammar rules section of \verb+pars.yacc+
by calling \verb+yyparse()+
%%
%% ............................
\subsection{Filenames}
In order to keep a link with the past, name space is a little messy.
\begin{itemize}
\item
  The names for the old kernel files remains unchanged.
\item
  New kernel files have prefix \verb+nn_+ or \verb+ng_+~.
\item
  Undo/redo and follow-me modes are based on \verb+nn_cmd+ files.
\item
  Motif to GTK transition was made with new GTK files that have
  the Motif name prefixed with \verb+gg_+
  and with some   changes, e.g.:
  \begin{itemize}
  \item \verb+motifutils.c + is splitted in \verb+ gg_gtkutils.c + and \verb+ gg_frame.c+
  \item \verb+xprotos.h -> gg_protos.h+
  \item \verb+xmgrace.c -> gg.c+
  \end{itemize}
  After the transition was achieved, the Motif files had been removed.
\item
  Explorer GTK files have prefix \verb+ge_+
\item
  Custom GtkWidgets that can be used in a more general context
  are prefixed \verb+gw_+~.
\item
  Collective update menus are build using \verb+wu_+ subsystem.
\item
New spline interpolation method  X-splines is in \verb+xsplines.c+ .
\item
  XYCMAP files are \verb+zc.c+ and \verb+zc_contours.c+ .
\end{itemize}
%%
%% ............................
\subsection{Arrays and the drawing tree}
\grace is based on arrays for graphs, sets and objects.
\ggtk keep this structure but add a tree view to it
and gather in array \texttt{objs[]} the various geometric objects. 
\subsubsection{Arrays}
\begin{verbatim}
Drawable   array    struct     struct       element                 Qtype
           name     name       definition   created by
--------------------------------------------------------------------------------
graph      g        graph      graphs.h     realloc_graphs()        Q_Graph
set        g[].p[]  plotarr        "        realloc_graph_plots()   Q_Set
axis       g[].t[]  tickmarks  defines.h    new_graph_tickmarks()   Q_Axis
legend     g[].l    legend         "                                Q_LegendBox
others     objs     QDobject       "        obj_next()
--------------------------------------------------------------------------------
\end{verbatim}
In order to manage the drawables as nodes in a tree, each drawable
is associated to an element in the \texttt{objs} array.
In the \texttt{QDobject} structure, the pointers
\texttt{self ,elder ,brother ,child}
are indexes in array \texttt{objs[]} and managed through the
functions defined in \verb+nn_tree.c+

This heterodox method has some \textit{pros}:
\begin{itemize}
\item
  it allows a smooth transition between the pure array management
  of \grace and the tree view of \ggtk,
\item
  it is more easy to scan all the objects with a simple loop than with
  a tree traversal,
\item
  the debugging is easier.\\
  Running
  \verb+ ./configure --enable-debug --enable-maintainer+\\
  allows to display toolbar buttons to print the tree with its
  pointers and all the \texttt{objs} array.
\end{itemize}
The main \textit{cons} are that you have to manage the synchronisation 
between the arrays and the tree and that, of course, reentrancy is
excluded. \\ 
Note that the tree is a binary tree, thus
a difference is made between \texttt{elder} and \texttt{father}.\\
Note that \verb+g[], p[], obj[]+ are dynamical arrays, i.e. are
reallocated when their size is varied. 
Consequently, addressing their elements through memory pointers is
safe only if you are sure that a reallocation will not occur.
%% 
\subsubsection{Drawing tree}
The drawing tree displayed in the left Explorer has in fact two
instances:
\begin{itemize}
\item the GTK one, managed through the \verb+ge_tree+ widget,
\item the kernel one, coded as a binary
  tree. The low level function are in \verb+ nn_tree.c + file, others
  functions independent from the graphical interface but taking into
  account the \texttt{Qtype} are mainly in
  \verb+ng_objects.c+.
\end{itemize}
%%
%%
\subsection{Miscellaneous}
%%
\subsubsection{Layers}
\index{Layers}
Each leaf of the drawing tree has a layer number.
Actually \verb+Q_Graph+ display 3 drawing elements with a layer number
that does not correspond to a \texttt{objs[]} element
(the frame, the title and the subtitle)
and consequently needs a special management.\\
For \verb+Q_Graph+ and \verb+Q_Compound+ which are nodes but not
leafs, a button is added to collapse all the branch into a single
layer.
%%
\subsubsection{Management of handles}
Handles are used to select objects or points and act on them with the
mouse.
There are three possibilities to attach handles to an object
(or set or graph):
\begin{itemize}
\item to the corner of the bounding box,
\item to the ends of a line, 
\item to each point of the polyline or set,
\end{itemize}
and two ways to grab the item:
\begin{itemize}
\item a click inside the bounding box to edit, move or copy the object,
\item a click on the handle to scale the object or move, delete or add
  a point.
\end{itemize}
For historical reasons, bounding boxes (bb) of graphs, axis ,sets and
legend boxes are not stored in \verb+ objs[].bb+, thus these elements
are all sets to zero.
A unification of bb management is desirable.
%%
\subsubsection{Instantaneous update}
Instantaneous update needs to add callbacks to each spin box,  combo
box, \textit{etc} in the Explorer right panes.
It is obtained by adding  \verb+ if (CB) g_signal_connect (...CB...) +
to utility functions defined in \verb+ gg_frame.c +
The pointer \texttt{CB}
towards the \textit{apply} function of  the concerned right pane
is set  by a call to \verb+ gg_frame_connect() + but,
 when a right pane menu is created or updated, 
 GTK emits signals for elements in the panel:
 to avoid to create a circular dependency, it is necessary to set
 the variable  \verb+ block_instant_update + to \texttt{TRUE}
 when the menu is created or updated.
 This is simpler then use \verb+gtk_signal_handler_block()+ for each
 item in the menu.
%%
\newpage
\bibliography{gracegtk}
%%
\newpage
\addcontentsline{toc}{section}{Index}
\printindex
%%
\end{document}

;;; Local Variables: ***
;;; ispell-local-dictionary: "british" ***
;;; End: ***

