"Fossies" - the Fresh Open Source Software Archive

Member "grace-5.1.25/doc/UsersGuide.sgml" (14 Feb 2015, 163755 Bytes) of package /linux/misc/grace-5.1.25.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "UsersGuide.sgml": 5.1.24_vs_5.1.25.

    1 <!doctype linuxdoc system>
    2 
    3 <!-- This is the User's Guide for Grace -->
    4 
    5 <article>
    6 
    7 <title>Grace User's Guide (for Grace-5.1.25)</title>
    8 <author>by the Grace Team</author>
    9 <date>15.02.2015</date>
   10 <abstract>
   11   This document explains the usage of
   12   <bf>Grace</bf>, a WYSIWYG 2D plotting tool for numerical data.
   13   (A German translation of this document, made by Tobias Brinkert, is
   14   available here: <url name="Grace Benutzerhandbuch"
   15     url="http://www.semibyte.de/dokuwiki/informatik:linux:xmgrace:grace_benutzerhandbuch">.)
   16 </abstract>
   17 
   18 <toc>
   19 
   20 <!-- **************************************** -->
   21 <sect>Introduction
   22 <p>
   23 
   24 <sect1>What is Grace?
   25   <p>
   26      Grace is a WYSIWYG tool to make two-dimensional plots of numerical
   27      data. It runs under various (if not all) flavors of Unix with X11
   28      and M*tif (LessTif or Motif). It also runs under VMS, OS/2, and
   29      Windows (95/98/NT/2000/XP). Its capabilities are roughly similar to
   30      GUI-based programs like Sigmaplot or Microcal Origin plus
   31      script-based tools like Gnuplot or Genplot. Its strength lies in the
   32      fact that it combines the convenience of a graphical user interface
   33      with the power of a scripting language which enables it to do
   34      sophisticated calculations or perform automated tasks.
   35 
   36      Grace is derived from Xmgr (a.k.a. ACE/gr), originally written by
   37      Paul Turner.
   38 
   39      From version number 4.00, the development was taken over by a
   40      team of volunteers under the coordination of Evgeny Stambulchik.
   41      You can get the newest information about Grace and download the
   42      latest version at the <url
   43      url="http://plasma-gate.weizmann.ac.il/Grace/" name="Grace home page">.
   44 
   45      When its copyright was changed to GPL, the name was changed to Grace,
   46      which stands for ``GRaphing, Advanced Computation and Exploration of
   47      data'' or ``Grace Revamps ACE/gr''. The first version of Grace available
   48      is named 5.0.0, while the last public version of Xmgr has the version
   49      number 4.1.2.
   50 
   51      Paul still maintains and develops a non-public version of Xmgr for
   52      internal use.
   53 
   54 <sect1>Copyright statement
   55   <p>
   56 
   57 <tscreen><verb>
   58 Copyright (&copy;) 1991-1995 Paul J Turner, Portland, OR
   59 Copyright (&copy;) 1996-2014 Grace Development Team
   60 
   61 Maintained by Evgeny Stambulchik
   62 
   63 
   64                          All Rights Reserved
   65 
   66 This program is free software; you can redistribute it and/or modify
   67 it under the terms of the GNU General Public License as published by
   68 the Free Software Foundation; either version 2 of the License, or
   69 (at your option) any later version.
   70 
   71 This program is distributed in the hope that it will be useful,
   72 but WITHOUT ANY WARRANTY; without even the implied warranty of
   73 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   74 GNU General Public License for more details.
   75 
   76 You should have received a copy of the GNU General Public License
   77 along with this program; if not, write to the Free Software
   78 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
   79 </verb></tscreen>
   80 
   81    <p>
   82      For certain libraries required to build Grace
   83      (which are therefore even included in a suitable version)
   84      there may be different Copyright/License statements. Though their
   85      License may by chance match the one used for Grace,
   86      the Grace Copyright holders can not influence or change them.
   87 
   88    <p>
   89    <table loc="htbp">
   90      <tabular ca="ll">
   91        <hline>
   92        Package        |  License  @
   93        <hline>
   94        cephes library |  Free     @
   95        T1lib          |  LGPL     @
   96        Xbae           |  BSD-like @
   97        Tab Widget     |  BSD-like @
   98        <hline>
   99      </tabular>
  100      <caption>
  101        Licenses
  102      </caption>
  103    </table>
  104  <P>
  105 
  106 
  107 <!-- **************************************** -->
  108 <sect>Installation guide
  109   <p>
  110 
  111   <sect1>Installing from sources
  112     <p>
  113       <enum>
  114         <item> Configuration <label id="configuration">
  115         <itemize>
  116           <item> Requirements.
  117                  Grace usually compiles out of the box in a regular Unix-like
  118                  environment. You need an ANSI C compiler (gcc is just fine),
  119                  the X11R5 or above libraries and headers, and an
  120                  implementaion of the M*tif API, version 1.2 or above.
  121                  If you want to compile your own changes to certain parts of
  122                  Grace, you will need a parser generator (<tt/yacc/ or, better,
  123                  <tt/bison/).
  124           <item> Extra libraries. Some features will be available only if
  125                  additional libraries are installed. Those are:
  126             <itemize>
  127               <item> The JPEG backend needs the IJG's
  128                      (<url name="JPEG library" url="ftp://ftp.uu.net/graphics/jpeg/">),
  129                      version 6.x.
  130               <item> The PNG backend needs
  131                      the (<url name="libpng" url="http://www.libpng.org/pub/png/libpng.html">)
  132                      library (version 0.96 or above).
  133               <item> The PDF driver requires the PDFlib library of Thomas
  134                      Merz to be installed, which is available
  135                      <url name="here" url="http://www.pdflib.com/">, version
  136                      4.0.3 or above.
  137               <item> If your computer has the FFTW library installed when
  138                      Grace is compiled, Grace will link itself to this, and
  139                      drop all conventional FFT's and DFT's. All transforms
  140                      will be routed through this package. Note that there is
  141                      then no difference between pushing the "FFT" button and
  142                      the "DFT" button, except that FFT will complain if the
  143                      length isn't a power of 2, and DFT will not.
  144 
  145                      For more information on this package, see the 
  146                      <url name="FFTW Home page" url="http://www.fftw.org">.
  147                      In short, this package allows one to do non-power-of-2
  148                      length FFT's along with the normal ones.  It seems to work
  149                      very efficiently for any set length which factors into 2^a
  150                      3^b 5^c 7^d for integer a, b, c, d. The great feature here
  151                      is that set lengths which are powers of 10 (e.g. 1000,
  152                      10000) and integer multiples of these (500, 2000, 2500,
  153                      5000, etc.) can be computed with no significant penalty
  154                      (maybe 20%) over power-of-2 transforms. Very often, real
  155                      datasets come in these sizes, and not in powers of 2.
  156               <item> In order to read/write sets in the NetCDF data format, you
  157                      will also need the <url name="NetCDF libraries"
  158                      url="http://unidata.ucar.edu/packages/netcdf/index.html">.
  159             </itemize>
  160           <item> Decide whether you want to compile in a separate place (thus
  161                  leaving the source tree pristine). You most probably would
  162                  want it if compiling Grace for more than one OS and keeping
  163                  the sources in a central shared (e.g. via NFS) location.
  164                  If you don't need it, skip the rest of this paragraph and go
  165                  right to the next step. Otherwise, assuming the sources are
  166                  in <tt>/usr/local/src/grace-x.y.z</tt> and the compilation
  167                  will be performed in <tt>/tmp/grace-obj</tt>, do the following:
  168                  <verb>
  169   % mkdir /tmp/grace-obj
  170   % cd /tmp/grace-obj
  171   % /usr/local/src/grace-x.y.z/ac-tools/shtool mkshadow \
  172     /usr/local/src/grace-x.y.z .
  173                  </verb>
  174           <item> The <tt>configure</tt> shell script attempts to guess correct
  175           values for various system-dependent variables used during
  176           compilation. It uses those values to create <tt>Make.conf</tt> in the
  177           top directory of the package. It also create <tt>config.h</tt> file
  178           containing system-dependent definitions. Finally, it creates a shell
  179           script <tt>config.status</tt> that you can run in the future to
  180           recreate the current configuration, a file <tt>config.cache</tt> that
  181           saves the results of its tests to speed up reconfiguring, and a file
  182           <tt>config.log</tt> containing compiler output (useful mainly for
  183           debugging <tt>configure</tt>). If at some point <tt>config.cache</tt>
  184           contains results you don't want to keep, you may remove or edit it.
  185           <item> Run <tt>./configure --help</tt>
  186                  to get list of additional switches specific to Grace
  187           <item> Run <tt>./configure &lt;options&gt;</tt>. Just an example:
  188                  <verb>
  189   % ./configure --enable-grace-home=/opt/grace 
  190     --with-extra-incpath=/usr/local/include:/opt/include \
  191     --with-extra-ldpath=/usr/local/lib:/opt/lib --prefix=/usr
  192                  </verb>
  193                  would use <tt>/usr/local/include</tt> and
  194                  <tt>/opt/include</tt> in addition to the default include path
  195                  and <tt>/usr/local/lib</tt> and <tt>/opt/lib</tt> in addition
  196                  to the default ld path. As well, all stuff would be put under
  197                  the /opt/grace directory and soft links made to
  198                  <tt>/usr/bin</tt>, <tt>/usr/lib</tt> and <tt>/usr/include</tt>.
  199                    <p>
  200                  <bf>Note</bf>: If you change one of the
  201                  <tt>--with-extra-incpath</tt> or
  202                  <tt>--with-extra-ldpath</tt> options from one run of
  203                  configure to another, remember to delete the
  204                  <tt>config.cache</tt> file!!!
  205         </itemize>
  206         <item> Compilation
  207         <itemize>
  208           <item> Issue <tt>make</tt>
  209                    <p>
  210                  If something goes wrong, try to see if the problem has been
  211                  described already in the <bf>Grace FAQ</bf> (in the
  212                  <tt>doc</tt> directory).
  213         </itemize>
  214         <item> Testing
  215     
  216         <itemize>
  217           <item> <tt>make tests</tt>
  218                    <p>
  219                   This will give you a slide show demonstrating some nice
  220                   features of Grace.
  221         </itemize>
  222         <item> Installation
  223         <itemize>
  224           <item> <tt>make install</tt>
  225           <item> <tt>make links</tt>
  226                    <p>
  227                  The later (optional) step will make soft links from some files
  228                  under the Grace home directory to the system-wide default
  229                  locations (can be changed by the <tt>--prefix</tt> option
  230                  during the configuration, see above).
  231         </itemize>
  232       </enum>
  233 
  234   <sect1>Binary installation
  235     <p>
  236        <enum>
  237        <item> Getting pre-built packages
  238        <item> Installation
  239        <item> Running tests
  240        </enum>
  241 
  242   <sect1>Alternative packaging schemes (RPM, ...)
  243     <p>
  244       
  245       Not written yet...
  246 
  247 
  248 <!-- **************************************** -->
  249 <sect>Getting started
  250   <p>
  251 
  252   For a jump-in start, you can browse the demos ("Help/Examples" menu tree).
  253   These are ordinary Grace projects, so you can play with them and modify them.
  254   Also, read the <url name="Tutorial" url="Tutorial.html">.
  255   <p>
  256   O.k. Here's a VERY quick introduction:
  257        <enum>
  258        <item> Start the GUI version: xmgrace (return).
  259        <item> Select/check the output medium and canvas size in File/Device
  260               Setup.
  261        <item> If needed, set the graph size ('Viewport' in
  262               Plot/Graph Appearance).
  263        <item> Load your data with Data/Import/ASCII. 'Load as': 'Single set' for
  264               two-column ASCII data, 'Block data' for multi-column ASCII data.
  265        <item> Adjust the scales, axis labels and tick marks in Plot/Axis
  266               properties. Acknowledge all changes with 'Apply'.
  267        <item> Adjust lines, symbols, legends in Plot/Set appearance.
  268        <item> Adjust titles, plot frame and legend display in Plot/Graph
  269               Appearance.
  270        <item> Data can be manipulated in Data/Transformations. To shift a
  271               data set by 20 to the left, e.g., in 'Evaluate Expression'
  272               select the same set on the left and the right, and say Formula:
  273               y=y-20.
  274               As you'll probably notice, Grace can do MUCH more than that.
  275               Explore at your leisure.
  276        <item> When you like your plot, select File/Print. That's it!
  277        </enum>
  278 
  279   <sect1>General concepts
  280     <p>
  281 
  282       <sect2>Project files <label id="project-file">
  283     <p>
  284 
  285           A project file contains all information necessary to restore a plot
  286           created by Grace, as well as some of preferences. Each plot is
  287           represented on a single page, but may have an unlimited number of
  288           graphs.You create a project file of your current graph with
  289           File/Save,Save as.
  290 
  291       <sect2>Parameter files <label id="parameter-file">
  292     <p>
  293 
  294           A parameter file contains the detailed settings of your project. It
  295           can be used to transfer these settings to a different plot/project.
  296           You generate a parameter file with File/Save menu entry selected
  297           from the "Plot/Graph appearance popup". You can load the settings
  298           contained in a parameter file with File/Open.
  299 
  300       <sect2>Input file formats <label id="files-formats">
  301     <p>
  302 
  303           Grace understands several input files formats. The most basic one
  304           is ASCII text files containing space and comma separated columns
  305           of data. The data fields can be either numeric (Fortran 'd' and
  306           'D' exponent markers are also supported) or alphanumeric (with or
  307           without quotes). Several calendar date formats are recognized
  308           automatically and you can specify your own reference for numeric
  309           date formats. Lines beginnig with "#" are ignored. Blank lines
  310           indicate new dataset.
  311           Grace also has a command language (see <ref
  312           id="command-interpreter" name="command interpreter">), you can
  313           include commands in data files using lines having "@" as their
  314           first non-blank character, though this is not recommended.
  315           Depending on configuration, Grace can also read NetCDF files (see
  316           <ref id="configuration" name="configuration">).
  317 
  318       <sect2>Graphs <label id="graph">
  319     <p>
  320 
  321           A graph consists of (every element is optional): a graph frame, axes,
  322           a title and a subtitle, a number of sets and additional annotative
  323           objects (time stamp string, text strings, lines, boxes and ellipses).
  324 
  325           The graph type can be any of:<label id="graph-types">
  326           <itemize>
  327              <item> XY Graph
  328              <item> XY Chart
  329              <item> Polar Graph
  330              <item> Fixed Graph
  331              <item> Pie chart
  332           </itemize>
  333           
  334           The idea of "XY Chart" is to plot bars (or symbols in general) of
  335           several sets side by side, assuming the abscissas of all the sets are
  336           the same (or subsets of the longest set).
  337 
  338       <sect2>Datasets <label id="datasets">
  339     <p>
  340 
  341           A dataset is a collection of points with x and y coordinates, up to
  342           four optional data values (which, depending on the set type, can be
  343           displayed as error bars or like) and one optional character string.
  344 
  345       <sect2>Sets <label id="sets">
  346     <p>
  347 
  348       A set is a way of representing datasets. It consists
  349           of a pointer to a dataset plus a collection of parameters describing
  350           the visual appearance of the data (like color, line dash pattern etc).
  351 
  352           The set type can be any of the following:
  353         
  354         <p>
  355         
  356           <table loc="htbp">
  357           <tabular ca="lcp{9cm}">
  358             <hline>
  359             Set type   | # of num. cols | Description @
  360             <hline>
  361             XY         | 2 | An X-Y scatter and/or line plot, plus (optionally) an annotated value @
  362             XYDX       | 3 | Same as XY, but with error bars (either one- or two-sided) along X axis @
  363             XYDY       | 3 | Same as XYDX, but error bars are along Y axis @
  364             XYDXDX     | 4 | Same as XYDX, but left and right error bars are defined separately @
  365             XYDYDY     | 4 | Same as XYDXDX, but error bars are along Y axis @
  366             XYDXDY     | 4 | Same as XY, but with X and Y error bars (either one- or two-sided) @
  367             XYDXDXDYDY | 6 | Same as XYDXDY, but left/right and upper/lower error bars are defined separately @
  368             BAR        | 2 | Same as XY, but vertical bars are used instead of symbols @
  369             BARDY      | 3 | Same as BAR, but with error bars (either one- or two-sided) along Y axis @
  370             BARDYDY    | 4 | Same as BARDY, but lower and upper error bars are defined separately @
  371             XYHILO     | 5 | Hi/Low/Open/Close plot @
  372             XYZ        | 3 | Same as XY; makes no sense unless the annotated value is Z @
  373             XYR        | 3 | X, Y,  Radius. Only allowed in Fixed graphs @
  374             XYSIZE     | 3 | Same as XY, but symbol size is variable @
  375             XYCOLOR    | 3 | X, Y, color index (of the symbol fill)@
  376             XYCOLPAT   | 4 | X, Y, color index, pattern index (currently used for Pie charts only) @
  377             XYVMAP     | 4 | Vector map @
  378             XYBOXPLOT  | 6 | Box plot (X, median, upper/lower limit, upper/lower whisker) @
  379             <hline>
  380           </tabular>
  381           <caption>
  382             Set types
  383           </caption>
  384           </table>
  385           
  386         <p>
  387 
  388           Not all set types, however, can be plotted on any graph type. The
  389           following table summarizes it:
  390 
  391         <p>
  392 
  393           <table loc="htbp">
  394           <tabular ca="lccccc">
  395             <hline>
  396             Set type          | XY Graph | XY Chart | Fixed | Polar | Pie @
  397             <hline>
  398             XY                |     +    |    +     |   +   |   +   |  +  @
  399             XYDX              |     +    |    -     |   +   |   -   |  -  @
  400             XYDY              |     +    |    +     |   +   |   -   |  -  @
  401             XYDXDX            |     +    |    -     |   +   |   -   |  -  @
  402             XYDYDY            |     +    |    +     |   +   |   -   |  -  @
  403             XYDXDY            |     +    |    -     |   +   |   -   |  -  @
  404             XYDXDXDYDY        |     +    |    -     |   +   |   -   |  -  @
  405             BAR               |     +    |    +     |   +   |   -   |  -  @
  406             BARDY             |     +    |    +     |   -   |   -   |  -  @
  407             BARDYDY           |     +    |    +     |   -   |   -   |  -  @
  408             XYHILO            |     +    |    -     |   -   |   -   |  -  @
  409             XYZ               |     +    |    -     |   +   |   +   |  -  @
  410             XYR               |     -    |    -     |   +   |   -   |  -  @
  411             XYSIZE            |     +    |    +     |   +   |   +   |  -  @
  412             XYCOLOR           |     +    |    +     |   +   |   +   |  +  @
  413             XYCOLPAT          |     -    |    -     |   -   |   -   |  +  @
  414             XYVMAP            |     +    |    -     |   +   |   -   |  -  @
  415             XYBOXPLOT         |     +    |    -     |   -   |   -   |  -  @
  416             <hline>
  417           </tabular>
  418           <caption>
  419             Graph/Set type connection
  420           </caption>
  421           </table>
  422 
  423 
  424       <sect2>Regions <label id="regions">
  425     <p>
  426 
  427           Regions are sections of the graph defined by the interior or exterior
  428           of a polygon, or a half plane defined by a line. Regions are used to
  429           restrict data transformations to a geometric area occupied by region.
  430 
  431       <sect2>Real Time Input <label id="RTI">
  432     <p>
  433 
  434           Real Time Input refers to the ability Grace has to be
  435           fed in real time by an external program. The Grace
  436           process spawned by the driver program is a full featured
  437           Grace process: the user can interact using the GUI at the
  438           same time the program sends data and commands. The process
  439           will adapt itself to the incoming data rate.
  440 
  441       <sect2>Hotlinks <label id="hotlinks">
  442     <p>
  443 
  444           Hotlinks are sources containing varying data. Grace can be
  445           instructed a file or a pipe is a hotlink in which case it
  446           will provide specific commands to refresh the data on a
  447           mouse click (a later version will probably allow automatic
  448           refresh).
  449 
  450       <sect2>Devices<label id="devices">
  451     <p>
  452           Grace allows the user to choose between several output
  453           devices to produce its graphics. The current list of
  454           supported devices is:
  455 
  456           <itemize>
  457           <item> X11
  458           <item> PostScript (level 1 and level 2)
  459           <item> EPS (encapsulated PostScript)
  460           <item> Metafile (which is Grace format, used at the moment mostly
  461                  for debugging purposes)
  462           <item> MIF (Maker Interchange Format used by FrameMaker)
  463           <item> SVG (Scalable Vector Graphics, a language for describing
  464                  two-dimensional vector and mixed vector/raster graphics
  465                  in XML)
  466           <item> PDF (depends on extra libraries,
  467                       see <ref name="configuration" id="configuration">)
  468           <item> PNM (portable anymap file format)
  469           <item> JPEG (depends on extra libraries,
  470                       see <ref name="configuration" id="configuration">)
  471           <item> PNG (depends on extra libraries,
  472                       see <ref name="configuration" id="configuration">)
  473           </itemize>
  474 
  475         <p>
  476           Note that Grace no longer supports GIF due to
  477           the copyright policy of Unisys. Grace can also be
  478           instructed to launch conversion programs automatically
  479           based on file name. As an example you can produce MIF
  480           (FrameMaker Interchange Format) or Java applets using
  481           pstoedit, or almost any image format using the netpbm suite
  482           (see the <url name="FAQ" url="FAQ.html">).
  483 
  484       <sect2>Magic path<label id="magic-path">
  485     <p>
  486         In many cases, when Grace needs to access a file given with a
  487         relative <tt>pathname</tt>, it searches for the file along the
  488         following path:
  489         <tt>./pathname:./.grace/pathname:~/.grace/pathname:$GRACE_HOME/pathname</tt>
  490 
  491       <sect2>Dynamic modules<label id="dynamic-modules">
  492     <p>
  493         Grace can access external functions present in either system
  494         or third-party shared libraries or modules specially compiled
  495         for use with it. The term dynamic refers to the possibility
  496         Grace has to open the library at run time to find the code of
  497         the external function, there is no need to recompile Grace
  498         itself (the functions already compiled in Grace are
  499         "statically linked").
  500 
  501       <sect2>Coordinate frames <label id="coordinates">
  502 
  503     <p>
  504           There are two types of coordinates in Grace: the <bf>world
  505           coordinates</bf> and the <bf>viewport coordinates</bf>. Points of
  506           data sets are defined in the world coordinates. The viewport
  507           coordinates correspond to the image of the plot drawn on the canvas
  508           (or printed on, say, PS output page). The transformation converting
  509           the world coordinates into the viewport ones is determined by both
  510           the graph type and the axis scaling.
  511     </p>
  512 
  513     <p>
  514           Actually, there is yet another level in the hierarchy of coordinates
  515           - the <bf>device coordinates</bf>. However, you (as a user of Grace)
  516           should not worry about the latter. The mapping between the viewport
  517           coordinates and the device coordinates is always set in such a way
  518           that the origin of the viewport corresponds to the left bottom corner
  519           of the device page, the smallest of the device dimensions corresponds
  520           to one unit in the viewport coordinates. Oh, and the most important
  521           thing about the viewport &rarr; device transformation is that it is
  522           homotetic, i.e. a square is guaranteed to remain a square, not a
  523           rectangle, a circle remains a circle (not an ellipse) etc.
  524     </p>
  525 
  526   <sect1>Invocation
  527     <p>
  528 
  529       <sect2>Operational mode
  530         <p>
  531 
  532           With respect to the user interface, there are three modes of
  533           operation that Grace can be invoked in. The full-featured GUI-based
  534           version is called <tt>xmgrace</tt>. A batch-printing version is
  535           called <tt>gracebat</tt>. A command-line interface mode is called
  536           <tt>grace</tt>. Usually, a single executable is called in all cases,
  537           with two of the three files being (symbolic) links to a "real" one.
  538 
  539       <sect2>Command line options
  540         <p>
  541           <descrip>
  542           <tag> -autoscale <it>x|y|xy</it> </tag>
  543                 Override any parameter file settings
  544 
  545           <tag> -barebones </tag>
  546                 Turn off all toolbars
  547 
  548           <tag> -batch <it>batch_file</it> </tag>
  549                 Execute batch_file on start up (i.e., after all other options
  550                 have been processed and the UI initialized)
  551 
  552           <tag> -block <it>block_data</it> </tag>
  553                 Assume data file is block data
  554 
  555           <tag> -bxy <it>x:y:etc.</it> </tag>
  556                 Form a set from the current block data set using the current set
  557                 type from columns given in the argument
  558 
  559           <tag> -datehint <it>iso|european|us|days|seconds|nohint</it> </tag>
  560                 Set the hint for dates analysis
  561 
  562           <tag> -dpipe <it>descriptor</it> </tag>
  563                 Read data from descriptor (anonymous pipe) on startup
  564 
  565           <tag> -fixed <it>width</it> <it>height</it> </tag>
  566                 Set canvas size fixed to width*height
  567 
  568           <tag> -free </tag> Use free page layout
  569 
  570           <tag> -graph <it>graph_number</it> </tag>
  571                 Set the current graph number
  572 
  573           <tag> -graphtype <it>xy|chart|fixed|polar|pie</it> </tag>
  574                 Set the type of the current graph
  575 
  576           <tag> -hardcopy </tag>
  577                 No interactive session, just print and quit
  578 
  579           <tag> -hdevice <it>hardcopy_device_name</it> </tag>
  580                 Set default hardcopy device
  581 
  582           <tag> -install </tag>
  583                 Install private colormap
  584 
  585           <tag> -legend <it>load</it> </tag>
  586                 Turn the graph legend on
  587 
  588           <tag> -log <it>x|y|xy</it> </tag>
  589                 Set the axis scaling of the current graph to logarithmic
  590 
  591           <tag> -maxpath <it>length</it> </tag>
  592                 Set the maximal drawing path length
  593 
  594           <tag> -mono </tag>
  595                 Run Grace in monochrome mode (affects the display only)
  596 
  597           <tag> -netcdf <it>file</it> </tag>
  598                 Assume data <it>file</it> is in netCDF format. This option is
  599                 present only if the netCDF support was compiled in
  600 
  601           <tag> -netcdfxy <it>X_var</it> <it>Y_var</it> </tag>
  602                 If -netcdf was used previously, read from the netCDF file
  603                 <it>X_var</it> <it>Y_var</it> variables and create a set. If
  604                 <it>X_var</it> name is "null" then load the index of Y to X.
  605                 This option is present only if the netCDF support was compiled
  606                 in
  607  
  608           <tag> -noask </tag>
  609                 Assume the answer is yes to all requests - if the operation would
  610                 overwrite a file, Grace will do so without prompting
  611 
  612           <tag> -noinstall </tag>
  613                 Don't use private colormap
  614 
  615           <tag> -noprint </tag>
  616                 In batch mode, do not print
  617 
  618           <tag> -nosafe </tag>
  619                 Disable safe mode
  620 
  621           <tag> -nosigcatch </tag>
  622                 Don't catch signals
  623 
  624           <tag> -npipe <it>file</it> </tag>
  625                 Read data from named pipe on startup
  626 
  627           <tag> -nxy <it>nxy_file</it> </tag>
  628                 Assume data file is in X Y1 Y2 Y3 ... format
  629 
  630           <tag> -param <it>parameter_file</it> </tag>
  631                 Load parameters from parameter_file to the current graph
  632 
  633           <tag> -pexec <it>parameter_string</it> </tag>
  634                 Interpret string as a parameter setting
  635 
  636           <tag> -pipe </tag>
  637                 Read data from stdin on startup
  638 
  639           <tag> -printfile </tag> <it>file</it>
  640                 Save print output to file
  641 
  642           <tag> -remove </tag>
  643                 Remove data file after read
  644 
  645           <tag> -results <it>results_file</it> </tag>
  646                 Write results of some data manipulations to results_file
  647 
  648           <tag> -rvideo </tag>
  649                 Exchange the color indices for black and white
  650 
  651           <tag> -safe </tag>
  652                 Run in the safe mode (default) - no file system modifications
  653                 are allowd through the batch language
  654 
  655           <tag> -saveall <it>save_file</it> </tag>
  656                 Save all graphs to save_file
  657 
  658           <tag> -seed <it>seed_value</it> </tag>
  659                 Integer seed for random number generator
  660 
  661           <tag> -settype <it>xy|xydx|...</it> </tag>
  662                 Set the type of the next data file
  663 
  664           <tag> -source <it>disk|pipe</it> </tag>
  665                 Source type of next data file
  666 
  667           <tag> -timer <it>delay</it> </tag>
  668                 Set allowed time slice for real time inputs to delay ms
  669 
  670           <tag> -timestamp </tag> Add timestamp to plot
  671 
  672           <tag> -version </tag>
  673                 Show the program version
  674 
  675           <tag> -viewport <it>xmin ymin xmax ymax</it> </tag>
  676                 Set the viewport for the current graph
  677 
  678           <tag> -wd <it>directory</it> </tag>
  679                 Set the working directory
  680 
  681           <tag> -world <it>xmin ymin xmax ymax</it> </tag>
  682                 Set the world coordinates for the current graph
  683 
  684           <tag> -usage|-help </tag>
  685                 This message
  686  
  687           </descrip>
  688 
  689   <sect1>Customization
  690     <p>
  691     <sect2>Environment variables <label id="environment-variables">
  692       <p>
  693         <itemize>
  694         <item> GRACE&lowbar;HOME
  695                <p>
  696                Set the location of Grace. This will be where help files,
  697                auxiliary programs, and examples are located. If you are unable
  698                to find the location of this directory, contact your system
  699                administrator.
  700                <p>
  701         <item> GRACE&lowbar;PRINT&lowbar;CMD
  702                <p>
  703                Print command. If the variable is defined but is an empty
  704                string, "Print to file" will be selected as default.
  705                <p>
  706         <item> GRACE&lowbar;EDITOR
  707                <p>
  708                The editor used for manual editing of dataset values.
  709                <p>
  710         <item> GRACE&lowbar;HELPVIEWER
  711                <p>
  712                The shell command to run an HTML viewer for on-line browsing of
  713                the help documents. Must include at least one instance of "%s"
  714                which will be replaced with the actual URL by Grace.
  715                <p>
  716         <item> GRACE&lowbar;FFTW&lowbar;WISDOM&lowbar;FILE and
  717                GRACE&lowbar;FFTW&lowbar;RAM&lowbar;WISDOM
  718                <p>
  719                These flags control behavior of the FFTW planner (see
  720                <ref id="fftw-tuning" name="FFTW tuning"> for detailed info)
  721                <p>
  722         </itemize>
  723     
  724     <sect2>Init file<label id="gracerc">
  725       <p>
  726         Upon start-up, Grace loads its init file, <tt>gracerc</tt>. The file
  727         is searched for in the magic path (see
  728         <ref id="magic-path" name="magic path">); once found, the rest of the
  729         path is ignored. It's recommended that in the <tt>gracerc</tt> file,
  730         one doesn't use statements which are part of a project file - such
  731         defaults, if needed, should be set in the default template (see 
  732         <ref id="default-template" name="default template">).
  733 
  734     <sect2>Default template<label id="default-template">
  735       <p>
  736         Whenever a new project is started, Grace loads the default template,
  737         <tt>templates/Default.agr</tt>. The file is searched for in the magic
  738         path (see  <ref id="magic-path" name="magic path">); once found, the
  739         rest of the path is ignored. It's recommended that in the default
  740         template, one doesn't use statements which are NOT part of a project
  741         file - such defaults, if needed, should be set in the
  742         <tt>gracerc</tt> (see <ref id="gracerc" name="init file">).
  743 
  744     <sect2>X resources
  745       <p>
  746 
  747         The following Grace-specific X resource settings are supported:
  748 
  749         <itemize>
  750         <item> XMgrace.invertDraw
  751                <newline>
  752                Use GXinvert rather than GXxor for rubber-band lines.
  753                If the rubber-banding for zooms and lines, etc. doesn't
  754                appear on the canvas, set this resource to yes.
  755                <newline>
  756 
  757         <item> XMgrace.allowDoubleClick
  758                <newline>
  759                When Yes, allow double clicks on the canvas to bring up various
  760                popups depending on  the location of the pointer when the double
  761                click occurs.
  762                <newline>
  763 
  764         <item> XMgrace.toolBar
  765                <newline>
  766                Enables button toolbar
  767                <newline>
  768 
  769         <item> XMgrace.statusBar
  770                <newline>
  771                Enables status bar
  772                <newline>
  773 
  774         <item> XMgrace.locatorBar
  775                <newline>
  776                Enables locator bar
  777                <newline>
  778 
  779        </itemize>
  780 
  781 
  782         It is also possible to customize menus by assigning key accelerators to
  783         any item.
  784 
  785         You'll need to derive the item's X resource name from the respective
  786         menu label, which is easily done following these rules:
  787         <itemize>
  788           <item> All non-alphanumeric characters are skipped
  789           <item> Start with lower case; each new word (if any) continues from
  790                  the capital letter
  791           <item> Add the item's type to the end - "Menu" for pulldown menus,
  792                  "Button" for menu buttons.
  793         </itemize>
  794         
  795         For example, in order to make Grace popup the Non-linear curve fitting
  796         by pressing Control+F, you would add the following two lines
  797 
  798         <tt>
  799           XMgrace*transformationsMenu.nonLinearCurveFittingButton.acceleratorText: Ctrl+F
  800           <newline>
  801           XMgrace*transformationsMenu.nonLinearCurveFittingButton.accelerator: Ctrl&lt;Key&gt;f
  802         </tt>
  803 
  804 
  805         to your <tt>.Xresources</tt> file (the file which is read when an X
  806         session starts; it could be <tt>.Xdefaults</tt>, <tt>.Xsession</tt> or
  807         some other file - ask your system administrator when in doubt).
  808         
  809         <p>
  810           Similarly, it may be desirable to alter default filename patterns of
  811           file selection dialogs. The recipe for the dialog's name is like for
  812           menu buttons outlined above, with "Button" being replaced with "FSB".
  813           E.g., to list all files in the "Open project" dialog ("File/Open..."),
  814           set the following resource:
  815           
  816           <tt>
  817             XMgrace*openProjectFSB.pattern: *
  818           </tt>
  819           
  820         </p>
  821 
  822 
  823 <!-- **************************************** -->
  824 <sect>Guide to the graphical user interface<label id="GUI-guide">
  825   <p>
  826   <sect1>GUI controls
  827     <p>
  828     This section describes interface controls - basic building blocks, used in
  829     many popups.
  830     </p>
  831     <sect2>File selection dialogs <label id="FS-dialog">
  832       <p>
  833       Whenever the user is expected to provide a filename, either for reading
  834       in or writing some data, a file selection dialog is popped up. In
  835       addition to the standard entries (the directory and file lists and the
  836       filter entry), there is a pulldown menu for quick directory change to
  837       predefined locations (the current working directory, user's home
  838       directory and the file system root). Also, a "Set as cwd" button is
  839       there which allows to set any directory as you navigate through the
  840       directory tree as the current working directory (cwd). Once defined, it
  841       can be used in any other file selection dialog to switch to that
  842       directory quickly.
  843 
  844     <sect2>List selectors <label id="list-selector">
  845       <p>
  846       Various selectors are available in several popups. They all display
  847       lists of objects (graphs, sets, ...) and can be used to perform
  848       simple operations on these objects (copying, deleting, ...). The
  849       operations are available from a popup menu that appears when pressing
  850       mouse button 3 on them. Depending on the required functionality, they
  851       may allow multiple choices or not. The following
  852       shortcuts are enabled (if the result of an action would contradict the
  853       list's selection policy, this would be ignored):
  854       <itemize>
  855         <item> Ctrl+a select all
  856         <item> Ctrl+u unselect all
  857         <item> Ctrl+i invert selection
  858       </itemize>
  859 
  860         <sect3> Graph selector <label id="graph-selector">
  861         <p>
  862         The operations that can be performed on graphs through the graph
  863         selector's popup menu are:
  864         <itemize>
  865           <item> focus to
  866           <item> hide
  867           <item> show
  868           <item> duplicate
  869           <item> kill
  870           <item> swap
  871           <item> create new
  872         </itemize>
  873         All this operations are not available in every instance of the
  874         selector. For example in the "read sets" popup only one graph can
  875         be selected at a time, and the swap operation is disabled.
  876 
  877         Double-clicking on a list entry will switch the focus to that graph.
  878 
  879         <sect3> Set selector <label id="set-selector">
  880         <p>
  881         The operations that can be performed on sets through the set
  882         selector's popup menu are:
  883         <itemize>
  884           <item> hide
  885           <item> show
  886           <item> bring to front
  887           <item> send to back
  888           <item> duplicate
  889           <item> kill
  890           <item> kill data
  891           <item> swap
  892           <item> edit
  893           <itemize>
  894             <item> in spreadsheet (see
  895                    <ref name="Spreadsheet data set editor" id="SSEditor">)
  896             <item> in text editor
  897           </itemize>
  898           <item> create new
  899           <itemize>
  900             <item> by formula
  901             <item> in spreadsheet (see
  902                    <ref name="Spreadsheet data set editor" id="SSEditor">)
  903             <item> in text editor
  904             <item> from block data
  905           </itemize>
  906           <item> pack all sets
  907           <item> selector operations
  908           <itemize>
  909             <item> view set comments
  910             <item> show data-less
  911             <item> show hidden
  912             <item> select all
  913             <item> unselect all
  914             <item> invert selection
  915             <item> update
  916           </itemize>
  917         </itemize>
  918 
  919         Double-clicking on a list entry will open the spreadsheet editor
  920         (see <ref name="Spreadsheet data set editor" id="SSEditor">) on
  921         the set data.
  922 
  923   <sect1>The main window<label id="main-window">
  924     <p>
  925 
  926     <sect2>The canvas<label id="canvas">
  927      <p>
  928 
  929       <sect3>Canvas hotkeys
  930         <p>
  931 
  932         When the pointer focus is on the canvas (where the graph is drawn),
  933         there are some shortcuts to activate several actions. They are:
  934 
  935         <itemize>
  936           <item> Ctrl &lt;Key&gt;A: Autoscale the current graph
  937           <item> Ctrl &lt;Key&gt;D: Delete an object
  938           <item> Ctrl &lt;Key&gt;L: Move current graph legend
  939           <item> Ctrl &lt;Key&gt;M: Move an object
  940           <item> Ctrl &lt;Key&gt;T: Place timestamp
  941           <item> Ctrl &lt;Key&gt;U: Refresh hotlinks
  942           <item> Ctrl &lt;Key&gt;V: Set the viewport with mouse
  943           <item> Ctrl &lt;Key&gt;Z: Zoom
  944           <item> Ctrl Alt &lt;Key&gt;L: Draw a line
  945           <item> Ctrl Alt &lt;Key&gt;B: Draw a box
  946           <item> Ctrl Alt &lt;Key&gt;E: Draw an ellipse
  947           <item> Ctrl Alt &lt;Key&gt;T: Write a text string
  948         </itemize>
  949 
  950       <sect3>Clicks and double clicks<label id="clicks">
  951         <p>
  952           A single click inside a graph switches focus to that graph. This is the
  953           default policy, but it can be changed from the "Edit/Preferences"
  954           popup.
  955         </p>
  956 
  957         <p>
  958           Double clicking on parts of the canvas will invoke certain actions
  959           or raise some popups:
  960 
  961           <itemize>
  962             <item> on a focus marker: move selected viewport corner 
  963             <item> on an axis:  "Plot/Axis properties" popup
  964             <item> on a set:    "Plot/Set appearance" popup
  965             <item> on a legend: "Plot/Graph appearance" popup
  966             <item> on a (sub)title: "Plot/Graph appearance" popup
  967             <item> on an object (box, line, ...): a popup for editing
  968                    properties of that object
  969           </itemize>
  970 
  971           The double clicking actions can be enabled/disabled from the
  972           "Edit/Preferences" popup.
  973 
  974     <sect2>Toolbar buttons<label id="toolbar">
  975       <p>
  976       Along the left-hand side of the canvas (if shown) is the ToolBar. It
  977       is armed with several buttons to provide quick and easy access to the
  978       more commonly used Grace functions.
  979 
  980       <itemize> 
  981         <item> <tt>  Draw</tt>: This will redraw the canvas and sets.
  982       Useful if "Auto Redraw" has been deselected in the Edit|Preferences
  983       dialog or after executing commands directly from the Window|Commands
  984       interpreter.
  985           <p>
  986 
  987         <item> <tt>  Lens</tt>: A zoom lens.  Click on the lens, then select the
  988           area of interest on the graph with the "rubber band".  The region
  989       enclosed by the rubber band will fill the entire graph.
  990         <item> <tt>    AS</tt>: AutoScale.  Autoscales the graph to contain all
  991           data points of all visible (not hidden) sets.
  992         <item> <tt>   Z/z</tt>:  Zoom in/out by 5%. The zoom percentage can be
  993           set in the Edit/Preferences dialog.
  994         <item> <tt>Arrows</tt>:  Scroll active graph by 5% in the arrow's
  995           direction.  The scroll percentage can be set in the
  996       Edit/Preferences dialog.
  997 
  998           <p>
  999         <item> <tt>AutoT</tt>: AutoTick Axes.  This will find the optimum
 1000           number of major and minor tick marks for both axes.
 1001         <item> <tt>AutoO</tt>: Autoscale On set.  Click the <tt>AutoO</tt>
 1002           button, then click on the graph near the set you wish to use for
 1003       determining the autoscale boundaries of the graph.
 1004           <p>
 1005         <item> <tt>ZX,ZY</tt>: Zoom along an axis.  These buttons work like the
 1006           zoom lens above but are restricted to a single axis. 
 1007         <item> <tt>AX,AY</tt>: Autoscale one axis only.
 1008           <p>
 1009         The following buttons deal with the graph stack and there is a good
 1010         example under Help/Examples/General Intro/World Stack.
 1011         <item> <tt>Pu/Po</tt>: Push and pop the current world settings to/from
 1012           the graph stack. When popping, makes the new stack top current.
 1013         <item> <tt>PZ</tt>: Push before Zooming.  Functions as the zoom lens,
 1014           but first pushes the current world settings to the stack.  
 1015         <item> <tt>Cy</tt>: Cycles through the stack settings of the active
 1016           graph.  Each graph may have up to twenty layers on the stack.
 1017           <p>      
 1018         <item> <tt>Exit</tt>: Pretty obvious, eh?
 1019       </itemize>
 1020 
 1021 
 1022    <sect1> File menu <label id="file-menu">
 1023    <p>
 1024      The file menu contains all entries related to the input/output features
 1025      of Grace.
 1026 
 1027       <sect2> New <label id="new">
 1028       <p>
 1029       Reset the state of Grace as if it had just started (one empty
 1030       graph ranging from 0 to 1 along both axes). If some work has
 1031       been done and not yet saved, a warning popup is displayed to
 1032       allow canceling the operation.
 1033 
 1034       <sect2> Open <label id="open">
 1035       <p>
 1036       Open an existing <ref id="project-file" name="project file">. A
 1037       popup is displayed that allow to browse the file system.
 1038 
 1039       <sect2> Save <label id="save">
 1040       <p>
 1041       Save the current work in a project file, using the name that was
 1042       used for the last open or save. If no name has been set (i.e.,
 1043       if the project has been created from scratch) act as <ref
 1044       id="save-as" name="save as">.
 1045 
 1046       <sect2> Save as <label id="save-as">
 1047       <p>
 1048       Save the current work in a project file with a new name. A popup allows
 1049       to browse the file system and set the name, the format to use for saving
 1050       data points (the default value is "%16.8g"), and a textual description of
 1051       the project. A warning is displayed if a file with the same name already
 1052       exists.
 1053 
 1054       <sect2> Revert to saved <label id="revert-to-saved">
 1055       <p>
 1056       Abandon all modifications performed on the project since the
 1057       last save. A confirmation popup is fired to allow the user
 1058       canceling the operation.
 1059 
 1060       <sect2> Print setup <label id="print-setup">
 1061       <p>
 1062       Set the properties of the printing device. Each device has its
 1063       own set of specific options (see <ref name="Device-specific
 1064       settings" id="device-settings">). According to the device, the
 1065       output can be sent either directly to a printer or directed to a
 1066       file. The global settings available for all devices are the
 1067       sizing parameters. The size of the graph is fixed. Changing the 'Page'
 1068       settings changes the size of the canvas underneath the graph.
 1069       Switching between portrait and landscape rotates the canvas.
 1070       Make sure the canvas size is large enough to hold your graph.
 1071       Otherwise you get a 'Printout truncated' warning. If your canvas
 1072       size cannot easily be changed because, for example, you want to
 1073       print on letter size paper, you need to adjust the size of
 1074       your graph ('Viewport' in Plot/Graph Appearance).
 1075 
 1076       <sect2> Print <label id="print">
 1077       <p>
 1078       Print the project using the current printer settings
 1079 
 1080       <sect2> Exit <label id="exit">
 1081       <p>
 1082       Exit from Grace. If some work has been done and not saved, a
 1083       warning popup will be displayed to allow the user to cancel the
 1084       operation.
 1085 
 1086    <sect1> Edit menu <label id="edit-menu">
 1087    <p>
 1088       <sect2> Data sets <label id="data-sets">
 1089       <p>
 1090       Using the data set popup, you can view the properties of
 1091       datasets. This include its type, length, associated comment and
 1092       some statistics (min, max, mean, standard deviation). A
 1093       horizontal scrollbar at the bottom allows to get the two last
 1094       properties, they are not displayed by default. Also note that if
 1095       you find some columns are too narrow to show all significant
 1096       digits, you can drag the vertical rules using Shift+Button 2.
 1097 
 1098       Using the menu on the top of this dialog, you can manipulate existing
 1099       sets or add new ones. Among the most important entries in the menu,
 1100       are options to create or modify a set using the spreadsheet data set
 1101       editor (see <ref name="Spreadsheet data set editor" id="SSEditor">).
 1102       
 1103         <sect3>Spreadsheet data set editor<label id="SSEditor">
 1104         <p>
 1105           The dialog presents an editable matrix of numbers, corresponding
 1106           to the data set being edited. The set type (and hence, the number
 1107           of data columns) can be changed using the "Type:" selector.
 1108           Clicking on a column label pops up a dialog allowing to adjust
 1109           the column formatting. Clicking on the row labels toggles the
 1110           respective row state (selected/unselected). The selected rows can
 1111           be deleted via the dialog's "Edit" menu. Another entry in this
 1112           menu lets you add a row; the place of the new row is determined
 1113           by the row containing a cell with the keyboard focus on. As well,
 1114           just typing in an empty cell will add one or several rows
 1115           (filling the intermediate rows with zeros).
 1116 
 1117           To resize columns, drag the vertical rules using Shift+Button 2.
 1118         </p>
 1119         </sect3> <!-- Spreadsheet data set editor -->
 1120 
 1121 
 1122       <sect2> Set operations <label id="set-operations">
 1123       <p>
 1124       The set operations popup allows you to interact with sets as a
 1125       whole. If you want to operate on the data ordering of the sets,
 1126       you should use the <ref name="data set operations"
 1127       id="data-set-operations"> popup from the Data menu. The popup
 1128       allows you to select a source (one set within one graph) and a
 1129       destination and perform some action upon them (copy, move,
 1130       swap). This popup also give you a quick access to several graph
 1131       and set selectors if you want to perform some other operation
 1132       like hiding a graph or creating a new set from block data.
 1133 
 1134       <sect2> Arrange graphs <label id="arrange-graphs">
 1135       <p>
 1136       This entry fires up a popup to lay out several graphs in a
 1137       regular grid given by <bf>M</bf> rows and <bf>N</bf> columns. 
 1138       
 1139       The graph selector at the top allows one to select a number of graphs
 1140       the arrangement will operate on. If the number of selected graphs
 1141       isn't equal to <bf>M</bf> times <bf>N</bf>,  new graphs may be created
 1142       or extra graphs killed if needed. These options are  controlled by the
 1143       respective checkboxes below the graph selector.
 1144       
 1145       The order in which the matrix is filled in with the graphs can be
 1146       selected (first horizontally then vertically or vise versa, with
 1147       either of them inverted). Additionaly, one may choose to fill the matrix
 1148       in the snake-like manner (adjacent "strokes" are anti-parallel).
 1149       
 1150       The rest of the controls of the dialog window deal with the matrix
 1151       spacing: left/right/top/bottom page offsets (in the viewport
 1152       coordinates) and <it>relative</it> inter-cell distances, vertical
 1153       and horizontal. Next to each of the vertical/horizontal spacing
 1154       spinboxes, a "Pack" checkbox is found. Enabling it effectively sets
 1155       the respective inter-cell distance to zero and alter axis tickmark
 1156       settings such that only bottom/left-most tickmarks are visible.
 1157       
 1158       If you don't want the regular layout this arrangement gives you,
 1159       you can change it afterwards using the mouse (select a graph and
 1160       double click on the focus marker, see <ref id="clicks"
 1161       name="clicks and double clicks">).
 1162 
 1163       <sect2> Overlay graphs <label id="overlay-graphs">
 1164       <p>
 1165       You can overlay a graph on top of another one. The main use of
 1166       this feature is to plot several curves using different scales on
 1167       the same (apparently) graph. The main difficulty is to be sure
 1168       you operate on the graph you want at all times (you can hide one
 1169       for a moment if this becomes too difficult).
 1170 
 1171       <sect2> Autoscale <label id="autoscale">
 1172       <p>
 1173       Using this entry, you can autoscale one graph or all graphs
 1174       according to the specified sets only. This is useful if you need
 1175       either to have truly comparable graphs despite every one
 1176       contains data of different ranges, or if you want to focus your
 1177       attention on one set only while it is displayed with other data
 1178       in a complex graph.
 1179 
 1180       <sect2> Regions menu <label id="regions-menu">
 1181       <p>
 1182          <sect3> Status <label id="status">
 1183          <p>
 1184          This small popup only displays the current state (type and
 1185          whether it is active or not) of the existing regions.
 1186 
 1187          <sect3> Define <label id="define">
 1188          <p>
 1189          You can define a new region (or redefine an existing one),
 1190          the allowed region types are:
 1191 
 1192          <itemize>
 1193          <item> Inside polygon
 1194          <item> Outside polygon
 1195          <item> Above line
 1196          <item> Below line
 1197          <item> Left of line
 1198          <item> Right of line
 1199          <item> In horizontal range
 1200          <item> In vertical range
 1201          <item> Out of horizontal range
 1202          <item> Out of vertical range
 1203          </itemize>
 1204 
 1205          A region can be either linked to the current graph only or to
 1206          all graphs.
 1207 
 1208          <sect3> Clear <label id="clear">
 1209          <p>
 1210          This kills a region.
 1211 
 1212          <sect3> Report on <label id="report-on">
 1213          <p>
 1214          This popup reports you which sets or points are inside or
 1215          outside of a region.
 1216 
 1217       <sect2> Hot links <label id="hot-links">
 1218       <p>
 1219       You can link a set to a file or a pipe using this feature. Once
 1220       a link has been established, you can update it (i.e., read data
 1221       again) by clicking on the update button.
 1222       <p>
 1223       Currently, only simple XY sets can be used for hotlinks.
 1224 
 1225       <sect2> Set locator fixed point <label id="set-locator-fixed-point">
 1226       <p>
 1227       After having selected this menu entry, you can select a point on
 1228       a graph that will be used as the origin of the locator display
 1229       (just below the menu bar). The fixed point is taken into account
 1230       only when the display type of the locator is set to [DX,DY].
 1231 
 1232       <sect2> Clear locator fixed point <label id="clear-locator-fixed-point">
 1233       <p>
 1234       This entry is provided to remove a fixed point set before and
 1235       use the default again: point [0, 0].
 1236 
 1237       <sect2> Locator props <label id="locator-props">
 1238       <p>
 1239       The locator props popup allows you to customize the display of
 1240       the locator, mainly its type and the format and precision of the
 1241       display. You can use all the formats that are allowed in the
 1242       graphs scales.
 1243 
 1244       <sect2> Preferences <label id="preferences">
 1245       <p>
 1246       The preferences popup allows you to set miscellaneous properties
 1247       of your Grace session, such as GUI behavior, cursor type,
 1248       date reading hint and reference date used for calendar conversions.
 1249 
 1250    <sect1> Data menu <label id="data-menu">
 1251    <p>
 1252       <sect2> Data set operations <label id="data-set-operations">
 1253       <p>
 1254        This popup gathers all operations that are related to the
 1255       ordering of data points inside a set or between sets. If you
 1256       want to operate on the sets as a whole, you should use the <ref
 1257       name="set operations" id="set-operations"> popup from the Edit
 1258       menu. You can sort according to any coordinate (X, Y, DX, ...)
 1259       in ascending or descending order, reverse the order of the
 1260       points, join several sets into one, split one set into several
 1261       others of equal lengths, or drop a range of points from a
 1262       set. The <ref name="set selector" id="set-selector"> of the
 1263       popup shows the number of points in each set in square brackets
 1264       like this: G0.S0[63], the points are numbered from 0 to n-1.
 1265 
 1266       <sect2> Transformations menu <label id="transformations-menu">
 1267       <p>
 1268       The transformations sub-menu gives you access to all data-mining
 1269       features of Grace.
 1270 
 1271          <sect3> Evaluate expression <label id="evaluate-expression">
 1272          <p>
 1273          Using evaluate expression allows you to create a set by
 1274          applying an explicit formula to another set, or to parts of
 1275          another set if you use regions restrictions.
 1276 
 1277          All the classical mathematical functions are available (cos,
 1278          sin, but also lgamma, j1, erf, ...). As usual all
 1279          trigonometric functions use radians by default but you can
 1280          specify a unit if you prefer to say cos (x rad) or sin (3 * y
 1281          deg). For the full list of available numerical functions and
 1282          operators, see
 1283          <ref name="Operators and functions" id="operators-and-functions">.
 1284 
 1285          In the formula, you can use X, Y, Y1, ..., Y4 to denote any
 1286          coordinate you like from the source set. An implicit loop
 1287          will be used around your formula so if you say:
 1288 
 1289          <tscreen><verb>
 1290          x = x - 4966.5
 1291          </verb></tscreen>
 1292 
 1293          you will shift all points of your set 4966.5 units to the left.
 1294 
 1295          You can use more than one set in the same formula, like this:
 1296 
 1297          <tscreen><verb>
 1298          y = y - 0.653 * sin (x deg) + s2.y
 1299          </verb></tscreen>
 1300 
 1301          which means you use both X and Y from the source set but also
 1302          the Y coordinate of set 2. Beware that the loop is a simple
 1303          loop over the indices, all the sets you use in such an hybrid
 1304          expression should therefore have the same number of points
 1305          and point i of one set should really be related to point i of
 1306          the other set. If your sets do not follow these requirements,
 1307          you should first homogenize them using
 1308          <ref name="interpolation" id="interpolation">.
 1309 
 1310          <sect3> Histograms <label id="histograms">
 1311          <p>
 1312          The histograms popup allows you to compute either standard
 1313          or cumulative histograms from the Y coordinates of
 1314          your data. Optionally, the histograms can be normalized to 1 (hence
 1315          producing a PDF (Probability Distribution Function).
 1316 
 1317          The bins can be either a linear mesh defined by its min, max, and
 1318          length values, or a mesh formed by abscissas of another set (in which
 1319          case abscissas of the set must form a strictly monotonic array).
 1320 
 1321          <sect3> Fourier transforms <label id="fourier-transforms">
 1322          <p>
 1323          This popup is devoted to direct and inverse Fourier transforms
 1324          (actually, what is computed is a power spectrum). The default is to
 1325          perform a direct transform on unfiltered data and to produce a set
 1326          with the index as abscissa and magnitude as ordinate. You can filter
 1327          the input data window through triangular, Hanning, Welch, Hamming,
 1328          Blackman and Parzen filters. You can load magnitude, phase or
 1329          coefficients and use either index, frequency or period as abscissas.
 1330          You can choose between direct and inverse Fourier transforms. If you
 1331          specify real input data, X is assumed to be equally spaced and
 1332          ignored; if you specify complex input data X is taken as the real part
 1333          and Y as the imaginary part.
 1334 
 1335          If Grace was configured with the FFTW library (see <ref
 1336          name="configuration" id="configuration">), then the DFT and
 1337          FFT buttons really perform the same transform (so there is no
 1338          speed-up in using FFT in this case). If you want Grace can to
 1339          use FFTW <it>wisdom</it> files, you should set several <ref
 1340          name="environment variables" id="environment-variables"> to
 1341          name them.
 1342 
 1343          <sect3> Running averages <label id="running-averages">
 1344          <p>
 1345          The running average popup allows you to compute some values
 1346          on a sliding window over your data. You choose both the value
 1347          you need (average, median, minimum, maximum, standard
 1348          deviation) and the length of the window and perform the
 1349          operation. You can restrict the operation to the points
 1350          belonging to (or outside of) a region.
 1351 
 1352          <sect3> Differences <label id="differences">
 1353          <p>
 1354          The differences popup is used to compute approximations of
 1355          the first derivative of a function with finite
 1356          differences. The only choice (apart from the source set of
 1357          course) is the type of differences to use: forward, backward
 1358          or centered.
 1359 
 1360          <sect3> Seasonal differences <label id="seasonal-differences">
 1361          <p>
 1362          The seasonal differences popup is used to subtract data from
 1363          a period to data of the preceding period (namely y[i] - y[i +
 1364          period]). Beware that the period is entered in terms of index
 1365          in the set and not in terms of abscissa!
 1366 
 1367          <sect3> Integration <label id="integration">
 1368          <p>
 1369          The integration popup is used to compute the integral of a
 1370          set and optionally to load it. The numerical value of the
 1371          integral is shown in the text field after
 1372          computation. Selecting "cumulative sum" in the choice item
 1373          will create and load a new set with the integral and compute
 1374          the end value, selecting "sum only" will only compute the end
 1375          value.
 1376 
 1377          <sect3> Interpolation/Splines <label id="interpolation">
 1378          <p>
 1379          This popup is used to interpolate a set on an array of alternative X
 1380          coordinates. This is mainly used before performing some complex
 1381          operations between two sets with the <ref name="evaluate
 1382          expression" id="evaluate-expression"> popup.
 1383          
 1384          The sampling array can be either a linear mesh defined by its min,
 1385          max, and length values, or a mesh formed by abscissas of another set. 
 1386          
 1387          Several interpolation methods can be used: linear, spline or Akima
 1388          spline.
 1389          
 1390          Note that if the sampling mesh is not entirely within the source set
 1391          X bounds, evaluation at the points beyond the bounds will be performed
 1392          using interpolation parameters from the first (or the last) segment
 1393          of the source set, which can be considered a primitive extrapolation.
 1394          This behaviour can be disabled by checking the "Strict" option on the
 1395          popup.
 1396          
 1397          The abscissas of the set being interpolated must form a strictly
 1398          monotonic array.
 1399 
 1400          <sect3> Regression <label id="regression">
 1401          <p>
 1402          The regression popup can be used to fit a set against
 1403          polynomials or some specific functions (y=A*x^B,
 1404          y=A*exp(B*x), y=A+B*ln(x) and y=1/(A+Bx)) for which a simple
 1405          transformation of input data can be used to apply linear
 1406          regression formulas.
 1407 
 1408          You can load either the fitted values, the residuals or the
 1409          function itself. Choosing to load fitted values or residuals
 1410          leads to a set of the same length and abscissas as the
 1411          initial set. Choosing to load the function is almost similar
 1412          to load the fitted values except that you choose yourself the
 1413          boundaries and the number of points. This can be used for
 1414          example to draw the curve outside of the data sample range or
 1415          to produce an evenly spaced set from an irregular one.
 1416 
 1417          <sect3> Non-linear fit <label id="non-linear-fit">
 1418          <p>
 1419          The non linear fit popup can be used for functions outside of
 1420          the simple regression methods scope. With this popup you
 1421          provide the expression yourself using a0, a1, ..., a9 to
 1422          denote the fit parameters (as an example you can say y = a0 * cos
 1423          (a1 * x + a2)). You specify a tolerance, starting values and
 1424          optional bounds and run several steps before loading the
 1425          results.
 1426 
 1427          The fit characteristics (number of parameters, formula, ...)
 1428          can be saved in a file and retrieved as needed using the file
 1429          menu of the popup.
 1430 
 1431          In the "Advanced" tab, you can additionally apply a restriction to
 1432          the set(s) to be fitted (thus ignoring points not satisfying the
 1433          criteria), use one of preset weighting schemes or define your own
 1434          (notice that "dY" in the preset "1/dY^2" one actually refers to the
 1435          third column of the data set; use the "Custom" function if this
 1436          doesn't make sense for your data set), and choose whether to load
 1437          the fitted values, the residuals or the function itself. Choosing
 1438          to load fitted values or residuals leads to a set of the same
 1439          length and abscissas as the initial set. Choosing to load the
 1440          function is almost similar to load the fitted values except that
 1441          you choose yourself the boundaries and the number of points. This
 1442          can be used for example to draw the curve outside of the data
 1443          sample range or to produce an evenly spaced set from an irregular
 1444          one.
 1445 
 1446          <sect3> Correlation/covariance <label id="correlation/covariance">
 1447          <p>
 1448          This popup can be used to compute autocorrelation
 1449          of one set or cross correlation between two sets. You only
 1450          select the set (or sets) and specify the maximum lag. A check
 1451          box allows one to evaluate covariance instead of correlation.
 1452          The result is normalized so that abs(C(0)) = 1.
 1453 
 1454          <sect3> Digital filter <label id="digital-filter">
 1455          <p>
 1456          You can use a set as a weight to filter another set. Only the
 1457          Y part and the length of the weighting set are important, the
 1458          X part is ignored.
 1459 
 1460          <sect3> Linear convolution <label id="linear-convolution">
 1461          <p>
 1462          The convolution popup is used to ... convolve two sets. You
 1463          only select the sets and apply.
 1464 
 1465          <sect3> Geometric transforms <label id="geometric-transforms">
 1466          <p>
 1467          You can rotate, scale or translate sets using the geometric
 1468          transformations popup. You specify the characteristics of
 1469          each transform and the application order.
 1470 
 1471          <sect3> Sample points <label id="sample-points">
 1472          <p>
 1473          This popup provides two sampling methods. The first one is
 1474          to choose a starting point and a step, the second one is to
 1475          select only the points that satisfy a boolean expression you
 1476          specify.
 1477 
 1478          <sect3> Prune data <label id="prune-data">
 1479          <p>
 1480          This popup is devoted to reducing huge sets (and then saving
 1481          both computation time and disk space).
 1482 
 1483          The interpolation method can be applied only to ordered sets:
 1484          it is based on the assumption that if a real point and an
 1485          interpolation based on neighboring points are closer than a
 1486          specified threshold, then the point is redundant and can be
 1487          eliminated.
 1488 
 1489          The geometric methods (circle, ellipse, rectangle) can be
 1490          applied to any set, they test each point in turn and keep
 1491          only those that are not in the neighborhood of previous
 1492          points.
 1493          <p>
 1494 
 1495       <sect2> Feature extraction <label id="feature-extraction">
 1496       <p>
 1497       Given a set of curves in a graph, extract a feature from each
 1498       curve and use the values of the feature to provide the Y values
 1499       for a new curve.
 1500 
 1501       <p>
 1502       <table loc="htbp">
 1503       <tabular ca="lp{10cm}">
 1504               <hline>
 1505               Feature           | Description                       @
 1506               <hline>
 1507 Y minimum |  Minimum Y value of set @
 1508 Y maximum | Maximum Y value of set @
 1509 Y average | Average Y value of set @
 1510 Y std. dev. | Standard deviation of Y values @
 1511 Y median | Median Y value @
 1512 X minimum | Minimum X value of set @
 1513 X maximum | Maximum X value of set @
 1514 X average | Average X value of set @
 1515 X std. dev. | Standard deviation of X values @
 1516 X median | Median X value @
 1517 Frequency | Perform DFT (FFT if set length a power of 2) to find largest frequency component @
 1518 Period | Inverse of above  @
 1519 Zero crossing | Time of the first zero crossing, + or - going @
 1520 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 @
 1521 Fall time | Assume curve starts at the maximum and drops to the minimum, get time to go from 90% to 10% of fall @
 1522 Slope | Perform linear regression to obtain slope @
 1523 Y intercept | Perform linear regression to obtain Y-intercept @
 1524 Set length | Number of data points in set @
 1525 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. @
 1526 Barycenter X | Barycenter along X axis @
 1527 Barycenter Y | Barycenter along Y axis @
 1528 X (Y max)    | X of Maximum Y @
 1529 Y (X max)    | Y of Maximum X @
 1530 integral     | cumulative sum @
 1531               <hline>
 1532       </tabular>
 1533       <caption>
 1534               Extractable features
 1535       </caption>
 1536       </table>
 1537 
 1538       <sect2> Import menu <label id="read-menu">
 1539       <p>
 1540          <sect3> ASCII <label id="read-sets">
 1541          <p>
 1542          Read new sets of data in a graph. A <ref id="graph-selector"
 1543          name="graph selector"> is used to specify the graph where the
 1544          data should go (except when reading block data, which are
 1545          copied to graphs later on).
 1546 
 1547          Reading as "Single set" means that if the source contains
 1548          only one column of numeric data, one set will be created
 1549          using the indices (from 1 to the total number of points) as
 1550          abscissas and read values as ordinates and that if the source
 1551          contains more than one column of data, the first two numeric
 1552          columns will be used. Reading as "NXY" means that the first
 1553          numeric column will provide the abscissas and all remaining
 1554          columns will provide the ordinates of several sets. Reading
 1555          as "Block data" means all column will be read and stored and
 1556          that another popup will allow to select the abscissas and
 1557          ordinates at will. It should be noted that block data are
 1558          stored as long as you do not override them by a new read. You
 1559          can still retrieve data from a block long after having closed
 1560          all popups, using the <ref id="set-selector" name="set
 1561          selector">.
 1562 
 1563          The set type can be one of the predefined set presentation types
 1564          (see <ref id="sets" name="sets">).
 1565 
 1566          The data source can be selected as "Disk" or "Pipe". In the
 1567          first case the text in the "Selection" field is considered to
 1568          be a file name (it can be automatically set by the file
 1569          selector at the top of the popup). In the latter case the
 1570          text is considered to be a command which is executed and
 1571          should produce the data on its standard output. On systems
 1572          that allows is, the command can be a complete sequence of
 1573          programs glued together with pipes.
 1574 
 1575          If the source contains date fields, they should be
 1576          automatically detected. Several formats are recognized (see
 1577          appendix <ref id="dates" name="dates in grace">). Calendar
 1578          dates are converted to numerical dates upon reading.
 1579          
 1580          The "Autoscale on read" menu controls whether, upon reading in new
 1581          sets, which axes of the graph should be autoscaled.
 1582 
 1583          <sect3> NetCDF <label id="read-netCDF">
 1584          <p>
 1585          This entry exists only if Grace has been compiled with
 1586          support for the NetCDF data format (see <ref
 1587          id="configuration" name="configuration">).
 1588 
 1589       <sect2> Export menu <label id="write-menu">
 1590       <p>
 1591          <sect3> ASCII <label id="write-sets">
 1592          <p>
 1593          Save data sets in a file. A <ref id="set-selector" name="set
 1594          selector"> is used to specify the set to be saved. The format
 1595          to use for saving data points can be specified (the default
 1596          value is "%16.8g"). A warning is displayed if a file with the
 1597          same name already exists.
 1598 
 1599 
 1600    <sect1> Plot menu <label id="plot-menu">
 1601    <p>
 1602       <sect2> Plot appearance <label id="plot-appearance">
 1603       <p>
 1604       The plot appearance popup let you set the time stamp properties
 1605       and the background color of the page. The color is used outside
 1606       of graphs and also on graphs were no specific background color
 1607       is set. The time stamp is updated every time the project is modified.
 1608 
 1609       <sect2> Graph appearance <label id="graph-appearance">
 1610       <p>
 1611       The graph appearance popup can be displayed from both the plot menu
 1612       and by double-clicking on a legend, title, or subtitle of a graph
 1613       (see <ref name="Clicks and double clicks" id="clicks">). The graph
 1614       selector at the top allows to choose the graph you want to operate
 1615       on, it also allows certain common actions through its popup menu (see
 1616       <ref name="graph selector" id="graph-selector">). Most of the actions
 1617       can also be performed using the "Edit" menu available from the popup
 1618       menubar. The main tab includes the properties you will need more
 1619       often (title for example), and other tabs are used to fine tune some
 1620       less frequently used options (fonts, sizes, colors, placements).
 1621 
 1622       If you need special characters or special formatting in your
 1623       title or subtitle, you can use Grace escape sequences (the
 1624       sequence will appear verbatim in the text field but will be
 1625       rendered on the graph), see <ref name="typesetting"
 1626       id="typesetting">. If you don't remember the mapping between
 1627       alphabetic characters and the glyph you need in some specific
 1628       fonts (mainly symbol and zapfdingbats), you can invoke the font
 1629       tool from the text field by hitting CTRL-e. You can change fonts
 1630       and select characters from there, they will be copied back in
 1631       the text field when you press the "Accept" button. Beware of
 1632       the position of the cursor as you enter text or change font in
 1633       the font tool, the character or command will be inserted at this
 1634       position, not at the end of the string!
 1635 
 1636       You can save graph appearance parameters or retrieve settings
 1637       previously saved via the "File" menu of this popup. In the "Save
 1638       parameters" dialog, you can choose to save settings either for
 1639       the current graph only or for all graphs.
 1640       
 1641 
 1642       <sect2> Set appearance <label id="set-appearance">
 1643       <p>
 1644       The set appearance popup can be displayed from both the plot
 1645       menu and by double-clicking anywhere in a graph (see <ref
 1646       name="Clicks and double clicks" id="clicks">). The set selector
 1647       at the top allows to choose the set you want to operate on, it
 1648       also allows certain common actions through its popup menu (see
 1649       <ref name="set selector" id="set-selector">). The main tab
 1650       gathers the properties you will need more often (line and
 1651       symbol properties or legend string for example), and other tabs
 1652       are used to fine tune some less frequently used options (drop
 1653       lines, fill properties, annotated values and error bars
 1654       properties for example).
 1655 
 1656       You should note that despite the legend string related to
 1657       <em>one</em> set is entered in the set appearance popup, this is not
 1658       sufficient to display it. Displaying <em>all</em> legends is a graph
 1659       level decision, so the toggle is in the main tab of the <ref
 1660       name="graph appearance" id="graph-appearance"> popup.
 1661 
 1662       If you need special characters or special formatting in your
 1663       legend, you can use Grace escape sequences (the sequence will
 1664       appear verbatim in the text field but will be rendered on the
 1665       graph), see <ref name="typesetting" id="typesetting">. If you
 1666       don't remember the mapping between alphabetic characters and the
 1667       glyph you need in some specific fonts (mainly symbol and
 1668       zapfdingbats), you can invoke the font tool from the text
 1669       field by hitting CTRL-e. You can change fonts and select
 1670       characters from there, they will be copied back in the text
 1671       field when you press the "Accept" button. Beware of the
 1672       position of the cursor as you enter text or change font in the
 1673       font tool, the character or command will be inserted at this
 1674       position, not at the end of the string!
 1675 
 1676       <sect2> Axis properties <label id="axis-properties">
 1677       <p>
 1678       The axis properties popup can be displayed from both the "Plot"
 1679       menu and by double-clicking exactly on an axis (see <ref
 1680       name="Clicks and double clicks" id="clicks">). The pulldown menu
 1681       at the top allows to select the axis you want to operate on. The
 1682       "Active" toggle globally activates or deactivates the axis (all
 1683       GUI elements are insensitive for deactivated axes). The start
 1684       and stop fields depict the displayed range. Three types of
 1685       scales are available: linear, logarithmic or reciprocal, and
 1686       you can invert the axis (which normally increases from left to
 1687       right and from bottom to top).  The main tab includes the
 1688       properties you will need more often (axis label, tick
 1689       spacing and format for example), and other tabs are used to fine
 1690       tune some less frequently used options (fonts, sizes, colors,
 1691       placements, stagger, grid lines, special ticks, ...).
 1692 
 1693       If you need special characters or special formatting in your
 1694       label, you can use Grace escape sequences (the
 1695       sequence will appear verbatim in the text field but will be
 1696       rendered on the graph), see <ref name="typesetting"
 1697       id="typesetting">. If you don't remember the mapping between
 1698       alphabetic characters and the glyph you need in some specific
 1699       fonts (mainly symbol and zapfdingbats), you can invoke the font
 1700       tool from the text field by hitting CTRL-e. You can change fonts
 1701       and select characters from there, they will be copied back in
 1702       the text field when you press the "Accept" button. Beware of
 1703       the position of the cursor as you enter text or change font in
 1704       the font tool, the character or command will be inserted at this
 1705       position, not at the end of the string!
 1706 
 1707       Most of the controls in the dialog should be self-explanatory. One
 1708       that is not (and frequently missed) is the "Axis transform"
 1709       input field in the "Tick labels" tab. Entering there e.g. "-$t"
 1710       will make the tick labels show negates of the real coordinates their
 1711       ticks are placed at. You can use any expression understood by the
 1712       interpreter (see <ref id="command-interpreter"
 1713       name="command interpreter">).
 1714       
 1715       Once you have set the options as you want, you can apply
 1716       them. One useful feature is that you can set several axes at
 1717       once with the bottom pulldown menu (current axis, all axes
 1718       current graph, current axis all graphs, all axes all
 1719       graphs). Beware that you always apply the properties of all
 1720       tabs, not only the selected one.
 1721 
 1722    <sect1> View menu <label id="view-menu">
 1723    <p>
 1724       <sect2> Show locator bar <label id="show-locator-bar">
 1725       <p>
 1726       This toggle item shows or hides the locator below the menu bar.
 1727 
 1728       <sect2> Show status bar <label id="show-status-bar">
 1729       <p>
 1730        This toggle item shows or hides the status string below the
 1731        canvas.
 1732 
 1733      <sect2> Show tool bar <label id="show-tool-bar">
 1734       <p>
 1735       This toggle item shows or hides the tool bar at the left of the
 1736       canvas.
 1737 
 1738       <sect2> Page setup <label id="page-setup">
 1739       <p>
 1740       Set the properties of the display device. It is the same dialog as
 1741       in <ref name="Print setup" id="print-setup">.
 1742       
 1743       <sect2> Redraw <label id="redraw">
 1744       <p>
 1745       This menu item triggers a redrawing of the canvas.
 1746 
 1747       <sect2> Update all <label id="update-all">
 1748       <p>
 1749       This menu item causes an update of all GUI controls. Usually, everything
 1750       is updated automatically, unless one makes modifications by entering
 1751       commands in the <ref name="Command" id="commands"> tool.
 1752 
 1753 
 1754    <sect1> Window menu <label id="window-menu">
 1755     <p>
 1756       <sect2> Commands <label id="commands">
 1757       <p>
 1758         Command driven version of the interface to Grace. Here, commands
 1759         are typed at the "Command:" text item and executed when
 1760         &lt;Return&gt; is pressed. The command will be parsed and executed,
 1761         and the command line is placed in the history list. Items in the
 1762         history list can be recalled by simply clicking on them with the
 1763         left mouse button. For a reference on the Grace command interpreter,
 1764         see <ref id="command-interpreter" name="Command interpreter">.
 1765       </p>
 1766       <sect2> Point tracking <label id="point-tracking">
 1767       <p>
 1768         Not written yet...
 1769       </p>
 1770       <sect2> Drawing objects <label id="drawing-objects">
 1771       <p>
 1772         Not written yet...
 1773       </p>
 1774       <sect2> Font tool <label id="font-tool">
 1775       <p>
 1776         Not written yet...
 1777       </p>
 1778       <sect2> Console <label id="console">
 1779       <p>
 1780         The console window displays errors and results of some numerical
 1781         operations, e.g. nonlinear fit (see <ref id="non-linear-fit"
 1782         name="Non-linear fit">). The window is popped up automatically
 1783         whenever an error occurs or new result messages appear. This can
 1784         be altered by checking the "Options/Popup only on errors" option.
 1785       </p>
 1786 
 1787    <sect1> Help menu <label id="help-menu">
 1788    <p>
 1789       <sect2> On context <label id="on-context">
 1790       <p>
 1791         Click on any element of the interface to get context-sensitive help
 1792         on it. Only partially implemented at the moment.
 1793       </p>
 1794       <sect2> User's guide <label id="users-guide">
 1795       <p>
 1796         Browse the Grace user's guide.
 1797       </p>      
 1798       <sect2> Tutorial <label id="tutorial">
 1799       <p>
 1800         Browse the Grace tutorial.
 1801       </p>      
 1802       <sect2> FAQ <label id="faq">
 1803       <p>
 1804         Frequently Asked Questions with answers.
 1805       </p>      
 1806       <sect2> Changes <label id="changes">
 1807       <p>
 1808         The list of changes during the Grace development.
 1809       </p> 
 1810       <sect2> Examples <label id="examples">
 1811       <p>
 1812         The whole tree of submenus each loading a sample plot.
 1813       </p>      
 1814       <sect2> Comments <label id="comments">
 1815       <p>
 1816         Use this to send your suggestions or bug reports.
 1817       </p>        
 1818       <sect2> License terms <label id="license-terms">
 1819       <p>
 1820         Grace licensing terms will be displayed (GPL version 2).
 1821       </p>      
 1822       <sect2> About <label id="about">
 1823       <p>
 1824         A popup with basic info on the software, including some
 1825         configuration details. More details can be found when running Grace
 1826         with the "-version" command line flag.
 1827       </p>
 1828 
 1829 <!-- **************************************** -->
 1830 <sect>Command interpreter <label id="command-interpreter">
 1831   <p>
 1832 
 1833   <sect1>General notes
 1834 
 1835     <p>
 1836       The interpreter parses its input in a line-by-line manner. There may
 1837       be several statements per line, separated by semicolon (<tt>;</tt>).
 1838       The maximal line length is 4 kbytes (hardcoded). The parser is
 1839       case-insensitive and ignores lines beginning with the "<tt>#</tt>" sign.
 1840     </p>
 1841 
 1842   <sect1>Definitions
 1843 
 1844     <p>
 1845       <table loc="htbp">
 1846       <tabular ca="lp{5cm}l">
 1847         <hline>
 1848         Name | Description | Examples @
 1849         <hline>
 1850         expr |
 1851           Any numeric expression |
 1852           1.5 + sin(2) @
 1853         iexpr |
 1854           Any expression that evaluates to an integer |
 1855           25, 0.1 + 1.9, PI/asin(1) @
 1856         nexpr |
 1857           Non-negative iexpr |
 1858           2 - 1 @
 1859         indx |
 1860           Non-negative iexpr |
 1861           &nbsp; @
 1862         sexpr |
 1863           String expression |
 1864           "a string", "a " . "string", "square root of 4 = " . sqrt(4) @
 1865         vexpr |
 1866           Vector expression |
 1867           "2*x" @
 1868         <hline>
 1869       </tabular>
 1870       <caption>
 1871         <label id="types">
 1872         Basic types
 1873       </caption>
 1874       </table>
 1875     </p>
 1876 
 1877     <p>
 1878       <table loc="htbp">
 1879       <tabular ca="llll">
 1880         <hline>
 1881         Expression | Description | Types | Example @
 1882         <hline>
 1883         GRAPH&lsqb;<it>id</it>&rsqb; |
 1884           graph <it>id</it> |
 1885           indx <it>id</it> |
 1886           GRAPH&lsqb;0&rsqb; @
 1887         G<it>nn</it> |
 1888           graph <it>nn</it> |
 1889           <it>nn</it>: 0-99 |
 1890           G0 @
 1891         <hline>
 1892       </tabular>
 1893       <caption>
 1894         <label id="graph-sel">
 1895         Graph selections
 1896       </caption>
 1897       </table>
 1898     </p>
 1899 
 1900     <p>
 1901       <table loc="htbp">
 1902       <tabular ca="lp{5cm}ll">
 1903         <hline>
 1904         Expression | Description | Types | Example @
 1905         <hline>
 1906         <it>graph</it>.SETS&lsqb;<it>id</it>&rsqb; |
 1907           set <it>id</it> in graph <it>graph</it>|
 1908           indx <it>id</it>, graphsel <it>graph</it> |
 1909           GRAPH&lsqb;0&rsqb;.SETS&lsqb;1&rsqb; @
 1910       <it>graph</it>.S<it>nn</it> |
 1911           set <it>nn</it> in graph <it>graph</it>|
 1912           <it>nn</it>: 0-99, graphsel <it>graph</it> |
 1913           G0.S1 @
 1914         SET&lsqb;<it>id</it>&rsqb; |
 1915           set <it>id</it> in the current graph|
 1916           indx <it>id</it> |
 1917           SET&lsqb;1&rsqb; @
 1918         S<it>nn</it> |
 1919           set <it>nn</it> in the current graph|
 1920           <it>nn</it>: 0-99 |
 1921           S1 @
 1922         S&lowbar; |
 1923           the last implicitly (i.e. as a result of a data transformation) allocated set in the current graph|
 1924           - |
 1925           S&lowbar; @
 1926         S$ |
 1927           the active set in the current graph|
 1928           - |
 1929           S$ @
 1930         <hline>
 1931       </tabular>
 1932       <caption>
 1933         <label id="set-sel">
 1934         Set selections
 1935       </caption>
 1936       </table>
 1937     </p>
 1938 
 1939     <p>
 1940       <table loc="htbp">
 1941       <tabular ca="llll">
 1942         <hline>
 1943         Expression | Description | Types | Example @
 1944         <hline>
 1945         R<it>n</it> |
 1946           region <it>n</it> |
 1947           <it>n</it>: 0-4 |
 1948           R0 @
 1949         <hline>
 1950       </tabular>
 1951       <caption>
 1952         <label id="region-sel">
 1953         Region selections
 1954       </caption>
 1955       </table>
 1956     </p>
 1957 
 1958 
 1959     <p>
 1960       <table loc="htbp">
 1961       <tabular ca="llll">
 1962         <hline>
 1963         Expression | Description | Types | Example @
 1964         <hline>
 1965         COLOR <it>"colorname"</it> |
 1966           a mapped color <it>colorname</it> |
 1967           - |
 1968           COLOR "red" @
 1969         COLOR <it>id</it> |
 1970           a mapped color with ID <it>id</it> |
 1971           nexpr <it>id</it> |
 1972           COLOR 2 @
 1973         <hline>
 1974       </tabular>
 1975       <caption>
 1976         <label id="color-sel">
 1977         Color selections
 1978       </caption>
 1979       </table>
 1980     </p>
 1981 
 1982     <p>
 1983       <table loc="htbp">
 1984       <tabular ca="llll">
 1985         <hline>
 1986         Expression | Description | Types | Example @
 1987         <hline>
 1988         PATTERN <it>id</it> |
 1989           pattern with ID <it>id</it> |
 1990           nexpr <it>id</it> |
 1991           PATTERN 1 @
 1992         <hline>
 1993       </tabular>
 1994       <caption>
 1995         <label id="pattern-sel">
 1996         Pattern selections
 1997       </caption>
 1998       </table>
 1999     </p>
 2000 
 2001     <p>
 2002       <table loc="htbp">
 2003       <tabular ca="llll">
 2004         <hline>
 2005         Expression | Description | Types | Example @
 2006         <hline>
 2007         X |
 2008           the first column |
 2009           - |
 2010           X @
 2011         Y |
 2012           the second column |
 2013           - |
 2014           Y @
 2015         Y<it>n</it> |
 2016           (<it>n</it> + 2)-th column |
 2017           <it>n</it> = 0 - 4 |
 2018           Y3 @
 2019         <hline>
 2020       </tabular>
 2021       <caption>
 2022         <label id="datacol-sel">
 2023         Data column selections
 2024       </caption>
 2025       </table>
 2026     </p>
 2027 
 2028     <p>
 2029       Not finished yet...
 2030     </p>
 2031 
 2032   <sect1>Variables
 2033     <p>
 2034 
 2035       <table loc="htbp">
 2036       <tabular ca="ll">
 2037         <hline>
 2038         Variable        | Description      @
 2039         <hline>
 2040         datacolumn      | data column of current ("active") set @
 2041         set.datacolumn  | data column of set @
 2042         <hline>
 2043         vvar            | user-defined array @
 2044         <hline>
 2045         vvariable &lsqb;i:j&rsqb; | segment of a vector variable (elements from i-th to j-th inclusive, i &lt;= j) @
 2046         <hline>
 2047       </tabular>
 2048       <caption>
 2049         <label id="vvariables">
 2050         Vector variables
 2051       </caption>
 2052       </table>
 2053 
 2054     <p>
 2055 
 2056       <table loc="htbp">
 2057       <tabular ca="ll">
 2058         <hline>
 2059         Variable               | Description      @
 2060         <hline>
 2061         vvariable&lsqb;i&rsqb; | i-th element of a vector variable @
 2062         <hline>
 2063         var                    | user-defined variable @
 2064         <hline>
 2065       </tabular>
 2066       <caption>
 2067         <label id="svariables">
 2068         Scalar variables
 2069       </caption>
 2070       </table>
 2071 
 2072 
 2073   <sect1>Numerical operators and functions<label id="operators-and-functions">
 2074     <p>
 2075 
 2076       In numerical expressions, the infix format is used. Arguments of
 2077       both operators and functions can be either scalars or vector arrays.
 2078       Arithmetic, logical, and comparison operators are 
 2079       given in tables below.
 2080             
 2081       <p>
 2082 
 2083       <table loc="htbp">
 2084       <tabular ca="cl">
 2085         <hline>
 2086         Operator | Description      @
 2087         <hline>
 2088         +        | addition         @
 2089     -        | substraction     @
 2090     *        | multiplication   @
 2091     /        | division         @
 2092     %        | modulus          @
 2093     ^        | raising to power @
 2094         <hline>
 2095       </tabular>
 2096       <caption>
 2097         <label id="arithmetic-operators">
 2098         Arithmetic operators
 2099       </caption>
 2100       </table>
 2101       
 2102       <p>
 2103       
 2104       <table loc="htbp">
 2105       <tabular ca="cl">
 2106         <hline>
 2107         Operator               | Description @
 2108         <hline>
 2109         AND or &amp;&amp;      | logical AND @
 2110     OR or &verbar;&verbar; | logical OR  @
 2111     NOT or !               | logical NOT @
 2112         <hline>
 2113       </tabular>
 2114       <caption>
 2115         <label id="logical-operators">
 2116         Logical operators
 2117       </caption>
 2118       </table>
 2119       
 2120       <p>
 2121 
 2122       <table loc="htbp">
 2123       <tabular ca="cl">
 2124         <hline>
 2125         Operator    | Description           @
 2126         <hline>
 2127     EQ or ==    | equal                 @
 2128     NE or !=    | not equal             @
 2129     LT or &lt;  | less than             @
 2130     LE or &lt;= | less than or equal    @
 2131     GT or &gt;  | greater than          @
 2132     GE or &gt;= | greater than or equal @
 2133         <hline>
 2134       </tabular>
 2135       <caption>
 2136         <label id="comparison-operators">
 2137         Comparison operators
 2138       </caption>
 2139       </table>
 2140       
 2141       <p>
 2142         
 2143         Another conditional operator is the "?:" (or ternary) operator, which
 2144         operates as in C and many other languages.
 2145 
 2146         (expr1) ? (expr2) : (expr3);
 2147 
 2148         This expression evaluates to expr2 if expr1 evaluates to TRUE, and
 2149         expr3 if expr1 evaluates to FALSE.
 2150       <p>
 2151 
 2152       <table loc="htbp">
 2153       <tabular ca="ll">
 2154         <hline>
 2155         Function        | Description      @
 2156         <hline>
 2157     abs(x)          | absolute value @
 2158     acos(x)         | arccosine @
 2159     acosh(x)        | hyperbolic arccosine @
 2160     asin(x)         | arcsine @
 2161     asinh(x)        | hyperbolic arcsine @
 2162     atan(x)         | arctangent @
 2163     atan2(y,x)      | arc tangent of two variables @
 2164     atanh(x)        | hyperbolic arctangent @
 2165     ceil(x)         | greatest integer function @
 2166     cos(x)          | cosine @
 2167     cosh(x)         | hyperbolic cosine @
 2168     exp(x)          | e^x @
 2169     fac(n)          | factorial function, n! @
 2170     floor(x)        | least integer function @
 2171     irand(n)        | random integer less than n @
 2172     ln(x)           | natural log  @
 2173     log10(x)        | log base 10 @
 2174     log2(x)         | base 2 logarithm of x @
 2175     maxof(x,y)      | returns greater of x and y @
 2176     mesh(n)         | mesh array (0 ... n - 1) @
 2177     mesh(x1, x2, n) | mesh array of n equally spaced points between x1 and x2 inclusive @
 2178     minof(x,y)      | returns lesser of x and y @
 2179     mod(x,y)        | mod function (also x % y) @
 2180     pi              | the PI constant @
 2181     rand            | pseudo random number distributed uniformly on (0.0,1.0) @
 2182     rand(n)         | array of n random numbers @
 2183     rint(x)         | round to closest integer @
 2184     rsum(x)         | running sum of x @
 2185     sgn(x)          | signum function @
 2186     sin(x)          | sine function @
 2187     sinh(x)         | hyperbolic sine @
 2188     sqr(x)          | x^2 @
 2189     sqrt(x)         | x^0.5 @
 2190     tan(x)          | tangent function @
 2191     tanh(x)         | hyperbolic tangent @
 2192         <hline>
 2193       </tabular>
 2194       <caption>
 2195         <label id="functions">
 2196         Functions
 2197       </caption>
 2198       </table>
 2199 
 2200       <table loc="htbp">
 2201       <tabular ca="ll">
 2202         <hline>
 2203         Function        | Description      @
 2204         <hline>
 2205     chdtr(df, x)    | chi-square distribution @
 2206     chdtrc(v, x)    | complemented Chi-square distribution @
 2207     chdtri(df, y)   | inverse of complemented Chi-square distribution @
 2208     erf(x)          | error function @
 2209     erfc(x)         | complement of error function @
 2210     fdtr(df1, df2, x) | F distribution function @
 2211     fdtrc(x)        | complemented F distribution @
 2212     fdtri(x)        | inverse of complemented F distribution @
 2213     gdtr(a, b, x)   | gamma distribution function @
 2214     gdtrc(a, b, x)  | complemented gamma distribution function @
 2215     ndtr(x)         | Normal distribution function @
 2216     ndtri(x)        | inverse of Normal distribution function @
 2217     norm(x)         | gaussian density function @
 2218     pdtr(k, m)      | Poisson distribution @
 2219     pdtrc(k, m)     | complemented Poisson distribution @
 2220     pdtri(k, y)     | inverse Poisson distribution @
 2221     rnorm(xbar,s)   | pseudo random number distributed N(xbar,s) @
 2222     stdtr(k, t)     | Student's t distribution @
 2223     stdtri(k, p)    | functional inverse of Student's t distribution @
 2224         <hline>
 2225       </tabular>
 2226       <caption>
 2227         <label id="stat-functions">
 2228         Statistical functions
 2229       </caption>
 2230       </table>
 2231 
 2232       <table loc="htbp">
 2233       <tabular ca="ll">
 2234         <hline>
 2235         Function        | Description      @
 2236         <hline>
 2237     ai(x), bi(x)    | Airy functions (two independent solutions of the differential equation <tt>y''(x) = xy</tt>) @
 2238     beta(x)         | beta function @
 2239     chi(x)          | hyperbolic cosine integral @
 2240     ci(x)           | cosine integral @
 2241     dawsn(x)        | Dawson's integral @
 2242     ellie(phi, m)   | incomplete elliptic integral of the second kind @
 2243     ellik(phi, m)   | incomplete elliptic integral of the first kind @
 2244     ellpe(m)        | complete elliptic integral of the second kind @
 2245     ellpk(m)        | complete elliptic integral of the first kind @
 2246     expn(n, x)      | exponential integral @
 2247     fresnlc(x)      | cosine Fresnel integral @
 2248     fresnls(x)      | sine Fresnel integral @
 2249     gamma(x)        | gamma function @
 2250     hyp2f1(a, b, c, x) | Gauss hyper-geometric function @
 2251     hyperg(a, b, x) | confluent hyper-geometric function @
 2252     i0e(x)          | modified Bessel function of order zero, exponentially  scaled @
 2253     i1e(x)          | modified Bessel function of order one, exponentially   scaled @
 2254     igam(a, x)      | incomplete gamma integral @
 2255     igamc(a, x)     | complemented incomplete gamma integral @
 2256     igami(a, p)     | inverse of complemented incomplete gamma integral @
 2257     incbet(a, b, x) | incomplete beta integral @
 2258     incbi(a, b, y)  | Inverse of incomplete beta integral @
 2259     iv(v, x)        | modified Bessel function of order v @
 2260     jv(v, x)        | Bessel function of order v @
 2261     k0e(x)          | modified Bessel function, third kind, order zero, exponentially scaled @
 2262     k1e(x)          | modified Bessel function, third kind, order one, exponentially scaled @
 2263     kn(n, x)        | modified Bessel function, third kind, integer order @
 2264     lbeta(x)        | natural log of &verbar;beta(x)&verbar; @
 2265     lgamma(x)       | log of gamma function @
 2266     psi(x)          | psi (digamma) function @
 2267     rgamma(x)       | reciprocal gamma function @
 2268     shi(x)          | hyperbolic sine integral @
 2269     si(x)           | sine integral @
 2270     spence(x)       | dilogarithm @
 2271     struve(v, x)    | Struve function @
 2272     voigt(gamma, sigma, x) | Voigt function (convolution of Lorentzian and Gaussian) @
 2273     yv(v, x)        | Bessel function of order v @
 2274     zeta(x, q)      | Riemann zeta function of two arguments @
 2275     zetac(x)        | Riemann zeta function   @
 2276         <hline>
 2277       </tabular>
 2278       <caption>
 2279         <label id="spec-functions">
 2280         Special math functions
 2281       </caption>
 2282       </table>
 2283 
 2284       <p>
 2285 
 2286       <table loc="htbp">
 2287       <tabular ca="cl">
 2288         <hline>
 2289         Function    | Description                    @
 2290         <hline>
 2291     MIN(x)      | min value of array x           @
 2292     MAX(x)      | max value of array x           @
 2293     AVG(x)      | average of array x             @
 2294     SD(x)       | standard deviation of array x  @
 2295     SUM(x)      | sum of all elements of array x @
 2296     INT(x,y)    | integral of y dx               @
 2297     IMIN(x)     | index of min value of array x  @
 2298     IMAX(x)     | index of max value of array x  @
 2299         <hline>
 2300       </tabular>
 2301       <caption>
 2302         <label id="aggregate-functions">
 2303         Aggregate functions
 2304       </caption>
 2305       </table>     
 2306 
 2307   <sect1>Procedures
 2308     <p>
 2309      Methods of directly manipulating the data corresponding to the
 2310      Data|Transformation menu are described in table <ref
 2311      id="transformations">. To evaluate expressions, you can directly submit
 2312      them to the command interpreter like you would in the evaluate expression
 2313      window. As an example, S1.X = S1.X * 0.000256 scales the x-axis
 2314      coordinates. The functionality of the 'Sample points' menu entry can be
 2315      obtained through RESTRICT.
 2316 
 2317       <table loc="htbp">
 2318       <tabular ca="p{3cm}p{5cm}p{3.5cm}p{3cm}">
 2319         <hline>
 2320         Statement | Description | Types | Example @
 2321         <hline>
 2322         RUNAVG (set, npoints) |
 2323           running average of <it>set</it> using <it>npoints</it> number of points |
 2324           nexpr <it>npoints</it> |
 2325           RUNAVG (S0, 100) @
 2326         RUNMED (set, npoints) |
 2327           running median of <it>set</it> using <it>npoints</it> number of points |
 2328           nexpr <it>npoints</it> |
 2329           RUNMED (S0, 100) @
 2330         RUNMIN (set, npoints) |
 2331           running minimum of <it>set</it> using <it>npoints</it> number of points |
 2332           nexpr <it>npoints</it> |
 2333           RUNMIN (S0, 100) @
 2334         RUNMAX (set, npoints) |
 2335           running maximum of <it>set</it> using <it>npoints</it> number of points |
 2336           nexpr <it>npoints</it> |
 2337           RUNMAX (S0, 100) @
 2338         RUNSTD (set, npoints) |
 2339           running standard deviation of <it>set</it> using <it>npoints</it> number of points |
 2340           nexpr <it>points</it> |
 2341           RUNSTD (S0, 100) @
 2342         INTERPOLATE (set, mesh, method, strict) |
 2343           interpolate <it>set</it> on a sampling <it>mesh</it> using <it>method</it>. <it>strict</it> flag controls whether result should be bound within the source set |
 2344           vexpr <it>mesh</it>, <it>method</it>: one of LINEAR, SPLINE, and ASPLINE, onoff <it>strict</it> |
 2345           INTERPOLATE (S0, S1.X, ASPLINE, OFF) @
 2346         HISTOGRAM (set, bins, cumulative, normalize) |
 2347           calculate histogram of <it>set</it> on defined <it>bins</it>. <it>cumulative</it> and <it>normalize</it> flags control whether to calculate cumulative and normalized (aka PDF) histograms, respectively.  Data points are placed at upper limit of the bin |
 2348           vexpr <it>bins</it>, onoff <it>cumulative</it>, onoff <it>normalize</it> |
 2349           HISTOGRAM (S0, MESH(0, 1, 11), OFF, ON) @
 2350         INTEGRATE (set) |
 2351           cumulative integral of <it>set</it> |
 2352           &nbsp; |
 2353           INTEGRATE (S0) @
 2354         XCOR (set1, set2, maxlag, covar) |
 2355           calculate cross-correlation (or -covariance if the <it>covar</it> flag is set) of <it>set1</it> with <it>set2</it> with maximum lag <it>maxlag</it>. |
 2356           nexpr <it>maxlag</it>, onoff <it>covar</it> |
 2357           XCOR (S0, S0, 50, OFF) @
 2358         LINCONV (set1, set2) |
 2359           calculate linear convolution of the array of ordinates of <it>set1</it> with that of <it>set2</it>. |
 2360           &nbsp; |
 2361           LINCONV (S0, S1) @
 2362         RESTRICT (set, restriction) |
 2363           filter <it>set</it> according to logical <it>restriction</it>. The original set will be overwritten |
 2364           vexpr <it>restriction</it> |
 2365           RESTRICT (S0, S0.X < 0) @
 2366         RESTRICT (set, region, negate) |
 2367           filter <it>set</it> by keeping only points lying inside/outside <it>region</it>. The original set will be overwritten |
 2368           onoff <it>negate</it>|
 2369           RESTRICT (S0, R1, OFF) @
 2370         <hline>
 2371       </tabular>
 2372       <caption>
 2373         <label id="transformations">
 2374         Transformations
 2375       </caption>
 2376       </table>
 2377     </p>
 2378 
 2379     <p>
 2380       Not finished yet...
 2381     </p>
 2382 
 2383   <sect1>Device parameters
 2384     <p>
 2385     For producing "hard copy", several parameters can be set via the command
 2386     interpreter.  They are summarized in table 
 2387     <ref id="device-parameters" name="Device parameters">.
 2388 
 2389       <table loc="htbp">
 2390       <tabular ca="lp{7cm}">
 2391         <hline>
 2392         Command                                           | Description   @
 2393         <hline>
 2394         PAGE SIZE xdim, ydim                              | set page dimensions (in pp) of all devices  @
 2395         PAGE RESIZE xdim, ydim                            | same as above plus rescale the current plot accordingly  @
 2396         DEVICE <it>"devname"</it> PAGE SIZE xdim, ydim    | set page dimensions (in pp) of device <it>devname</it>  @
 2397         DEVICE <it>"devname"</it> DPI dpi                 | set device's dpi (dots per pixel) @
 2398         DEVICE <it>"devname"</it> FONT onoff              | enable/disable usage of built-in fonts for device <it>devname</it> @
 2399         DEVICE <it>"devname"</it> FONT ANTIALIASING onoff | enable/disable font aliasing for device <it>devname</it> @
 2400         DEVICE <it>"devname"</it> OP <it>"options"</it>   | set device specific options (see <ref id="device-settings" name="Device-specific settings">) @
 2401         HARDCOPY DEVICE <it>"devname"</it>                | set device <it>devname</it> as current hardcopy device @
 2402         PRINT TO <it>"filename"</it>                      | set print output to <it>filename</it> (but do not print) @
 2403         PRINT TO DEVICE                                   | set print output to hardcopy device (but do not print) @
 2404         <hline>
 2405       </tabular>
 2406       <caption>
 2407         <label id="device-parameters">
 2408         Device parameters
 2409       </caption>
 2410       </table>
 2411 
 2412   <sect1>Flow control
 2413 
 2414     <p>
 2415       <table loc="htbp">
 2416       <tabular ca="lp{5cm}ll">
 2417         <hline>
 2418         Statement | Description | Types | Example @
 2419         <hline>
 2420         EXIT(<it>status</it>) |
 2421           cause normal program termination with exit status <it>status</it> |
 2422           iexpr <it>status</it> |
 2423           EXIT(0) @
 2424         EXIT |
 2425           cause normal program termination; same as EXIT(0) |
 2426           &nbsp; |
 2427           EXIT @
 2428         HELP <it>url</it> |
 2429           open a HTML document pointed to by <it>url</it> |
 2430           sexpr <it>url</it> |
 2431           HELP "doc/FAQ.html" @
 2432         HELP |
 2433           open User's Guide |
 2434           &nbsp; |
 2435           HELP @
 2436         PRINT |
 2437           execute print job |
 2438           &nbsp; |
 2439           PRINT @
 2440         AUTOSCALE |
 2441           scale the graph |
 2442           &nbsp; |
 2443           AUTOSCALE @
 2444         AUTOSCALE XAXES |
 2445           scale the graph in x only |
 2446           &nbsp; |
 2447           AUTOSCALE XAXES @
 2448         AUTOSCALE YAXES |
 2449           scale the graph in y only |
 2450           &nbsp; |
 2451           AUTOSCALE YAXES @
 2452         AUTOSCALE set |
 2453           scale to a specific set |
 2454           &nbsp; |
 2455           AUTOSCALE S0 @
 2456         AUTOTICKS |
 2457           autotick all axes |
 2458           &nbsp; |
 2459           AUTOTICKS @
 2460         REDRAW |
 2461           refresh the canvas to reflect the current project state |
 2462           &nbsp; |
 2463           REDRAW @
 2464         SLEEP <it>n</it> |
 2465           sleep for <it>n</it> seconds |
 2466           expr <it>n</it> |
 2467           SLEEP(3) @
 2468         UPDATEALL |
 2469           update the GUI (graph and set selectors etc) to reflect the current project state |
 2470           &nbsp; |
 2471           UPDATEALL @
 2472         SAVEALL <it>"file"</it> |
 2473           save project to <it>file</it> |
 2474           sexpr <it>file</it> |
 2475           SAVEALL "foo.agr" @
 2476         LOAD <it>"file"</it> |
 2477           load project <it>file</it> |
 2478           sexpr <it>file</it> |
 2479           LOAD "foo.agr" @
 2480         <hline>
 2481       </tabular>
 2482       <caption>
 2483         <label id="flow-control">
 2484         Flow control
 2485       </caption>
 2486       </table>
 2487     </p>
 2488 
 2489   <sect1>Declarations
 2490     <p>
 2491     User-defined variables are set and used according to the syntax
 2492     described in table <ref id="user-variables" name="User variables">.
 2493 
 2494       <table loc="htbp">
 2495       <tabular ca="lp{7cm}ll">
 2496         <hline>
 2497         Statement | Description | Types | Example @
 2498         <hline>
 2499         DEFINE <it>var</it> |
 2500           define new scalar variable <it>var</it> |
 2501           &nbsp; |
 2502           DEFINE myvar @
 2503         DEFINE <it>vvar</it>&lsqb;&rsqb; |
 2504           define new vector variable <it>vvar</it> of zero length |
 2505           &nbsp; |
 2506           DEFINE myvvar&lsqb;&rsqb; @
 2507         DEFINE <it>vvar</it>&lsqb;<it>n</it>&rsqb; |
 2508           define new vector variable <it>vvar</it> of length <it>n</it> |
 2509           nexpr <it>n</it> |
 2510           DEFINE myvvar&lsqb;10&rsqb; @
 2511         <hline>
 2512         CLEAR <it>var</it> |
 2513           undefine new variable <it>var</it> and deallocate associated storage |
 2514           &nbsp; |
 2515           CLEAR myvar @
 2516         <hline>
 2517         <it>vvar</it> LENGTH <it>n</it> |
 2518           reallocate vector variable <it>vvar</it> |
 2519           nexpr <it>n</it> |
 2520           myvvar LENGTH 25 @
 2521         <hline>
 2522       </tabular>
 2523       <caption>
 2524         <label id="user-variables">
 2525         User variables
 2526       </caption>
 2527       </table>
 2528     </p>
 2529 
 2530     <p>
 2531       Not finished yet...
 2532     </p>
 2533 
 2534   <sect1>Graph properties
 2535   <p>
 2536   We divide the commands pertaining to the properties and appearance of
 2537   graphs into those which directly manipulate the graphs and those that 
 2538   affect the appearance of graph elements---the parameters that can appear
 2539   in a Grace project file.
 2540   </p>
 2541   
 2542   <sect2>Command operations
 2543     <p>
 2544      General graph creation/annihilation and control commands appear in
 2545      table <ref id="graph-ops" name="Graph operations">.
 2546 
 2547       <table loc="htbp">
 2548       <tabular ca="p{3.5cm}p{4.5cm}p{3cm}p{3.5cm}">
 2549         <hline>
 2550         Statement | Description | Types | Example @
 2551         <hline>
 2552     FOCUS <it>graph</it> | Makes <it>graph</it> current and unhides it if necessary |
 2553                           graphsel <it>graph</it> | FOCUS G0 @
 2554     KILL <it>graph</it> | Kills <it>graph</it> | graphsel <it>graph</it> | KILL G0 @
 2555     ARRANGE(<it>nrows</it>, <it>ncols</it>, <it>offset</it>, <it>hgap</it>, <it>vgap</it>) |
 2556          Arrange existing graphs (or add extra if needed) to form an <it>nrows</it> by <it>ncols</it> matrix, leaving <it>offset</it> at each page edge with <it>hgap</it> and <it>vgap</it> relative horizontal and vertical spacings |
 2557          nexpr <it>nrows</it>, <it>ncols</it>, expr <it>offset</it>, <it>hgap</it>, <it>vgap</it> |
 2558          ARRANGE(2, 2, 0.1, 0.15, 0.2) @
 2559     ARRANGE(<it>nrows</it>, <it>ncols</it>, <it>offset</it>, <it>hgap</it>, <it>vgap</it>, <it>hvinv</it>, <it>hinv</it>, <it>vinv</it>) |
 2560          Same as above, plus additional <it>hvinv</it>, <it>hinv</it>, and <it>vinv</it> flags allowing to alter the order of the matrix filling |
 2561          nexpr <it>nrows</it>, <it>ncols</it>, expr <it>offset</it>, <it>hgap</it>, <it>vgap</it>, onoff <it>hvinv</it>, <it>hinv</it>, <it>vinv</it> |
 2562          ARRANGE(2, 2, 0.1, 0.15, 0.2, ON, OFF, ON) @
 2563     ARRANGE(<it>nrows</it>, <it>ncols</it>, <it>offset</it>, <it>hgap</it>, <it>vgap</it>, <it>hvinv</it>, <it>hinv</it>, <it>vinv</it>, <it>snake</it>) |
 2564          Same as above, plus additional <it>snake</it> flag allowing to fill the matrix in a snake-like fashion |
 2565          nexpr <it>nrows</it>, <it>ncols</it>, expr <it>offset</it>, <it>hgap</it>, <it>vgap</it>, onoff <it>hvinv</it>, <it>hinv</it>, <it>vinv</it>, <it>snake</it> |
 2566          ARRANGE(2, 2, 0.1, 0.15, 0.2, ON, OFF, ON, ON) @
 2567       </tabular>
 2568       <caption>
 2569         <label id="graph-ops">
 2570         Graph operations
 2571       </caption>
 2572       </table>
 2573     </p>
 2574    <sect2>Parameter settings
 2575     <p>
 2576     Setting the active graph and its type is accomplished with the commands
 2577     found in table <ref id="graphsel-pars" name="Graph selection parameters">.
 2578     
 2579       <table loc="htbp">
 2580       <tabular ca="p{3.25cm}p{4.5cm}p{3.5cm}p{3.25cm}">
 2581         <hline>
 2582         Statement | Description | Types | Example @
 2583         <hline>
 2584     WITH <it>graph</it> | Makes  <it>graph</it> current | 
 2585                         graphsel <it>graph</it> | WITH G0 @
 2586     TYPE <it>type</it>  | Sets <it>type</it> of current graph |
 2587                        graphtype <it>type</it> |TYPE XY @
 2588      <it>graph</it> onoff| (De)Activates selected <it>graph</it> | graphsel <it>graph</it>, onoff | G0 ON @
 2589      <it>graph</it> HIDDEN onoff | Hides selected <it>graph</it> | graphsel <it>graph</it>, onoff | G1 HIDDEN TRUE @
 2590      <it>graph</it> TYPE <it>type</it> | Sets <it>type</it> of <it>graph</it>  |
 2591               graphsel <it>graph</it>, graphtype <it>type</it> | G0 TYPE XYDY @
 2592       </tabular>
 2593       <caption>
 2594         <label id="graphsel-pars">
 2595         Graph selection parameters
 2596       </caption>
 2597       </table>
 2598 
 2599       The axis range and scale of the current graph as well as its  location
 2600       on the plot viewport are set with the commands listed in table
 2601       <ref id="graphaxis-pars" name="Axis parameters">.
 2602       <table loc="htbp">
 2603       <tabular ca="p{3.25cm}p{4.5cm}p{3.5cm}p{3.25cm}">
 2604         <hline>
 2605         Statement | Description | Types | Example @
 2606         <hline>
 2607      WORLD XMIN <it>xmin</it> | Sets minimum value of  current graph's x axis to <it>xmin</it> |
 2608               expr <it>xmin</it> | WORLD XMIN -10 @
 2609      WORLD XMAX <it>xmax</it> | Sets maximum value of  current graph's x axis to <it>xmin</it> |
 2610               expr <it>xmax</it> | WORLD XMAX 22.5 @
 2611      WORLD YMIN <it>ymin</it> | Sets minimum value of current graph's y axis to <it>ymin</it> |
 2612               expr <it>ymin</it> | WORLD YMIN 0 @
 2613      WORLD YMAX <it>ymax</it> | Sets maximum value of current graph's y axis to <it>ymax</it> |
 2614               expr <it>ymax</it> | WORLD YMAX 1e4 @
 2615      VIEW XMIN <it>xmin</it> | Sets left edge of current graph at x=<it>xmin</it> in the viewport |
 2616               expr <it>xmin</it>| VIEW XMIN .2 @
 2617      VIEW XMAX <it>xmax</it> | Sets right edge of current graph at x=<it>xmax</it> in the viewport |
 2618               expr <it>xmax</it>| VIEW XMAX 1.0 @
 2619      VIEW YMIN <it>ymin</it> | Sets bottom edge of current graph at y=<it>ymin</it> in the viewport |
 2620               expr <it>ymin</it>| VIEW YMIN .25 @
 2621          VIEW YMAX <it>ymax</it> | Sets top edge of current graph at y=<it>ymax</it> in the viewport | 
 2622               expr <it>ymax</it>| VIEW YMAX .75 @
 2623      VIEW <it>xmin</it>, <it>ymin</it>, <it>xmax</it>, <it>ymax</it>| Sets graph's viewport |
 2624               expr <it>xmin</it>, <it>ymin</it>, <it>xmax</it>, <it>ymax</it>| VIEW 0.15, 0.15, 1.15, 0.85 @
 2625      XAXES SCALE <it>type</it>  | Set scaling of the x axes to <it>type</it> |
 2626               <it>type</it>: one of NORMAL, LOGARITHMIC, or RECIPROCAL | XAXES SCALE NORMAL @
 2627      YAXES SCALE <it>type</it>  | Set scaling of the y axes to <it>type</it>  |
 2628               <it>type</it>: one of NORMAL, LOGARITHMIC, or RECIPROCAL | YAXES SCALE LOGARITHMIC @
 2629      XAXES INVERT onoff | If ON, draws xmin to xmax from right to left | 
 2630               onoff | XAXES INVERT OFF @
 2631      YAXES INVERT onoff | If ON, draws ymin to ymax from  top to bottom | 
 2632               onoff | YAXES INVERT OFF @
 2633      AUTOSCALE ONREAD <it>type</it> | Set automatic scaling on read according to <it>type</it> |
 2634               <it>type</it>: one of  NONE, XAXES, YAXES, XYAXES | AUTOSCALE ONREAD NONE @
 2635       </tabular>
 2636       <caption>
 2637         <label id="graphaxis-pars">
 2638         Axis parameters
 2639       </caption>
 2640       </table>
 2641 
 2642       The commands to set the appearance and textual content of titles and
 2643       legends are given in table 
 2644       <ref id="graphlegend-pars" name="Titles and legends">.
 2645 
 2646       <table loc="htbp">
 2647       <tabular ca="p{3.5cm}p{4.5cm}p{3.25cm}p{3.25cm}">
 2648         <hline>
 2649         Statement | Description | Types | Example @
 2650         <hline>
 2651      TITLE <it>title</it>       | Sets the title of current graph |
 2652               sexpr <it>title</it> | TITLE "Foo" @
 2653      TITLE FONT <it>font</it>  | Selects font of title string |
 2654               fontsel <it>font</it> | TITLE FONT 1 @
 2655      TITLE SIZE <it>size</it>  | Sets size of title string |
 2656               expr <it>size</it> | TITLE SIZE 1.5 @
 2657      TITLE COLOR <it>color</it> | Sets color of title string | 
 2658               colorsel <it>color</it> | TITLE COLOR 1 @
 2659      SUBTITLE <it>subtitle</it> | Sets the subtitle of current graph |
 2660               sexpr <it>subtitle</it> | SUBTITLE "Bar" @
 2661      SUBTITLE FONT <it>font</it>  | Selects font of subtitle string |
 2662               fontsel <it>font</it> | SUBTITLE FONT "Times-Italic" @
 2663      SUBTITLE SIZE <it>size</it>  | Sets size of subtitle string |
 2664               expr <it>size</it> | SUBTITLE SIZE .60 @
 2665      SUBTITLE COLOR <it>color</it> | Sets color of subtitle string |
 2666               colorsel <it>color</it> | SUBTITLE COLOR "blue" @
 2667      LEGEND onoff | Toggle legend display |onoff | LEGEND ON @
 2668      LEGEND LOCTYPE <it>type</it> | Posistion legend in <it>type</it> coordinates |
 2669        <it>type</it>: either WORLD or VIEW | LEGEND LOCTYPE WORLD @
 2670      LEGEND <it>xloc, yloc</it> | Set location of legend box (upper left corner) | 
 2671        expr <it>xloc, yloc</it> | LEGEND .5,.75 @
 2672      LEGEND FONT <it>font</it>| Set legend font type |
 2673        fontsel <it>font</it> | LEGEND FONT "Helvetica" @
 2674      LEGEND CHAR SIZE <it>size</it> | Sets size of legend label characters (1 is normal)|
 2675      expr <it>size</it> | LEGEND CHAR SIZE .30 @
 2676      LEGEND <it>color</it>| Set color of legend text |
 2677        colorsel <it>color</it> | LEGEND COLOR 1 @
 2678      LEGEND VGAP <it>gap</it> | Sets vertical gap between legend entries |
 2679        nexpr <it>gap</it> | LEGEND VGAP 1 @
 2680      LEGEND HGAP <it>gap</it> | Sets horizontal gap between symbol and description |
 2681        nexpr <it>gap</it> | LEGEND HGAP 4 @
 2682      LEGEND LENGTH <it>length</it>| Sets <it>length</it> of legend| 
 2683        nexpr <it>length</it> | LEGEND LENGTH 5 @
 2684      LEGEND INVERT onoff | Determines relationship between order of sets and order of legend labels |
 2685        onoff | LEGEND INVERT true @
 2686      LEGEND BOX onoff | Determines if the legend bounding box is drawn |
 2687        onoff | LEGEND BOX off @
 2688      LEGEND BOX COLOR <it>color</it>  | Sets color of legend bounding box | colorsel <it>color</it> |
 2689        LEGEND BOX COLOR 1@
 2690      LEGEND BOX PATTERN <it>pattern</it>| Sets pattern of legend bounding box | patternsel <it>pattern</it> |
 2691        LEGEND BOX PATTERN 2@
 2692      LEGEND BOX LINESTYLE <it>style</it>| Sets line style of bounding box |nexpr <it>style</it> |
 2693        LEGEND BOX LINESTYLE 1 @
 2694      LEGEND BOX LINEWIDTH <it>width</it>| Sets line width of bounding box|nexpr <it>width</it> | 
 2695        LEGEND BOX LINEWIDTH 2 @
 2696      LEGEND BOX FILL onoff | Determines if the legend bounding box is filled |
 2697        onoff | LEGEND BOX FILL false @
 2698      LEGEND BOX FILL COLOR <it>color</it>  | Sets color of legend box fill | colorsel <it>color</it> | 
 2699        LEGEND BOX COLOR 3 @
 2700      LEGEND BOX FILL <it>pattern</it>| Sets pattern of legend box fill |patternsel <it>pattern</it> |
 2701        LEGEND BOX FILL PATTERN 1@
 2702       </tabular>
 2703       <caption>
 2704         <label id="graphlegend-pars">
 2705         Titles and legends
 2706       </caption>
 2707       </table>
 2708     </p>
 2709    <p>
 2710    Not finished yet...
 2711    </p>
 2712    
 2713   <sect1>Set properties
 2714     <p>
 2715     Again, as with the graphs, we separate those parser commands that
 2716     manipulate the data in a set from the commands that determine
 2717     parameters---elements that are saved in a project file.
 2718 
 2719     <sect2>Commands
 2720     <p>
 2721     Operations for set I/O are summarized in table 
 2722     <ref id="set-io" name="Set input, output,  and creation">.  (Note that
 2723     this is incomplete  and only lists <it>input</it> commands at the moment.)
 2724 
 2725       <table loc="htbp">
 2726       <tabular ca="p{3.5cm}p{4.5cm}p{3cm}p{3.5cm}">
 2727         <hline>
 2728         Statement | Description | Types | Example @
 2729         <hline>
 2730         READ <it>"file"</it> | Reads <it>file</it> as a single set |
 2731                          sexpr <it>file</it> | READ "foo.dat" @
 2732         READ <it>settype</it> <it>"file"</it> | Reads <it>file</it> into a single set of type <it>settype</it> |
 2733              xytype <it>settype</it>, sexpr <it>file</it> | READ xydy "bar.dat" @
 2734     READ NXY <it>"file"</it> | Reads <it>file</it> as NXY data |
 2735                          sexpr <it>file</it> | READ NXY "gad.dat" @
 2736     READ BLOCK <it>"file"</it> | Reads <it>file</it> as block data |
 2737                          sexpr <it>file</it> | READ BLOCK "zooks.dat" @
 2738     KILL BLOCK | Kills the current block data and frees the associated memory |
 2739                          &nbsp; | KILL BLOCK @
 2740     BLOCK <it>settype</it> <it>columns</it> | Forms a data set of type <it>settype</it> using <it>columns</it> from current block data file. |
 2741                  xytype <it>settype</it>, sexpr <it>columns</it> | BLOCK xydxdy "0:2:1:3" @
 2742         WRITE <it>set</it> | writes <it>set</it> to stdout|
 2743              setsel <it>set</it> | WRITE G0.S1 @
 2744         WRITE <it>set</it> FORMAT <it>"formatstring"</it> | writes <it>set</it> to stdout using format specification <it>formatstring</it> |
 2745              setsel <it>set</it> sexpr <it>formatstring</it> | WRITE G0.S1 FORMAT "%18.8g" @
 2746         WRITE <it>set</it> FILE <it>"file"</it> | writes <it>set</it> to <it>file</it> |
 2747              setsel <it>set</it> sexpr <it>file</it> | WRITE G0.S1 FILE "data.dat" @
 2748         WRITE <it>set</it> FILE <it>"file"</it> FORMAT <it>"formatstring"</it> | writes <it>set</it> to <it>file</it> using format specification <it>formatstring</it> |
 2749              setsel <it>set</it> sexpr <it>file</it> sexpr <it>formatstring</it> | WRITE G0.S1 FILE "data.dat" FORMAT "%18.8g" @
 2750       </tabular>
 2751       <caption>
 2752         <label id="set-io">
 2753         Set input, output,  and creation
 2754       </caption>
 2755       </table>
 2756 
 2757       The parser commands analogous to the Data|Data set operations dialogue
 2758       can be found in table <ref id="set-ops" name="Set operations">. 
 2759       <table loc="htbp">
 2760       <tabular ca="p{3.5cm}p{4.5cm}p{3cm}p{3.5cm}">
 2761         <hline>
 2762         Statement | Description | Types | Example @
 2763         <hline>
 2764     COPY <it>src</it> TO <it>dest</it>  | Copies <it>src</it> to <it>dest</it>|
 2765        setsel <it>src,dest</it> | COPY S0 TO S1 @
 2766     MOVE <it>src</it> TO <it>dest</it>  | Moves <it>src</it> to <it>dest</it> |
 2767        setsel <it>src,dest</it> | MOVE G0.S0 TO G1.S0 @
 2768     SWAP <it>src</it> AND <it>dest</it>  | Interchanges <it>src</it> and <it>dest</it> | 
 2769        setsel <it>src,dest</it> | SWAP G0.S0 AND G0.S1 @
 2770     KILL <it>set</it> | Kills <it>set</it> | setsel <it>set</it> | KILL G0.S0 @
 2771       </tabular>
 2772       <caption>
 2773         <label id="set-ops">
 2774         Set operations
 2775       </caption>
 2776       </table>
 2777     </p>
 2778     <p>
 2779     Not Finished yet...
 2780 
 2781     <sect2>Parameter settings
 2782     <p>
 2783       Not written yet...
 2784       
 2785 <!-- **************************************** -->
 2786 <sect>Advanced topics
 2787   <p>
 2788 
 2789   <sect1>Fonts<label id="fonts">
 2790     <p>
 2791     For all devices, Grace uses Type1 fonts. Both PFA (ASCII) and PFB
 2792     (binary) formats can be used.
 2793     <p>
 2794     <sect2>Font configuration
 2795       <p>
 2796       The file responsible for the font configurations of Grace is
 2797       <tt>fonts/FontDataBase</tt>. The first line contains a positive integer
 2798       specifying the number of fonts declared in that file. All remaining lines
 2799       contain declarations of one font each, composed out of three fields:
 2800       <enum>
 2801         <item> Font name. The name will appear in the font selector controls.
 2802                Also, backend devices that has built-in fonts, will be given the
 2803                name as a font identifier.
 2804         <item> Font fall-back. Grace will try to use this in case the real
 2805                font is not found.
 2806         <item> Font filename. The file with the font outline data.
 2807       </enum>
 2808     <p>
 2809       Here is the default <tt>FontDataBase</tt> file:
 2810       <tscreen><code>
 2811 14
 2812 Times-Roman             Times-Roman             n021003l.pfb
 2813 Times-Italic            Times-Italic            n021023l.pfb
 2814 Times-Bold              Times-Bold              n021004l.pfb
 2815 Times-BoldItalic        Times-BoldItalic        n021024l.pfb
 2816 Helvetica               Helvetica               n019003l.pfb
 2817 Helvetica-Oblique       Helvetica-Oblique       n019023l.pfb
 2818 Helvetica-Bold          Helvetica-Bold          n019004l.pfb
 2819 Helvetica-BoldOblique   Helvetica-BoldOblique   n019024l.pfb
 2820 Courier                 Courier                 n022003l.pfb
 2821 Courier-Oblique         Courier-Oblique         n022023l.pfb
 2822 Courier-Bold            Courier-Bold            n022004l.pfb
 2823 Courier-BoldOblique     Courier-BoldOblique     n022024l.pfb
 2824 Symbol                  Symbol                  s050000l.pfb
 2825 ZapfDingbats            ZapfDingbats            d050000l.pfb
 2826       </code></tscreen>
 2827     <p>
 2828 
 2829     <sect2>Font data files
 2830     <p>
 2831       For text rastering, three types of files are used.
 2832       <enum>
 2833         <item> <tt>.pfa</tt>-/<tt>.pfb</tt>-files: These contain the character
 2834                outline descriptions. The files are assumed to be in the
 2835                <tt>fonts/type1</tt> directory; these are the filenames
 2836                specified in the <tt>FontDataBase</tt> configuration file.
 2837         <item> <tt>.afm</tt>-files: These contain high-precision font metric
 2838                descriptions as well as some extra information, such as kerning
 2839                and ligature information for a particular font. It is assumed
 2840                that the filename of a font metric file has same basename as the
 2841                respective font outline file, but with the <tt>.afm</tt>
 2842                extension; the metric files are expected to be found in the
 2843                <tt>fonts/type1</tt> directory, too.
 2844         <item> <tt>.enc</tt>-files: These contain encoding arrays in a special
 2845                but simple form. They are only needed if someone wants to load
 2846                a special encoding to re-encode a font. Their place is
 2847                <tt>fonts/enc</tt>
 2848       </enum>
 2849       
 2850     <sect2>Custom fonts
 2851       <p>
 2852       It is possible to use custom fonts with Grace. One mostly needs to use
 2853       extra fonts for the purpose of localization. For many European
 2854       languages, the standard fonts supplied with Grace should contain all the
 2855       characters needed, but encoding may have to be adjusted. This is done by
 2856       putting a <tt>Default.enc</tt> file with proper encoding scheme into the
 2857       <tt>fonts/enc</tt> directory. Grace comes with a few encoding files in
 2858       the directory; more can be easily found on the Internet. (If the
 2859       <tt>Default.enc</tt> file doesn't exist, the IsoLatin1 encoding will be
 2860       used). Notice that for fonts having an encoding scheme in themselves
 2861       (such as the Symbol font, and many nationalized fonts) the default
 2862       encoding is ignored.
 2863       <p>
 2864       If you do need to use extra fonts, you should modify the
 2865       <tt>FontDataBase</tt> file accordingly, obeying its format. However,
 2866       if you are going to exchange Grace project files with other people who
 2867       do not have the extra fonts configured, an important thing is to define
 2868       reasonable fall-back font names.
 2869       <p>
 2870       For example, let us assume I use Hebrew fonts, and the configuration file
 2871       has lines like these:
 2872       <tscreen><code>
 2873     ...
 2874 Courier-Hebrew              Courier                 courh___.pfa
 2875 Courier-Hebrew-Oblique      Courier-Oblique         courho__.pfa
 2876     ...
 2877       </code></tscreen>
 2878       My colleague, who lives in Russia, uses Cyrillic fonts with Grace
 2879       configured like this:
 2880       <tscreen><code>
 2881     ...
 2882 Cronix-Courier              Courier                 croxc.pfb
 2883 Cronix-Courier-Oblique      Courier-Oblique         croxco.pfb
 2884     ...
 2885       </code></tscreen>
 2886       The font mapping information (Font name &lt;-&gt; Font fall-back) is
 2887       stored in the Grace project files. Provided that all the localized fonts
 2888       have English characters in the lower part of the ASCII table unmodified,
 2889       I can send my friend files (with no Hebrew characters, of course) and be
 2890       sure they render correctly on his computer.
 2891       <p>
 2892       Thus, with properly configured national fonts, you can make localized
 2893       annotations for plots intended for internal use of your institution,
 2894       while being able to exchange files with colleagues from abroad. People
 2895       who ever tried to do this with MS Office applications should appreciate
 2896       the flexibility :-).
 2897 
 2898   <sect1>Interaction with other applications
 2899     <p>
 2900 
 2901     <sect2>Using pipes
 2902       <p>
 2903 
 2904     <sect2>Using grace&lowbar;np library
 2905       <p>
 2906       The grace&lowbar;np library is a set of compiled functions that
 2907       allows you to launch and drive a Grace subprocess from your C or
 2908       Fortran application. Functions are provided to start the
 2909       subprocess, to send it commands or data, to stop it or detach
 2910       from it.
 2911 
 2912       <table loc="htbp">
 2913       <tabular ca="p{4.5cm}lp{5.5cm}">
 2914         <hline>
 2915         Function           | Arguments          |  Description                 @
 2916         <hline>
 2917         int GraceOpenVA    | (char *<it>exe</it>, int <it>buf&lowbar;size</it>, ...)
 2918                                                 | launch a Grace executable <it>exe</it> and open a communication channel with it using <it>buf&lowbar;size</it> bytes for data buffering. The remaining NULL-terminated list of options is command line arguments passed to the Grace process @
 2919         int GraceOpen      | (int <it>buf&lowbar;size</it>)
 2920                                                 | equivalent to GraceOpenVA("xmgrace", buf&lowbar;size, "-nosafe", "-noask", NULL) @
 2921         int GraceIsOpen    | (void)             | test if a Grace subprocess is currently connected @
 2922         int GraceClose     | (void)             | close the communication channel and exit the Grace subprocess @
 2923         int GraceClosePipe | (void)             | close the communication channel and leave the Grace subprocess alone @
 2924         <hline>
 2925         int GraceFlush     | (void)             | flush all the data remaining in the buffer @
 2926         int GracePrintf    | (const char* <it>format</it>, ...)
 2927                                                 | format a command and send it to the Grace subprocess @
 2928         int GraceCommand   | (const char* <it>cmd</it>)
 2929                                                 | send an already formated command to the Grace subprocess @
 2930         <hline>
 2931         GraceErrorFunctionType GraceRegisterErrorFunction
 2932                            | (GraceErrorFunctionType <it>f</it>)
 2933                                                 | register a user function <it>f</it> to display library errors @
 2934         <hline>
 2935       </tabular>
 2936       <caption>
 2937         <label id="C functions"> grace&lowbar;np library C functions.
 2938       </caption>
 2939       </table>
 2940 
 2941       <table loc="htbp">
 2942       <tabular ca="p{5cm}lp{5cm}">
 2943         <hline>
 2944         Function                | Arguments     |  Description                 @
 2945         <hline>
 2946         integer GraceOpenF      | (integer <it>buf&lowbar;size</it>)
 2947                                                 | launch a Grace subprocess and open a communication channel with it @
 2948         integer GraceIsOpenF    | (void)        | test if a Grace subprocess is currently connected @
 2949         integer GraceCloseF     | (void)        | close the communication channel and exit the Grace subprocess @
 2950         integer GraceClosePipeF | (void)        | close the communication channel and leave the Grace subprocess alone @
 2951         <hline>
 2952         integer GraceFlushF     | (void)        | flush all the data remaining in the buffer @
 2953         integer GraceCommandF   | (character*(*) <it>cmd</it>)
 2954                                                 | send an already formatted command to the Grace subprocess @
 2955         <hline>
 2956         GraceFortranFunctionType GraceRegisterErrorFunctionF
 2957                                 | (GraceFortranFunctionType <it>f</it>)
 2958                                                 | register a user function <it>f</it> to display library errors @
 2959         <hline>
 2960       </tabular>
 2961       <caption>
 2962         <label id="fortran functions"> grace&lowbar;np library F77 functions.
 2963       </caption>
 2964       </table>
 2965 
 2966       <p> There is no Fortran equivalent for the GracePrintf function,
 2967       you should format all the data and commands yourself before
 2968       sending them with GraceCommandF.
 2969 
 2970       The Grace subprocess listens for the commands you send and
 2971       interprets them as if they were given in a batch file. You can
 2972       send any command you like (redraw, autoscale, ...). If you want
 2973       to send data, you should include them in a command like "g0.s0
 2974       point 3.5, 4.2".
 2975 
 2976       Apart from the fact it monitors the data sent via an anonymous
 2977       pipe, the Grace subprocess is a normal process. You can interact
 2978       with it through the GUI. Note that no error can be sent back to
 2979       the parent process. If your application send erroneous commands,
 2980       an error popup will be displayed by the subprocess.
 2981 
 2982       If you exit the subprocess while the parent process is still
 2983       using it, the broken pipe will be detected. An error code will
 2984       be returned to every further call to the library (but you can
 2985       still start a new process if you want to manage this situation).
 2986 
 2987       Here is an example use of the library, you will find this
 2988       program in the distribution.
 2989 
 2990 <tscreen><code>
 2991 #include <stdlib.h>
 2992 #include <stdio.h>
 2993 #include <unistd.h>
 2994 #include <grace_np.h>
 2995 
 2996 #ifndef EXIT_SUCCESS
 2997 #  define EXIT_SUCCESS 0
 2998 #endif
 2999 
 3000 #ifndef EXIT_FAILURE
 3001 #  define EXIT_FAILURE -1
 3002 #endif
 3003 
 3004 void my_error_function(const char *msg)
 3005 {
 3006     fprintf(stderr, "library message: \"%s\"\n", msg);
 3007 }
 3008 
 3009 int
 3010 main(int argc, char* argv[])
 3011 {
 3012     int i;
 3013 
 3014     GraceRegisterErrorFunction(my_error_function);
 3015 
 3016     /* Start Grace with a buffer size of 2048 and open the pipe */
 3017     if (GraceOpen(2048) == -1) {
 3018         fprintf(stderr, "Can't run Grace. \n");
 3019         exit(EXIT_FAILURE);
 3020     }
 3021     
 3022     /* Send some initialization commands to Grace */
 3023     GracePrintf("world xmax 100");
 3024     GracePrintf("world ymax 10000");
 3025     GracePrintf("xaxis tick major 20");
 3026     GracePrintf("xaxis tick minor 10");
 3027     GracePrintf("yaxis tick major 2000");
 3028     GracePrintf("yaxis tick minor 1000");
 3029     GracePrintf("s0 on");
 3030     GracePrintf("s0 symbol 1");
 3031     GracePrintf("s0 symbol size 0.3");
 3032     GracePrintf("s0 symbol fill pattern 1");
 3033     GracePrintf("s1 on");
 3034     GracePrintf("s1 symbol 1");
 3035     GracePrintf("s1 symbol size 0.3");
 3036     GracePrintf("s1 symbol fill pattern 1");
 3037 
 3038     /* Display sample data */
 3039     for (i = 1; i <= 100 && GraceIsOpen(); i++) {
 3040         GracePrintf("g0.s0 point %d, %d", i, i);
 3041         GracePrintf("g0.s1 point %d, %d", i, i * i);
 3042         /* Update the Grace display after every ten steps */
 3043         if (i % 10 == 0) {
 3044             GracePrintf("redraw");
 3045             /* Wait a second, just to simulate some time needed for
 3046                calculations. Your real application shouldn't wait. */
 3047             sleep(1);
 3048         }
 3049     }
 3050 
 3051     if (GraceIsOpen()) {
 3052         /* Tell Grace to save the data */
 3053         GracePrintf("saveall \"sample.agr\"");
 3054 
 3055         /* Flush the output buffer and close Grace */
 3056         GraceClose();
 3057 
 3058         /* We are done */
 3059         exit(EXIT_SUCCESS);
 3060     } else {
 3061         exit(EXIT_FAILURE);
 3062     }
 3063 }
 3064 
 3065 </code></tscreen>
 3066     <p>
 3067       To compile this program, type
 3068       <tscreen><code>
 3069         cc example.c -lgrace_np
 3070       </code></tscreen>
 3071       If Grace wasn't properly installed, you may need to instruct the
 3072       compiler about include and library paths explicitly, e.g.
 3073       <tscreen><code>
 3074         cc -I/usr/local/grace/include example.c -L/usr/local/grace/lib -lgrace_np
 3075       </code></tscreen>
 3076 
 3077  <sect1>FFTW tuning<label id="fftw-tuning">
 3078     <p>
 3079      When the FFTW capabilities are compiled in, Grace looks at two environment
 3080      variables to decide what to do with the FFTW 'wisdom' capabilities. 
 3081      First, a quick summary of what this is. The FFTW package is capable of
 3082      adaptively determining the most efficient factorization of a set to give
 3083      the fastest computation.  It can store these factorizations as 'wisdom',
 3084      so that if a transform of a given size is to be repeated, it is does not
 3085      have to re-adapt.  The good news is that this seems to work very well. 
 3086      The bad news is that, the first time a transform of a given size is
 3087      computed, if it is not a sub-multiple of one already known, it takes a LONG
 3088      time (seconds to minutes).
 3089     <p>
 3090      The first environment variable is GRACE_FFTW_WISDOM_FILE. If this is set
 3091      to the name of a file which can be read and written (e.g.,
 3092      $HOME/.grace_fftw_wisdom) then Grace will automatically create this file
 3093      (if needed) and maintain it. If the file is read-only, it will be read,
 3094      but not updated with new wisdom. If the symbol GRACE_FFTW_WISDOM_FILE
 3095      either doesn't exist, or evaluates to an empty string, Grace will drop the
 3096      use of wisdom, and will use the fftw estimator (FFTW_ESTIMATE flag sent to
 3097      the planner) to guess a good factorization, instead of adaptively
 3098      determining it.
 3099     <p>
 3100      The second variable is GRACE_FFTW_RAM_WISDOM. If this variable is defined
 3101      to be non-zero, and GRACE_FFTW_WISDOM_FILE variable is not defined (or is
 3102      an empty string), Grace will use wisdom internally, but maintain no
 3103      persistent cache of it. This will result in very slow execution times the
 3104      first time a transform is executed after Grace is started, but very fast
 3105      repeats. I am not sure why anyone would want to use wisdom without
 3106      writing it to disk, but if you do, you can use this flag to enable it.
 3107     <p>
 3108 
 3109   <sect1>DL modules <label id="dl-modules">
 3110     <p>
 3111     Grace can access external functions present
 3112     in either system or third-party shared libraries or modules
 3113     specially compiled for use with Grace.
 3114 
 3115     <sect2>Function types
 3116     <p>
 3117     One must make sure, however, that the external function is of one
 3118     of supported by Grace types:
 3119       <table loc="htbp">
 3120       <tabular ca="ll">
 3121               <hline>
 3122       Grace type | Description   @
 3123               <hline>
 3124 f&lowbar;of&lowbar;i      | a function of 1 <tt/int/ variable                                 @
 3125 f&lowbar;of&lowbar;d      | a function of 1 <tt/double/ variable                              @
 3126 f&lowbar;of&lowbar;nn     | a function of 2 <tt/int/ parameters                               @
 3127 f&lowbar;of&lowbar;nd     | a function of 1 <tt/int/ parameter and 1 <tt/double/ variable     @
 3128 f&lowbar;of&lowbar;dd     | a function of 2 <tt/double/ variables                             @
 3129 f&lowbar;of&lowbar;nnd    | a function of 2 <tt/int/ parameters and 1 <tt/double/ variable    @
 3130 f&lowbar;of&lowbar;ppd    | a function of 2 <tt/double/ parameters and 1 <tt/double/ variable @
 3131 f&lowbar;of&lowbar;pppd   | a function of 3 <tt/double/ parameters and 1 <tt/double/ variable @
 3132 f&lowbar;of&lowbar;ppppd  | a function of 4 <tt/double/ parameters and 1 <tt/double/ variable @
 3133 f&lowbar;of&lowbar;pppppd | a function of 5 <tt/double/ parameters and 1 <tt/double/ variable @
 3134               <hline>
 3135       </tabular>
 3136       <caption>
 3137               <label id="grace-types">
 3138               Grace types for external functions
 3139       </caption>
 3140       </table>
 3141 
 3142       The return values of functions are assumed to be of the
 3143       <tt/double/ type.
 3144 
 3145        Note, that there is no difference from the point of view of
 3146        function prototype between parameters and variables; the
 3147        difference is in the way Grace treats them - an attempt to use
 3148        a vector expression as a parameter argument will result in a
 3149        parse error.
 3150 
 3151        Let us consider few examples.
 3152 
 3153        <sect2>Examples
 3154        <p>
 3155        Caution: the examples provided below (paths and compiler flags)
 3156        are valid for Linux/ELF with gcc. On other operating systems,
 3157        you may need to refer to compiler/linker manuals or ask a guru.
 3158 
 3159        <sect3>Example 1
 3160        <p>
 3161        Suppose I want to use function <tt/pow(x,y)/ from the Un*x math
 3162        library (libm). Of course, you can use the "^" operator defined
 3163        in the Grace language, but here, for the sake of example, we
 3164        want to access the function directly.
 3165 
 3166        The command to make it accessible by Grace is
 3167        <tscreen>
 3168        USE "pow" TYPE f_of_dd FROM "/usr/lib/libm.so"
 3169        </tscreen>
 3170 
 3171        Try to plot y = pow(x,2) and y = x^2 graphs (using, for
 3172        example, "create new -&gt; Formula" from any <ref name="set
 3173        selector" id="set-selector">) and compare.
 3174 
 3175        <sect3>Example 2
 3176        <p>
 3177        Now, let us try to write a function ourselves. We will define
 3178        function <tt/my_function/ which simply returns its (second)
 3179        argument multiplied by integer parameter transferred as the
 3180        first argument.
 3181 
 3182        In a text editor, type in the following C code and save it as
 3183        "my_func.c":
 3184 
 3185        <tscreen><code>
 3186        double my_function (int n, double x)
 3187        {
 3188            double retval;
 3189            retval = (double) n * x;
 3190            return (retval);
 3191        }
 3192        </code></tscreen>
 3193 
 3194        OK, now compile it:
 3195 
 3196        <tscreen><code>
 3197        $gcc -c -fPIC my_func.c
 3198        $gcc -shared my_func.o -o /tmp/my_func.so
 3199        </code></tscreen>
 3200 
 3201        (You may strip it to save some disk space):
 3202 
 3203        <tscreen><code>
 3204        $strip /tmp/my_func.so
 3205        </code></tscreen>
 3206 
 3207        That's all! Ready to make it visible to Grace as "myf" - we are
 3208        too lazy to type the very long string "my_function" many times.
 3209 
 3210        <tscreen>
 3211        USE "my_function" TYPE f_of_nd FROM "/tmp/my_func.so" ALIAS "myf"
 3212        </tscreen>
 3213 
 3214 
 3215        <sect3>Example 3
 3216        <p>
 3217        A more serious example. There is a special third-party library
 3218        available on your system which includes a very important for
 3219        you yet very difficult-to-program from the scratch function
 3220        that you want to use with Grace.  But, the function prototype
 3221        is NOT one of any predefined <ref name="types"
 3222        id="grace-types">.  The solution is to write a simple function
 3223        wrapper. Here is how:
 3224 
 3225        Suppose, the name of the library is "special_lib" and the
 3226        function you are interested in is called "special_func" and
 3227        according to the library manual, should be accessed as <tt/void
 3228        special_func(double *input, double *output, int parameter)/.
 3229        The wrapper would look like this:
 3230 
 3231        <tscreen><code>
 3232        double my_wrapper(int n, double x)
 3233        {
 3234            extern void special_func(double *x, double *y, int n);
 3235            double retval;
 3236            (void) special_func(&amp;x, &amp;retval, n);
 3237            return (retval);
 3238        }
 3239        </code></tscreen>
 3240 
 3241        Compile it:
 3242 
 3243        <tscreen><code>
 3244        $gcc -c -fPIC my_wrap.c
 3245        $gcc -shared my_wrap.o -o /tmp/my_wrap.so -lspecial_lib -lblas
 3246        $strip /tmp/my_wrap.so
 3247        </code></tscreen>
 3248 
 3249        Note that I added <tt/-lblas/ assuming that the special_lib
 3250        library uses some functions from the BLAS. Generally, you have
 3251        to add <it>all</it> libraries which your module depends on (and
 3252        all libraries those libraries rely upon etc.), as if you wanted
 3253        to compile a plain executable.
 3254 
 3255        Fine, make Grace aware of the new function
 3256 
 3257        <tscreen>
 3258        USE "my_wrapper" TYPE f_of_nd FROM "/tmp/my_wrap.so" ALIAS "special_func"
 3259        </tscreen>
 3260 
 3261        so we can use it with its original name.
 3262 
 3263        <sect3>Example 4
 3264        <p>
 3265        An example of using Fortran modules.
 3266 
 3267        Here we will try to achieve the same functionality as in
 3268        Example 2, but with the help of F77.
 3269 
 3270        <tscreen><code>
 3271        DOUBLE PRECISION FUNCTION MYFUNC (N, X)
 3272        IMPLICIT NONE
 3273        INTEGER N
 3274        DOUBLE PRECISION X
 3275 C
 3276        MYFUNC = N * X
 3277 C
 3278        RETURN
 3279        END
 3280        </code></tscreen>
 3281 
 3282        As opposite to C, there is no way to call such a function from
 3283        Grace directly - the problem is that in Fortran all arguments
 3284        to a function (or subroutine) are passed by reference. So, we
 3285        need a wrapper:
 3286 
 3287        <tscreen><code>
 3288        double myfunc_wrapper(int n, double x)
 3289        {
 3290            extern double myfunc_(int *, double *);
 3291            double retval;
 3292            retval = myfunc_(&amp;n, &amp;x);
 3293            return (retval);
 3294        }
 3295        </code></tscreen>
 3296 
 3297        Note that most of f77 compilers by default add underscore to
 3298        the function names and convert all names to the lower case,
 3299        hence I refer to the Fortran function <tt/MYFUNC/ from my C
 3300        wrapper as <tt/myfunc_/, but in your case it can be different!
 3301 
 3302        Let us compile the whole stuff:
 3303 
 3304        <tscreen><code>
 3305        $g77 -c -fPIC myfunc.f
 3306        $gcc -c -fPIC myfunc_wrap.c
 3307        $gcc -shared myfunc.o myfunc_wrap.o -o /tmp/myfunc.so -lf2c -lm
 3308        $strip /tmp/myfunc.so
 3309        </code></tscreen>
 3310 
 3311        And finally, inform Grace about this new function:
 3312 
 3313        <tscreen>
 3314        USE "myfunc_wrapper" TYPE f_of_nd FROM "/tmp/myfunc.so" ALIAS "myfunc"
 3315        </tscreen>
 3316 
 3317        <sect2>Operating system issues
 3318          <p>
 3319          <sect3>OS/2
 3320           <p>
 3321          In general the method outlined in the examples above can be
 3322      used on OS/2, too. However you have to create a DLL (Dynamic Link Library)
 3323      which is a bit more tricky on OS/2 than on most Un*x systems.
 3324          Since Grace was ported by using EMX we also use it to create
 3325      the examples; however other development environments should work
 3326      as well (ensure to use the _System calling convention!).
 3327          We refer to Example 2 only. Example 1 might demonstrate
 3328      that DLLs can have their entry points (i.e. exported functions)
 3329          callable via ordinals only, so you might not know how to access a
 3330          specific function without some research.
 3331          First compile the source from Example 2 to "my_func.obj"
 3332 
 3333          <tscreen>
 3334          gcc -Zomf -Zmt -c my_func.c -o my_func.obj
 3335          </tscreen>
 3336 
 3337          Then you need to create a linker definition file "my_func.def"
 3338      which contains some basic info about the DLL and declares
 3339      the exported functions.
 3340 
 3341          <tscreen><code>
 3342          LIBRARY my_func INITINSTANCE TERMINSTANCE
 3343          CODE LOADONCALL
 3344          DATA LOADONCALL MULTIPLE NONSHARED
 3345          DESCRIPTION 'This is a test DLL: my_func.dll'
 3346          EXPORTS
 3347          my_function
 3348          </code></tscreen>
 3349 
 3350          (don't forget about the 8 characters limit on the DLL name!).
 3351          Finally link the DLL:
 3352 
 3353          <tscreen>
 3354          gcc my_func.obj my_func.def -o my_func.dll -Zdll -Zno-rte -Zmt -Zomf
 3355          </tscreen>
 3356 
 3357          (check out the EMX documentation about the compiler/linker flags
 3358       used here!)
 3359          To use this new library function within Grace you may either
 3360      put the DLL in the LIBPATH and use the short form:
 3361 
 3362          <tscreen>
 3363          USE "my_function" TYPE f_of_nd FROM "my_func" ALIAS "myf"
 3364          </tscreen>
 3365 
 3366          or put it in an arbitrary path which you need to specify explicitly
 3367          then:
 3368 
 3369          <tscreen>
 3370          USE "my_function" TYPE f_of_nd FROM "e:/foo/my_func.dll" ALIAS "myf"
 3371          </tscreen>
 3372      
 3373      (as for most system-APIs you may use the Un*x-like forward
 3374      slashs within the path!)
 3375 
 3376 <!-- ****** Appendices/references ************ -->
 3377 <sect> References
 3378   <p>
 3379   
 3380   <sect1>Typesetting<label id="typesetting">
 3381     <p>
 3382       Grace permits quite complex typesetting on a per string basis.
 3383       Any string displayed (titles, legends, tick marks,...) may contain
 3384       special control codes to display subscripts, change fonts within the
 3385       string etc.
 3386        <p>
 3387 
 3388       <table loc="htbp">
 3389       <tabular ca="ll">
 3390               <hline>
 3391               Control code | Description   @
 3392               <hline>
 3393               &bsol;f{x}   | switch to font named "x"   @
 3394               &bsol;f{n}   | switch to font number n    @
 3395               &bsol;f{}    | return to original font    @
 3396               &bsol;R{x}   | switch to color named "x"  @
 3397               &bsol;R{n}   | switch to color number n   @
 3398               &bsol;R{}    | return to original color   @
 3399               &bsol;#{x}   | treat "x" (must be of even length) as list of hexadecimal char codes @
 3400               &bsol;t{xx xy yx yy} | apply transformation matrix   @
 3401               &bsol;t{}    | reset transformation matrix   @
 3402               &bsol;z{x}   | zoom x times   @
 3403               &bsol;z{}    | return to original zoom   @
 3404               &bsol;r{x}   | rotate by x degrees   @
 3405               &bsol;l{x}   | slant by factor x   @
 3406               &bsol;v{x}   | shift vertically by x   @
 3407               &bsol;v{}    | return to unshifted baseline   @
 3408               &bsol;V{x}   | shift baseline by x   @
 3409               &bsol;V{}    | reset baseline   @
 3410               &bsol;h{x}   | horizontal shift by x   @
 3411               &bsol;n      | new line   @
 3412               &bsol;u      | begin underline   @
 3413               &bsol;U      | stop underline   @
 3414               &bsol;o      | begin overline   @
 3415               &bsol;O      | stop overline   @
 3416               &bsol;Fk     | enable kerning   @
 3417               &bsol;FK     | disable kerning   @
 3418               &bsol;Fl     | enable ligatures   @
 3419               &bsol;FL     | disable ligatures   @
 3420               &bsol;m{n}   | mark current position as n   @
 3421               &bsol;M{n}   | return to saved position n   @
 3422               &bsol;dl     | LtoR substring direction   @
 3423               &bsol;dr     | RtoL substring direction   @
 3424               &bsol;dL     | LtoR text advancing   @
 3425               &bsol;dR     | RtoL text advancing   @
 3426               <hline>
 3427               &bsol;x      | switch to Symbol font (same as &bsol;f{Symbol})   @
 3428               &bsol;+      | increase size (same as &bsol;z{1.19} ; 1.19 = sqrt(sqrt(2)))   @
 3429               &bsol;-      | decrease size (same as &bsol;z{0.84} ; 0.84 = 1/sqrt(sqrt(2)))   @
 3430               &bsol;s      | begin subscripting (same as &bsol;v{-0.4}&bsol;z{0.71})   @
 3431               &bsol;S      | begin superscripting (same as &bsol;v{0.6}&bsol;z{0.71})   @
 3432               &bsol;T{xx xy yx yy} | same as &bsol;t{}&bsol;t{xx xy yx yy}   @
 3433               &bsol;Z{x}   | absolute zoom x times (same as &bsol;z{}&bsol;z{x})  @
 3434               &bsol;q      | make font oblique (same as &bsol;l{0.25})   @
 3435               &bsol;Q      | undo oblique (same as &bsol;l{-0.25})   @
 3436               &bsol;N      | return to normal style (same as &bsol;v{}&bsol;t{})   @
 3437               <hline>
 3438               &bsol;&bsol; | print &bsol;   @
 3439               <hline>
 3440               &bsol;n      | switch to font number n (0-9) (deprecated) @
 3441               &bsol;c      | begin using upper 128 characters of set (deprecated)  @
 3442               &bsol;C      | stop using upper 128 characters of set (deprecated)  @
 3443               <hline>
 3444       </tabular>
 3445       <caption>
 3446               <label id="control-codes">
 3447               Control codes.
 3448       </caption>
 3449       </table>
 3450 
 3451       <p>
 3452        Example:
 3453       <p>
 3454        F&bsol;sX&bsol;N(&bsol;xe&bsol;f{}) =
 3455        sin(&bsol;xe&bsol;f{})&bsol;#{b7}e&bsol;S-X&bsol;N&bsol;#{b7}cos(&bsol;xe&bsol;f{}) 
 3456       <p>
 3457        prints roughly
 3458        <tscreen><verb>
 3459                        -x
 3460        F (e) = sin(e)&middot;e  &middot;cos(e)
 3461         x
 3462        </verb></tscreen>
 3463       <p>
 3464        using string's initial font and e prints as epsilon from the Symbol font.
 3465       <p>
 3466        NOTE:
 3467        Characters from the upper half of the char table can be entered directly
 3468        from the keyboard, using appropriate <tt>xmodmap(1)</tt> settings, or
 3469        with the help of the font tool ("Window/Font tool").
 3470       <p>
 3471 
 3472   <sect1>Device-specific limitations<label id="device-limitations">
 3473     <p>
 3474       
 3475       Grace can output plots using several device backends. The list of
 3476       available devices can be seen (among other stuff) by specifying the
 3477       "-version" command line switch.
 3478       <itemize>
 3479         <item> X11, PostScript and EPS are full-featured devices
 3480         <item> Raster drivers (PNM/JPEG/PNG):
 3481                <itemize>
 3482                  <item> only even-odd fill rule is supported
 3483                  <item> patterned lines are not implemented
 3484                </itemize>
 3485         <item> PDF driver:
 3486                <itemize>
 3487                  <item> bitmapped text strings are not transparent
 3488                </itemize>
 3489         <item> MIF driver:
 3490                <itemize>
 3491                  <item> some of patterned fills not implemented
 3492                  <item> bitmapped text strings not implemented
 3493                </itemize>
 3494         <item> SVG driver:
 3495                <itemize>
 3496                  <item> bitmapped text strings not implemented
 3497                </itemize>
 3498       </itemize>
 3499       
 3500       <p>
 3501 
 3502   <sect1>Device-specific settings<label id="device-settings">
 3503     <p>
 3504       
 3505       Some of the output devices accept several configuration options. You can
 3506       set the options by passing a respective string to the interpreter
 3507       using the "DEVICE <it>"devname"</it> OP <it>"options"</it>" command (see
 3508       <ref id="device-parameters" name="Device parameters">). A few options
 3509       can be passed in one command, separated by commas.
 3510 
 3511     <p>
 3512       
 3513       <table loc="htbp">
 3514       <tabular ca="ll">
 3515               <hline>
 3516               Command           | Description                               @
 3517               <hline>
 3518               grayscale         | set grayscale output                      @
 3519               color             | set color output                          @
 3520               level1            | use only PS Level 1 subset of commands    @
 3521               level2            | use also PS Level 2 commands if needed    @
 3522               docdata:7bit      | the document data is 7bit clean           @
 3523               docdata:8bit      | the document data is 8bit clean           @
 3524               docdata:binary    | the document data may be binary           @
 3525               xoffset:<it>x</it> | set page offset in X direction <it>x</it> pp  @
 3526               yoffset:<it>y</it> | set page offset in Y direction <it>y</it> pp  @
 3527               mediafeed:auto    | default input tray                        @
 3528               mediafeed:match   | select input with media matching page dimensions @
 3529               mediafeed:manual  | manual media feed                         @
 3530               hwresolution:on   | set hardware resolution                   @
 3531               hwresolution:off  | do not set hardware resolution            @
 3532               <hline>
 3533       </tabular>
 3534       <caption>
 3535               PostScript driver options
 3536       </caption>
 3537       </table>
 3538 
 3539     <p>
 3540       
 3541       <table loc="htbp">
 3542       <tabular ca="ll">
 3543               <hline>
 3544               Command       | Description                                   @
 3545               <hline>
 3546               grayscale     | set grayscale output                          @
 3547               color         | set color output                              @
 3548               level1        | use only PS Level 1 subset of commands        @
 3549               level2        | use also PS Level 2 commands if needed        @
 3550               bbox:tight    | enable "tight" bounding box                   @
 3551               bbox:page     | bounding box coincides with page dimensions   @
 3552               <hline>
 3553       </tabular>
 3554       <caption>
 3555               EPS driver options
 3556       </caption>
 3557       </table>
 3558 
 3559     <p>
 3560 
 3561       <table loc="htbp">
 3562       <tabular ca="ll">
 3563               <hline>
 3564               Command           | Description                        @
 3565               <hline>
 3566               PDF1.3            | set compatibility mode to PDF-1.3  @
 3567               PDF1.4            | set compatibility mode to PDF-1.4  @
 3568               compression:value | set compression level (0 - 9)      @
 3569               patterns:on       | enable use of patterns             @
 3570               patterns:off      | disable use of patterns            @
 3571               <hline>
 3572       </tabular>
 3573       <caption>
 3574               PDF driver options
 3575       </caption>
 3576       </table>
 3577 
 3578     <p>
 3579 
 3580       <table loc="htbp">
 3581       <tabular ca="ll">
 3582               <hline>
 3583               Command           | Description               @
 3584               <hline>
 3585               format:pbm        | output in PBM format      @
 3586               format:pgm        | output in PGM format      @
 3587               format:ppm        | output in PPM format      @          
 3588               rawbits:on        | "rawbits" (binary) output @          
 3589               rawbits:off       | ASCII output              @          
 3590               <hline>
 3591       </tabular>
 3592       <caption>
 3593               PNM driver options
 3594       </caption>
 3595       </table>
 3596 
 3597     <p>
 3598 
 3599       <table loc="htbp">
 3600       <tabular ca="ll">
 3601               <hline>
 3602               Command               | Description                           @
 3603               <hline>
 3604               grayscale             | set grayscale output                  @
 3605               color                 | set color output                      @
 3606               optimize:on/off       | enable/disable optimization           @
 3607               quality:value         | set compression quality (0 - 100)     @
 3608               smoothing:value       | set smoothing (0 - 100)               @
 3609               baseline:on/off       | do/don't force baseline output        @
 3610               progressive:on/off    | do/don't output in progressive format @
 3611               dct:ifast             | use fast integer DCT method           @
 3612               dct:islow             | use slow integer DCT method           @
 3613               dct:float             | use floating-point DCT method         @
 3614               <hline>
 3615       </tabular>
 3616       <caption>
 3617               JPEG driver options
 3618       </caption>
 3619       </table>
 3620 
 3621     <p>
 3622 
 3623       <table loc="htbp">
 3624       <tabular ca="ll">
 3625               <hline>
 3626               Command           | Description                       @
 3627               <hline>
 3628               interlaced:on     | make interlaced image             @
 3629               interlaced:off    | don't make interlaced image       @
 3630               transparent:on    | produce transparent image         @
 3631               transparent:off   | don't produce transparent image   @
 3632               compression:value | set compression level (0 - 9)     @
 3633               <hline>
 3634       </tabular>
 3635       <caption>
 3636               PNG driver options
 3637       </caption>
 3638       </table>
 3639 
 3640     <p>
 3641 
 3642 
 3643     <sect1>Dates in Grace <label id="dates">
 3644     
 3645     <p>
 3646       We use two calendars in Grace: the one that was established in
 3647       532 by Denys and lasted until 1582, and the one that was created
 3648       by Luigi Lilio (Alyosius Lilius) and Christoph Klau
 3649       (Christophorus Clavius) for pope Gregorius XIII. Both use the
 3650       same months (they were introduced under emperor Augustus, a few
 3651       years after Julian calendar introduction, both Julius and
 3652       Augustus were honored by a month being named after each one).
 3653       
 3654       The leap years occurred regularly in Denys's calendar: once
 3655       every four years, there is no year 0 in this calendar (the leap
 3656       year -1 was just before year 1). This calendar was not compliant
 3657       with earth motion and the dates were slowly shifting with regard
 3658       to astronomical events.
 3659       
 3660       This was corrected in 1582 by introducing Gregorian
 3661       calendar. First a ten days shift was introduced to reset correct
 3662       dates (Thursday October the 4th was followed by Friday October
 3663       the 15th). The rules for leap years were also changed: three
 3664       leap years are removed every four centuries. These years are
 3665       those that are multiple of 100 but not multiple of 400: 1700,
 3666       1800, and 1900 were not leap years, but 1600 and 2000 were (will
 3667       be) leap years.
 3668       
 3669       We still use Gregorian calendar today, but we now have several
 3670       time scales for increased accuracy. The International Atomic
 3671       Time (TAI) is a linear scale: the best scale to use for
 3672       scientific reference. The Coordinated Universal Time (UTC, often
 3673       confused with Greenwich Mean Time) is a legal time that is
 3674       almost synchronized with earth motion. However, since the earth
 3675       is slightly slowing down, leap seconds are introduced from time
 3676       to time in UTC (about one second every 18 months). UTC is not a
 3677       continuous scale ! When a leap second is introduced by
 3678       International Earth Rotation Service, this is published in
 3679       advance and the legal time sequence is as follows: 23:59:59
 3680       followed one second later by 23:59:60 followed one second later
 3681       by 00:00:00. At the time of this writing (1999-01-05) the
 3682       difference between TAI and UTC was 32 seconds, and the last leap
 3683       second was introduced in 1998-12-31.
 3684       
 3685       These calendars allow to represent any date from the mist of the
 3686       past to the fog of the future, but they are not convenient for
 3687       computation. Another time scale is possible: counting only the
 3688       days from a reference. Such a time scale was introduced by
 3689       Joseph-Juste Scaliger (Josephus Justus Scaliger) in 1583. He
 3690       decided to use "-4713-01-01T12:00:00" as a reference date
 3691       because it was at the same time a Monday, first of January of a
 3692       leap year, there was an exact number of 19 years Meton cycle
 3693       between this date and year 1 (for Easter computation), and it
 3694       was at the beginning of a 15 years <it>Roman indiction</it>
 3695       cycle. The day number counted from this reference is
 3696       traditionally called <it>Julian day</it>, but it has really
 3697       nothing to do with the Julian calendar.
 3698 
 3699       Grace stores dates internally as reals numbers counted from a
 3700       reference date. The default reference date is the one chosen by
 3701       Scaliger, it is a classical reference for astronomical
 3702       events. It can modified for a single session using the <ref
 3703       name="Edit-&gt;Preferences" id="preferences"> popup of the GUI. If
 3704       you often work with a specific reference date you can set it for
 3705       every sessions with a REFERENCE DATE command in your
 3706       configuration file (see <ref name="Default template"
 3707       id="default-template">).
 3708       
 3709       The following date formats are supported (hour, minutes and
 3710       seconds are always optional):
 3711       
 3712       <enum>
 3713       <item>iso8601  : 1999-12-31T23:59:59.999
 3714       <item>european : 31/12/1999 23:59:59.999 or 31/12/99 23:59:59.999
 3715       <item>us       : 12/31/1999 23:59:59.999 or 12/31/99 23:59:59.999
 3716       <item>Julian   : 123456.789
 3717       </enum>
 3718       
 3719       One should be aware that Grace does not allow to put a space in
 3720       one data column as spaces are used to separate fields. You
 3721       should always use another separator (:/.- or better T) between
 3722       date and time in data files. The GUI, the batch language and the
 3723       command line flags do not have this limitation, you can use
 3724       spaces there without any problem. The T separator comes from the
 3725       ISO8601 standard. Grace support its use also in european and us
 3726       formats.
 3727 
 3728       You can also provide a hint about the format ("ISO8601",
 3729       "european", "us") using the -datehint command line flag or the
 3730       ref name="Edit->Preferences" id="preferences"> popup of the GUI.
 3731       The formats are tried in the following order: first the hint
 3732       given by the user, then iso, european and us (there is no
 3733       ambiguity between calendar formats and numerical formats and
 3734       therefore no order is specified for them). The separators
 3735       between various fields can be any characters in the set: " :/.-T"
 3736       (one or more spaces act as one separator, other characters can
 3737       not be repeated, the T separator is allowed only between date and time,
 3738       mainly for iso8601), so the string "1999-12 31:23/59" is allowed
 3739       (but not recommended).  The '-' character is used both as a
 3740       separator (it is traditionally used in iso8601 format) and as
 3741       the unary minus (for dates in the far past or for numerical
 3742       dates). By default years are left untouched, so 99 is a date far
 3743       away in the past. This behavior can be changed with the <ref
 3744       name="Edit->preferences" id="preferences"> popup, or with the
 3745       <tt>DATE WRAP on</tt> and <tt>DATE WRAP YEAR year</tt>
 3746       commands. Suppose for example that the wrap year is chosen as
 3747       1950, if the year is between 0 and 99 and is written with two or
 3748       less digits, it is mapped to the present era as follows:
 3749 
 3750        range [00 ; 49] is mapped to [2000 ; 2049]
 3751 
 3752        range [50 ; 99] is mapped to [1950 ; 1999]
 3753 
 3754       with a wrap year set to 1970, the mapping would have been:
 3755 
 3756        range [00 ; 69] is mapped to [2000 ; 2069]
 3757 
 3758        range [70 ; 99] is mapped to [1970 ; 1999]
 3759 
 3760       this is reasonably Y2K compliant and is consistent with current
 3761       use.  Specifying year 1 is still possible using more than two
 3762       digits as follows: "0001-03-04" is unambiguously March the 4th,
 3763       year 1. The inverse transform is applied for dates written by
 3764       Grace, for example as tick labels. Using two digits only for
 3765       years is not recommended, we introduce a <it>wrap year +
 3766       100</it> bug here so this feature should be removed at some
 3767       point in the future ...
 3768       
 3769       The date scanner can be used either for Denys's and Gregorian
 3770       calendars. Inexistent dates are detected, they include year 0,
 3771       dates between 1582-10-05 and 1582-10-14, February 29th of non
 3772       leap years, months below 1 or above 12, ...  the scanner does
 3773       not take into account leap seconds: you can think it works only
 3774       in International Atomic Time (TAI) and not in Coordinated
 3775       Unified Time (UTC). If you find yourself in a situation were you
 3776       need UTC, a very precise scale, and should take into account
 3777       leap seconds ... you should convert your data yourself (for
 3778       example using International Atomic Time). But if you bother with
 3779       that you probably already know what to do.
 3780 
 3781 
 3782     <sect1>Xmgr to Grace migration guide
 3783     
 3784     <p>
 3785       
 3786       This is a very brief guide describing problems and workarounds for
 3787       reading in project files saved with Xmgr. You should read the docs or
 3788       just play with Grace to test new features and controls.
 3789  
 3790       <enum>
 3791       <item> Grace must be explicitly told the version number of the software
 3792              used to create a file. You can manually put "@version VERSIONID"
 3793              string at the beginning of the file. The VERSIONID is built as
 3794              MAJOR_REV*10000 + MINOR_REV*100 + PATCHLEVEL; so 40101 corresponds
 3795              to xmgr-4.1.1. Projects saved with Xmgr-4.1.2 do NOT need the above,
 3796              since they already have the version string in them. If you have no
 3797              idea what version of Xmgr your file was created with, try some.
 3798              In most cases, 40102 would do the trick.
 3799  
 3800       <item> The above relates to the ASCII projects only. The old binary
 3801              projects (saved with xmgr-4.0.*) are not automatically converted
 3802              anymore. An input filter must be defined to make the conversion
 3803              work on-the-fly. Add the following line to ~/.gracerc or the
 3804              system-wide $GRACE_HOME/gracerc resource file: DEFINE IFILTER
 3805              "grconvert %s -" MAGIC "00000031" See docs for more info on the
 3806              I/O filters.
 3807  
 3808       <item> Documentation on the script language is severely lacking still.
 3809  
 3810       <item> Grace is WYSIWYG. Xmgr was not. Many changes required to achieve the
 3811              WYSIWYG'ness led to the situation when graphs with objects carefully
 3812              aligned under Xmgr may not look so under Grace. Grace tries its best
 3813              to compensate for the differences, but sometimes you may have to
 3814              adjust such graphs manually.
 3815  
 3816       <item> A lot of symbol types (all except *real* symbols) are removed.
 3817              "Location *" types can be replaced (with much higher comfort) by
 3818              A(nnotating)values. "Impulse *", "Histogram *" and "Stair steps *"
 3819              effects can be achieved using the connecting line parameters (Type,
 3820              Drop lines). "Dot" symbol is removed as well; use the filled circle
 3821              symbol of the zero size with no outline to get the same effect.
 3822  
 3823       <item> Default page layout switched from free (allowing to resize canvas
 3824              with mouse) to fixed. For the old behavior, put "PAGE LAYOUT FREE"
 3825              in the Grace resource file or use the "-free" command line switch.
 3826              <bf>The use of the "free" page layout is in general deprecated,
 3827              though.</bf>
 3828  
 3829       <item> System (shell) variables GR_* renamed to GRACE_*
 3830  
 3831       <item> Smith plots don't work now. They'll be put back soon.
 3832  
 3833       </enum>
 3834     
 3835 
 3836 </article>
 3837 
 3838 <!-- End of UsersGuide.sgml -->