Changeset 3041 in Sophya for trunk/SophyaLib/Manual/piapp.tex

Timestamp:

Jul 20, 2006, 7:12:06 PM (19 years ago)

Author:

ansari

Message:

ecriture documentation piapp pour piapp V4/sophya V2 , Reza 20/7/2006

File:

• trunk/SophyaLib/Manual/piapp.tex (modified) (23 diffs)

trunk/SophyaLib/Manual/piapp.tex

@@ -1 @@
-\documentclass[twoside,11pt]{article}
+\documentclass[twoside,10pt]{article}
 % \usepackage[latin1]{inputenc}
 % \usepackage[T1]{fontenc}
@@ -36 +36 @@
 %}
 
+\newcommand{\rond}{$\bullet \ $}
+\newcommand{\etoile}{$\star \ $}
+\newcommand{\cercle}{$\circ \ $}
+\newcommand{\carre}{$\Box \ $}
+
+%%%% Definition des commandes pour l'aide en ligne
 \newcommand{\piacommand}[1]{
 $\blacksquare$ \hspace{3mm} {\bf \Large #1 } \index{#1} % (Command) 
 }
-
 \newcommand{\piahelpitem}[1]{
 $\square$ \hspace{3mm} {\bf \Large #1 } \index{#1} (Help item) 
 }
+
+\newcommand{\menubar}[1]{\hspace{1mm} \framebox{\it MenuBar::#1} \hspace{1mm}}
 
 \newcommand{\myppageref}[1]{ (p. \pageref{#1} ) }
@@ -65 +72 @@
 \vspace{1cm}
 \begin{center}
-{\bf \Large piapp Version: 3.985 (V\_Mai2005) } 
+{\bf \Large piapp Version: 4.0 (V\_Jul2006) } 
 \end{center}
 \titrebp{5}
@@ -79 +86 @@
 {\bf piapp} (or {\bf spiapp}) is an interactive data analysis 
 and visualization  program. It is based on the {\bf PI} GUI library 
-and the {\bf SOPHYA}
-(or {\bf PEIDA++}) C++ data analysis class library 
-\footnote{see http://www.sophya.org}. 
-This document contains an overview of piapp possibilities as well as 
-a copy of the on-line help (accessible through the menu {\tt File/Help}). 
-Once the SOPHYA/piapp (or PEIDA++/piapp) environment 
-\footnote{ The environment variables {\tt SOPHYABASEREP} (or {\tt EROSBASEREP}),
-{\tt SOPHYACXX} (compiler selector), the shared library path 
-{\tt LD\_LIBRARY\_PATH} and the executable search path {\tt PATH} must
-be defined}
-has been initialized, {\bf piapp} can simply be started on the command
-line. {\tt (s)piapp -h} provides a brief help of the command line 
+and the {\bf SOPHYA} \footnote{see http://www.sophya.org}
+(or {\bf PEIDA++} \footnote{PEIDA++ has been used in EROS software. 
+(http://eros.in2p3.fr). It is not maintained anymore.}) 
+C++ data analysis class library. 
+\par 
+{\bf piapp} is a powerful command oriented tool for visualising and analysing data.
+Its main features are summarised below:
+\begin{itemize}
+\item[\rond] Image, multiple 2D and few 3D representations
+\item[\rond] Highly interactive graphics, with postscript as export format
+\item[\rond] Capability to handle large data sets. Data can be imported and 
+exported in different formats: ASCII, PPF and FITS.
+\item[\rond] Interactive analysis: 2D/3D distributions, histograms, FFT \ldots 
+\item[\rond] Flexible c-shell inspired command interpreter. 
+\item[\rond] Possibility to perform more complex operations in C++, on objects
+managed by the application through the on-the-fly compilation and execution
+of c++ code fragments in piapp. 
+\item[\rond] piapp is a multi-threaded program with separate threads for graphics
+and command execution, ensuring interactive response, even while heavy 
+computation is being performed. In addition, thread safe commands can be executed 
+in separate threads, for taking advantage of multi CPU (or CPU-cores) workstations.
+\item[\rond] The application can be easily extended through modules which can be
+loaded at run time.  
+\end{itemize}
+%%%
+\vspace*{5mm}
+\par
+ {\bf piapp} can simply be started on the command line in a terminal window 
+once the SOPHYA/piapp  environment has been initialised. 
+The environment variables {\tt SOPHYABASE} should contain the directory 
+where SOPHYA/piapp has been installed. the shared library path 
+{\tt LD\_LIBRARY\_PATH} must contain {\tt \$SOPHYABASE /slb} and the 
+current directory {\tt .} and the executable search path {\tt PATH} must
+contain {\tt \$SOPHYABASE /exe}. Refer to the SOPHYA overview manual 
+for more information on SOPHYA directory structure. \\
+It might also be necessary to define the environment variable 
+{\bf PIXKBMOMASK}, used by the libPI.a to map correctly 
+the {\tt <Alt>} key with some X servers (in particular with 
+X11 on MacOS X). \\
+{\tt csh> setenv PIXKBMODMASK 2 }
+\par
+{\tt (s)piapp -h} provides a brief help of the command line 
 arguments. Xtoolkit options can also be specified as command line
-arguments.
+arguments. {\bf spiapp} is the name of SOPHYA/piapp executable, 
+in order to distinguish it from PEIDA/piapp. 
 \begin{verbatim}
 csh> spiapp -h
- PIOPersist::Initialize() Starting Sophya Persistence management service
-SOPHYA Version  1.3 Revision 76 (V_Jun2002) -- Jul 31 2002 12:26:37 cxx
-
- piapp: Interactive data analysis and visualisation program
- Usage: piapp [-nored] [-nosig] [-nosigfpe] [-nosigsegv] [-hidezswin]
-              [-tmpdir TmpDirectory] [-help2tex] [-exec file [args]]
-  -nored : NoRedirect StdOut/StdErr
-  -nosig : Don't catch SigFPE, SigSEGV
-  -nosigfpe -nosigsegv: Don t catch SigFPE / SigSEGV
-  -hidezswin : Hide Zoom/Stat/ColMap window
-  -tmpdir TmpDirectory: defines TMDIR for temporary files
+ SophyaInitiator::SophyaInitiator() BaseTools Init
+ PIOPersist::Initialize() Starting Sophya Persistence management service 
+SOPHYA Version  2.0 Revision 0 (V_Jul2006) -- Jul 18 2006 12:35:58 gcc 3.3 20030304 (Apple Computer, Inc. build 1495)
+
+ piapp: Interactive data analysis and visualisation program 
+ Usage: piapp [-nored] [-termread] [-term] [-hidezswin] [-small] 
+              [-nosig] [-nosigfpe] [-nosigsegv] 
+              [-tmpdir TmpDirectory] [-help2tex] [-exec file [args]] 
+  -nored : Don't redirect stdout/stderr to piapp console
+  -termread : Read commands on terminal (stdin)
+  -term : equivalent to -nored -termread -small 
+  -hidezswin : Hide Zoom/Stat/ColMap window 
+  -small : Create small size main piapp window 
+  -nosig : Don't catch SigFPE, SigSEGV 
+  -nosigfpe -nosigsegv: Don t catch SigFPE / SigSEGV 
+  -tmpdir TmpDirectory: defines TMDIR for temporary files 
   -help2tex: Create a LaTeX help file (piahelp.tex)
-  -exec file [args] : Execute command file
+  -exec file [args] : Execute command file (last option)
 \end{verbatim} 
-Once {\bf piapp} is started, a main window, containing the menu bar, 
-an upper part containing the zoom and colormap window for 
-image displays, memory and CPU usage and a terminal like 
-window in the lower part appears. The figure \ref{figmainwin}
+Once {\bf piapp} is started, the main piapp window appears.
+It contains the menu bar, an upper part with the zoom and colormap 
+widgets for  image displays, memory and CPU usage and a terminal like 
+widget (piapp console, see {\bf PIConsole} \myppageref{PIConsole}) 
+in the lower part. The figure \ref{figmainwin}
 shows an image of the piapp main window.
-\begin{verbatim}
-csh> spiapp 
- PIOPersist::Initialize() Starting Sophya Persistence management service
-SOPHYA Version  1.3 Revision 76 (V_Jun2002) -- Jul 31 2002 12:26:37 cxx
->>>>> Starting piapp <<<<<
-SOPHYA Version  1.3 Revision 76 (V_Jun2002) -- Jul 31 2002 12:26:37 cxx
-Version: piapp=3.55  PI=3.8  SOPHYA=1.376
- --piapp: Creating Tmp Directory: ./PIATmp_aadrPa/
- PIColorMap::PIColorMap(CMapId id) Allocating ColorMap Grey32 ...
- PIColorMap::PIColorMap(CMapId id) Allocating ColorMap InvGrey32 ...
- PIColorMap::PIColorMap(CMapId id) Allocating ColorMap ColRJ32 ...
- registration of contour commands
- registration of flow chart commands
-SOPHYA Version  1.3 Revision 76 (V_Jun2002) -- Jul 31 2002 12:26:37 cxx
-  NamedObjMgr::SetTmpDir()+XNTuple::SetSwapPath() ./PIATmp_aadrPa/
-\end{verbatim}
-
-C++ code can be executed within the piapp application, easing the 
-development and analysis task.
-piapp can handle input data in different formats:
-\begin{itemize}
-\item[\bul] ASCII files (see {\tt ntfrascii} \myppageref{ntfrascii} and 
-{\tt newnt} \myppageref{newnt} command)
-\item[\bul] FITS format files, through menu {\bf File/Open-Fits}. 
-(see also (see {\tt openfits} \myppageref{openfits}) command.
-\item[\bul] PPF (Portable Persistence file Format) files through 
-menu {\bf File/Open-PPF}. PPF files are the native persistence 
-format in Sophya (or PEIDA++). 
-\end{itemize}
-
-The next sections present a quick tour of {\bf piapp}.
+{\tt stdout/cout, stderr/cerr} are redirected to the piapp console and 
+commands can be entered in this widget. It is also possible to keep
+the terminal where piapp was started  for {\tt stdout/stderr} (flag {\tt -nored}).
+It is also possible to have a command reader on  the terminal
+({\tt stdin}), using the flag {\tt -term}. \\[1mm]
+%
+{\bf Warning:} The output redirection uses unix pipes. On Linux, with commands
+producing long outputs, the application may block because of incorrect management
+of pipes. If this happens, use piapp with  {\tt -nored} flag. 
+
+\par 
+In section 2, we present  a quick tour of {\bf piapp}.  
+a brief overview of piapp graphics, supported data formats, interactive
+analysis possibilities, the command interpreter and c++ execution 
+are presented in the following sections. 
+Section \ref{piappcmdref} contains a brief description of all piapp commands 
+and help items. Various interactive control windows are described in appendix.
 
 \vspace*{10mm}
@@ -158 +188 @@
 \newpage
 \section{A Tour of piapp}
+\subsection{Interacting with piapp, getting help}
+Users interact with piapp through commands entered in the piapp-console
+(or the unix terminal), and through the different menus. 
+Some of the possibilities of the piapp-console are described
+in {\bf PIConsole} help item, in the command reference section \myppageref{PIConsole}.
+The description
+of the commands in available online using the help command.
+An online help window can be displayed by \menubar{File / Help}.
+Commands and help items are grouped in categories which can be
+selected using the OptionMenu in the Help window.
+\begin{verbatim}
+Cmd> help func 
+Displays a function y=f(x) (Fills a vector with function values)   
+ Usage: func f(x) xmin xmax [npt graphic_attributes]               
+  Related commands: funcff func2d func2dff   
+Cmd> func sin(x)/x 0.1 10 100 'red line=solid,2'
+---> Graphic display of the function
+\end{verbatim}
+The directory {\tt DemoPIApp} contains a number of example
+command script and sample data files.
+
 \subsection{the Object Manager (NamedObjMgr)}
 The {\bf piapp} application is built around an object manager
@@ -180 +231 @@
 The window {\bf ObjMgr} shown in figure \ref{figobjmgrw} 
 can be used to navigate in the memory directories and 
-execute simple operations on objects. This window 
-can be displayed using the menu command
-Menubar: {\bf Objects/ObjectManager}. 
+execute simple operations on objects. \\ 
+This window can be displayed using the menu command
+\menubar{Objects / ObjectManager}. 
 The button \framebox{\small \bf SetCurObj} can be used to set the value
 of the interpreter's variable {\tt cobj} to the selected 
@@ -199 +250 @@
 
 \subsection{command language}
-A basic command interpreter ({\bf piacmd}) is included in {\bf piapp} and 
+A basic command interpreter ({\bf PIACmd/Commander}) is included in {\bf piapp} and 
 other command interpreters can be inserted in the application 
 framework.
-This interpreter ({\bf piacmd} \myppageref{piacmd}) 
+This interpreter ({\bf Commander} \myppageref{Commander}) 
 synthax is close to the c-shell 
 (csh) shell script. It is possible to define and use variables
@@ -264 +315 @@
 \begin{verbatim}
 Cmd> c++exec c++exec Vector in(1024); \
-Cmd> in = RandomSequence(RandomSequence::Gaussian, 0., 1.); \
-Cmd> for(int kk=0; kk<in.Size(); kk++) \
-Cmd> in(kk) += 2*sin(kk*0.05); \
-Cmd> KeepObj(in);
+...? in = RandomSequence(RandomSequence::Gaussian, 0., 1.); \
+...? for(int kk=0; kk<in.Size(); kk++) \
+...? in(kk) += 2*sin(kk*0.05); \
+...? KeepObj(in);
 \end{verbatim}
 We can of course display the resulting vector:
@@ -278 +329 @@
 \begin{verbatim}
 Cmd> c++exec Vector out(1024); \
-Cmd> int w = 2; \
-Cmd> for(int k=w; k<in.Size()-w; k++) \
-Cmd>   out(k) = in(Range(k-w, k+w)).Sum()/(2.*w+1.); \
-Cmd> KeepObj(out);
+...? int w = 2; \
+...? for(int k=w; k<in.Size()-w; k++) \
+...?   out(k) = in(Range(k-w, k+w)).Sum()/(2.*w+1.); \
+...? KeepObj(out);
 \end{verbatim}
 
@@ -333 +384 @@
 \end{itemize}
 
+%%%%%%%%%% Section 3: Graphiques
 \newpage
 \section{Interactive graphics}
@@ -366 +418 @@
 \end{itemize}
 
-
+%%%%%%%%%%%%%%% Section 4 :   I/O
+\newpage
+\section{Data formats and I/O}
+\begin{itemize}
+\item[\bul] ASCII files (see {\tt ntfrascii} \myppageref{ntfrascii} and 
+{\tt newnt} \myppageref{newnt} command)
+\item[\bul] FITS format files, through \menubar{File/Open-Fits}. 
+(see also (see {\tt openfits} \myppageref{openfits}) command.
+\item[\bul] PPF (Portable Persistence file Format) files through 
+menu \menubar{File/Open-PPF}. PPF files are the native persistence 
+format in Sophya (or PEIDA++). 
+\end{itemize}
+
+%%%%%%%%%%%%%%% Section 5 :   analyse a la paw
+\newpage
+\section{Tables and interactive analysis}
+
+%%%%%%%%%%%%%%% Section 6 :  command interpreter 
+\newpage
+\section{Command interpreter}
+piapp uses the class {\bf PIACmd} which extends slightly the 
+SOPHYA class {\bf Commander} as the command interpreter.
+{\bf Commander} is a  c-shell inspired, string oriented command 
+interpreter.  Although it has many limitations compared to 
+c-shell, or Tcl , it provides some interesting possibilities:
+\begin{itemize}
+\item Extended arithmetic operations (c-like and RPN)
+\item Simple and vector variables
+\item Script definition 
+\item Command execution in separate threads
+\item Dynamic Load 
+\end{itemize}
+
+We describe below  the {\bf Commander} possibilities, 
+as well as the few {\bf PIACmd} extensions. 
+
+\subsection{Variables}
+The SOPHYA::Commander interpreter manages non typed set of variables.
+Environment variables are also accessible through 
+the usual {\tt \$varenvname}, unless shadowed by a Commander 
+variable. All Commander variables are vector of strings, and are 
+extended as necessary.  {\tt \$varname} is the string formed by all 
+the vector elements. Except when performing arithmetic operations,
+variables are treated  as strings. 
+\par 
+An application level set of variables is also managed 
+by Commander, through redefinition of \\
+{\tt Commander::GetVarApp() / GetVarApp() \ldots } methods. 
+The {\bf PIACmd} in piapp redefines the {\tt GetVarApp() }
+in order to provide an easy access to some of objects attributes or methods, 
+managed by {\bf NamedObjMgr}.
+
+\begin{itemize}
+\item[\rond] {\bf Definition and initialisation of variables }  
+\begin{verbatim}
+# Notice that the set command has no = sign 
+Cmd> set sv StringValue
+# Clearing/removing  of a variable : unset or clearvar 
+Cmd> unset sv 
+
+# Definition of a multi element variable (vector type)
+# Notice that spaces before / after '(' and ')' are mandatory 
+Cmd> set vecv ( mot1 mot2 mot3 mot4 mot5 )
+# Arithmetic  expression : C language syntax - spaces before/after '=' are mandatory  Cmd> a = 2+3*sqrt(4)
+# The '=' operator can also be used to initialize a variable with a string
+Cmd> a = 'Bonjour Madame'
+# A vector element can be specified in the left hand side
+Cmd> vecv[2] = 'coucou'
+# Or using an interpreter variable as index :
+Cmd> i = 3
+Cmd> vecv[i] = 'Ooohhh' 
+\end{verbatim}
+
+On the right hand side, the value of a variable should be accessed using 
+the \$ character.  \\
+A string can be parsed  into words using {\tt  var2words}
+\begin{verbatim}
+Cmd> var2words varname wordvarname [separateur]
+\end{verbatim}
+
+\item[\rond] {\bf Accessing variable contents } \\
+The \$ character is used to access the content of a variable {\tt \$varname} .
+Substitution rules : 
+The {\tt \$xxx} is replaced by the value of  variable xxx. 
+No substitution is performed for strings enclosed in simple quotes {\tt ' ... \$xxx '},
+but substitution is done in strings enclosed in double quotes. 
+Parenthesis or brackets can be used to specify the variable name, inside a string
+without white space: {\tt \${vname} } ou {\tt \$(vname)}.
+\begin{verbatim}
+Cmd> x = 'Hello'
+Cmd> echo $x
+# Size of a vector variable : $#vname
+Cmd> set vx ( 111 2222 3333 444444 )
+Cmd> echo $#vx 
+# Accessing vector elements 
+Cmd> echo $vx[0] $vx[1] 
+#  or using an interpreter variable as index :
+Cmd> i = 2
+Cmd> echo $vx[i] 
+# Special syntax:  $[vname] is replaced by the content
+# of a  variable whose name is $vname
+Cmd> zzz = 'Commander'
+Cmd> xxx = 'zzz'
+Cmd> echo '---> $[xxx]= '  $[xxx]
+---> $[xxx]= Commander
+\end{verbatim}
+
+\par
+When brackets are used, the priority level between interpreter variables
+and application level variable is changed. If vname exist at the application level,
+{\tt \${vname} }  is replaced by its value, even if an interpreter variable with the 
+same name has been defined. For some classes managed by NamedObjMgr, 
+PIACmd provide acces to some of the attributes of the object by 
+{\tt \${objname.attname} }. This mechanism has been implemented in particular for
+TArrays, TMatrix/TVector, Histograms, NTuples and DataTables.
+\par
+Environment variables can simply be accessed by {\tt \$varenvname}. 
+However, env. variables have the lowest priority.
+Interpreter's variables have the highest priority in the substitution, followed 
+by the application level variables.
+
+\item[\rond] {\bf Special variables } 
+\begin{itemize}
+\item {\tt \$retval} ou {\tt \$retstr}  :  the string specified in the last {\bf return} statement 
+\item {\tt \$status} : Return code from the last executed command.
+Arguments of scripts (see below) or file executed through {\bf exec} command.
+\item {\tt \$\# } : number of arguments, except \$0 
+\item {\tt \$0}  : Script or file name  
+\item {\tt \$1 \$2 \$3} ....  : Arguments  (for scripts and .pic files (exec))
+\end{itemize}
+\end{itemize}
+ 
+\subsection{Control structures}
+
+\begin{itemize}
+\item[\rond] Enumerated loop:
+\begin{verbatim}
+foreach f ( w1 w2 w3 ... )
+  ...
+  echo $f
+end
+\end{verbatim}
+
+Note that spaces before/after  '(' et and  ')' are mandatory.
+An alternative form uses a vector variable name :
+\begin{verbatim}
+foreach v vecname 
+  ...
+  echo $v
+end
+\end{verbatim}
+
+\item[\rond] Integer type loop:
+\begin{verbatim}
+for i  startInt:endInt[:stepInt]
+  ....
+  echo $i 
+end
+\end{verbatim}
+
+\item[\rond] Integer type loop:
+\begin{verbatim}
+for f  startFloat:endFloat[:stepFloat]
+  ....
+  echo $f
+end
+\end{verbatim}
+
+\item[\rond] Loop over lines of a file 
+\begin{verbatim}
+forinfile line FileName
+  ...
+  echo $line
+end
+\end{verbatim}
+
+\item[\rond] The {\tt break} instruction can be used to exit from a loop 
+
+\item[\rond] {\bf if then else} Conditional execution:
+\begin{verbatim}
+if ( test ) then 
+endif
+
+if ( test ) then
+ ....
+else
+ .... 
+endif
+\end{verbatim}
+Note that spaces before/after  '(' et and  ')' are mandatory.
+
+test is in the form {\tt a == b} OR {\tt a != b} OR {\tt a < b}  OR {\tt a > b} 
+OR {\tt a <= b} OR {\tt a >= b}. Comparison operators should be delimited 
+by spaces.
+{\tt ==} et {\tt !=}  make a string comparison, while
+{\tt < , > , <= , >=} compare the values obtained after string to double conversion.
+\end{itemize}
+
+\subsection{Script definition} 
+A script is a sequence of commands. It is very similar to the execution of commands
+from a file ({\bf exec filename}). Once a script has been defined, it can be called specifying
+specifying the script name followed by its arguments.
+\begin{verbatim}
+#  Script definition :
+defscript scriptname  [description ]
+   ....
+endscript 
+
+#  Executing the script
+Cmd> scriptname arg1 arg2 arg3 ....
+\end{verbatim}
+
+The {\tt return} instruction stops the execution and returns from a script, or from a command
+file called through {\bf exec}. \\
+The commands  {\bf listscript } and  {\bf clearscript scriptname} can be used 
+to obtain the list of already defined script, or to clear a script definition.
+
+\subsection{Other built-in commands}
+\begin{itemize}
+\item[\rond] Instruction {\bf echo } to write the line to cout/stdout
+\item[\rond] Instruction {\bf echo2file} to write (append) the line to file ({\tt echo2file filename ....})
+\item[\rond] Instruction {\bf sleep nsec} wait for {\tt nsec}  seconds
+\item[\rond] Instructions {\bf timingon , timingoff , traceon , traceoff } \\
+%
+\item[\rond] {\bf exec filename [arg1 arg2 ... ] } to execute command from 
+the file named {\tt filename}. {\tt .pic} is the default extension for the interpreter 
+command files. 
+\item[\rond]  {\bf help} and {help keyword/commandname }
+\item[\rond]  {\bf listvars , listcommands } to print the list of defined variables and known
+commands
+\item[\rond]  An alias for a command by {\bf alias aliasname 'string ' }. Alias substitution
+occurs for the first word in a command line. {\bf  listalias} prints the list of all 
+defined aliases. 
+\item[\rond] Execution control (piapp/PIACmd extension):
+It is possible to stop the interpreter execution in a loop, a script or 
+a command file by the {\bf stop} command, or using 
+ {\tt <Cntrl C>} in the piapp console (PIConsole) \\
+\end{itemize} 
+
+\subsection {Command execution in separate threads} 
+It is possible to create new threads to execute commands
+( for non built-in interpreter commands). The syntax is similar 
+to unix shell background tasks: an {\&} should be added at the end
+of the command line.  A new thread is then created for the 
+execution of the command, if declared as thread safe \\
+(see {\tt CmdExecutor::IsThreadable() }. 
+\par
+Thread management commands:
+\begin{itemize}
+\item[\rond] {\bf thrlist }Print current list of threads, with the associated command
+the thread identifier (integer ThrId) and its status.
+\item[\rond] {\bf cleanthrlist } Removes all finished threads from the list.
+An automatic cleanup is performed periodically.
+\item[\rond] {\bf cancelthr ThId } / {\bf killthr ThId } Stops/kills the thread with 
+the identifier ThId. Avoid using theses commands as the cleanup does 
+not release some resources associated with 
+the thread (memory, mutex \ldots). 
+\end{itemize}
+
+%%%%%%%%%%%%%%% Section 7 :  c++ execution
+\newpage
+\section{On the fly C++ execution}
+
+%%%%%%%%%%%%%%% Section 8 :  command reference
 \newpage
 \section{piapp command reference}
@@ -372 +687 @@
 This section contains the description of piapp commands. This information
 is available on-line, through the help command, or through a graphic
-window, accessible  through the menu {\tt File/Help}.
+window, accessible  by \menubar{File / Help}.
 The help items and command are divided into different sections,
 where related commands are grouped. \\[10mm]
@@ -381 +696 @@
 %  La partie des appendix
 \appendix
-
-\newpage
-\section{DrawerTools} \index{DrawerTools}
+\newpage
+\section{Interactive control windows}
+\subsection{DrawerTools} \index{DrawerTools}
 \label{secdrwtools}
 The {\bf PIDrawerTools}, shown in the figure \ref{figdrwtools} can be 
@@ -395 +710 @@
 A given drawer can be selected through the DrawerId selector.
 
-\vspace*{10mm}
+\vspace*{5mm}
 \begin{figure}[ht!]
 \begin{center}
@@ -404 +719 @@
 \end{figure}
 \newpage
-
-\newpage
-\section{AxesTools} \index{AxesTools}
+%%%%
+\subsection{AxesTools} \index{AxesTools}
 \label{secaxestools}
 The {\bf PIAxesTools}, shown in the figure \ref{figaxestools} can be used to 
@@ -415 +729 @@
 the menu {\bf Tools/Show AxesTools}.
 
-\vspace*{10mm}
+\vspace*{5mm}
 \begin{figure}[ht!]
 \begin{center}
@@ -423 +737 @@
 \end{center}
 \end{figure}
-
-\newpage
+%%%%%
 \section{ImageTools} \index{ImageTools}
 \label{secimagetools}
@@ -433 +746 @@
 {\bf Tools/Show ImageTools}.
 
-\vspace*{10mm}
+\vspace*{5mm}
 \begin{figure}[ht!]
 \begin{center}
@@ -442 +755 @@
 \end{figure}
 
-\newpage
-\section{Histo2DTools} \index{Histo2DTools}
+\subsection{Histo2DTools} \index{Histo2DTools}
 \label{sech2dtools}
 The {\bf PIHisto2DTools}, shown in the figure \ref{figh2dtools} can be 
@@ -452 +764 @@
 PIDrawerTools.
 
-\vspace*{10mm}
+\vspace*{5mm}
 \begin{figure}[ht!]
 \begin{center}
@@ -461 +773 @@
 \end{figure}
 
-\newpage
-\section{ContourTools} \index{ContourTools}
+\subsection{ContourTools} \index{ContourTools}
 \label{secconttools}
 The {\bf PIContourTools}, shown in the figure \ref{figconttools} can be 
@@ -486 +797 @@
 by {\bf PIContourTools}. 
 
-\subsection{Drawing options}
+\subsubsection{Drawing options}
 The top choices in {\bf PIContourTools} 
 concern the color map (left choice) or color (right choice) of the contours.
@@ -504 +815 @@
 
 
-\subsection{Contour options}
+\subsubsection{Contour options}
 The contouring routines in {\tt spiapp} are based on a hack of the {\tt GNUPlot} 
 routines. Contours are determined from a grid of values