\documentclass[11pt]{book}

% \usepackage{modman}
\usepackage{html}
\usepackage{makeidx}
% \usepackage{fullpage}
\usepackage{jmb}
\usepackage{epsf}
\usepackage{cite}
\usepackage{rotating}
\usepackage{afterpage}
% \usepackage{overcite}
\usepackage{supertabular}

\makeindex

% Macros:
% -------

\def\tabtab{\rule{1cm}{0cm}}
\def\bull{$\bullet$}
\def\P{\\[0.2cm]}

%Underline below Figure or Table
\def\underfigtab{\vspace{-0.7cm}
                 \begin{center} \rule{7cm}{0.2mm} \end{center}}

%A title in its own line, smaller than subsubsection
\newcommand{\subsubsubsection}[1]{
\bigskip

{\em \noindent #1}

\smallskip
}

%Broken line for indicating a new theme without a title
\def\brokenline{\
  \hspace{1cm}
   \begin{center}
   \rule{9mm}{0.2mm} \rule{6mm}{0.0mm} \rule{9mm}{0.2mm}
   \rule{6mm}{0.0mm} \rule{9mm}{0.2mm} \rule{6mm}{0.0mm} \rule{9mm}{0.2mm}
   \end{center}
  \hspace{1cm}
}

% Underline:
\newcommand{\un}[1]{\underline{#1}}

%TLS tensors:
\newcommand{\TLS}{$\bf T$, $\bf L$ and $\bf S$}

% Enlarge and shrink the page for one line:
\newcommand{\longpage}{\enlargethispage{\baselineskip}}
\newcommand{\shortpage}{\enlargethispage{-\baselineskip}}

% Ensemble average
\newcommand{\ens}[1]{\langle#1\rangle}

% Figure~placeholders (won't work for tables!!!; the placement will be screwed):
\def\figplace{\begin{center} \fbox{\hspace{8cm} \rule{0cm}{1cm}} \end{center} }
\newcommand{\figholder}[1]{\rule{0cm}{#1}}
\def\pageinsert{\begin{figure}[htbp] \rule{0.cm}{30cm} \end{figure}}
\newcommand{\onepage}{\pageinsert}
\newcommand{\twopages}{\onepage\onepage}
\newcommand{\threepages}{\onepage\onepage\onepage}

% \newcommand{\onepage}{\newpage \mbox{\ } \newpage}
% \newcommand{\twopages}{\newpage \mbox{\ } \newpage \mbox{\ } \newpage}
% \newcommand{\threepages}{\newpage \mbox{\ } \newpage \mbox{\ } \newpage
%                          \mbox{\ } \newpage}

% Calpha, Cbeta, Cgamma:
\newcommand{\Calpha}{$\mbox{C}_\alpha$}
\newcommand{\Cbeta}{$\mbox{C}_\beta$}
\newcommand{\Cgamma}{$\mbox{C}_\gamma$}
\newcommand{\Cgammaone}{$\mbox{C}_{\gamma 1}$}
\newcommand{\Cgammatwo}{$\mbox{C}_{\gamma 2}$}
\newcommand{\Cdelta}{$\mbox{C}_\delta$}
\newcommand{\Cdeltaone}{$\mbox{C}_{\delta 1}$}
\newcommand{\Cdeltatwo}{$\mbox{C}_{\delta 2}$}
\newcommand{\Cepsilonone}{$\mbox{C}_{\epsilon 1}$}
\newcommand{\Cepsilontwo}{$\mbox{C}_{\epsilon 2}$}
\newcommand{\Czeta}{$\mbox{C}_\zeta$}
\newcommand{\Obeta}{$\mbox{O}_\beta$}
\newcommand{\Ogamma}{$\mbox{O}_\gamma$}
\newcommand{\Ogammaone}{$\mbox{O}_{\gamma 1}$}

% Right margin notes:
\newcommand{\margnote}[1] {\marginpar{\small $\leftarrow$#1}}

% Subscript, superscript
% the inclusion of \scriptsize command crashes LaTeX when the macros used
% in caption and some other environments; this can be corrected by the
% \protect command; The argument of the \subs or \sups command is typeset
% in text-mode (and can only be used in text-mode (add another \mbox around
% the command to use it in both text and math modes, but that will
% crash even more). Scriptsize command is relative to the \normalsize
% only. So, if you want to get proper size subscripts with other
% size basic text, include the size for scripts into the argument.
\def\subs#1{${}_{\mbox{\protect\scriptsize #1}}$}
\def\sups#1{${}^{\mbox{\protect\scriptsize #1}}$}

% Degrees Celsius, degrees, Subsite, Subsite', Position, Position'
% In these commands, the argument is processed in math-mode and the
% size of super/sub-scripts will be fine whatever the size of the
% basic font; note the use of the mathmode only style \scriptstyle here,
% as opposed the \scriptsize used in text-mode; explicit \scriptstyle
% in math-mode prevents the error message 'scriptscriptfont undefined'.
\def\oC{\mbox{${}^{\scriptstyle\circ}$C}}
\def\degr{\mbox{${}^{\scriptstyle\circ}$}}
\newcommand{\Sub}[1]{${\rm S}_{#1}$}
\newcommand{\Subp}[1]{${\rm S}'_{\rm #1}$}
\newcommand{\Pos}[1]{${\rm P}_{#1}$}
\newcommand{\Posp}[1]{${\rm P}'_{\rm #1}$}

% Programs:
\newcommand{\GROMOS} {\mbox{\sc Gromos}}
\newcommand{\COMPARER} {\mbox{\sc Comparer}}
\newcommand{\ALIGNER} {\mbox{\sc Aligner}}
\newcommand{\MOLSCRIPT} {\mbox{\sc Molscript}}
\newcommand{\CLUSTALV} {\mbox{\sc Clustalv}}
\newcommand{\CHARMM} {\mbox{\sc Charmm}}
\newcommand{\QUANTA} {\mbox{\sc Quanta}}
\newcommand{\RASMOL} {\mbox{\sc Rasmol}}
\newcommand{\INSIGHT} {\mbox{\sc InsightII}}
\newcommand{\GRASP} {\mbox{\sc Grasp}}
\newcommand{\MATCHMAKER} {\mbox{\sc MatchMaker}}
\newcommand{\PROFIT} {\mbox{\sc Profit}}
\newcommand{\MODELLER} {\mbox{\sc Modeller}}
\newcommand{\MOULDER} {\mbox{\sc Moulder}}
\newcommand{\MOD} {\mbox{\sc Mod}}
\newcommand{\RESTRAIN} {\mbox{\sc Restrain}}
\newcommand{\MNYFIT} {\mbox{\sc Mnyfit}}
\newcommand{\FRODO} {\mbox{\sc Frodo}}
\newcommand{\ARIADNE} {\mbox{\sc Ariadne}}
\newcommand{\DISMAN} {\mbox{\sc Disman}}
\newcommand{\COMPOSER} {\mbox{\sc Composer}}
\newcommand{\LOPAL} {\mbox{\sc Lopal}}
\newcommand{\KITSCH} {\mbox{\sc Kitsch}}
\newcommand{\PHYLIP} {\mbox{\sc Phylip}}
\newcommand{\PROCHECK} {\mbox{\sc Procheck}}
\newcommand{\DRAWTREE} {\mbox{\sc Drawtree}}
\newcommand{\DRAWGRAM} {\mbox{\sc Drawgram}}
\newcommand{\ALIGN} {\mbox{\sc Align}}
\newcommand{\JOY} {\mbox{\sc Joy}}
\newcommand{\TOP} {\mbox{\sc Top}}
\newcommand{\MDT} {\mbox{\sc Mdt}}
\newcommand{\XS} {\mbox{\sc Xs}}
\newcommand{\DIH} {\mbox{\sc Dih}}
\newcommand{\PLOT} {\mbox{\sc Plot}}
\newcommand{\LSQ} {\mbox{\sc Lsq}}
\newcommand{\CORR} {\mbox{\sc Corr}}
\newcommand{\PSA} {\mbox{\sc Psa}}
\newcommand{\DISULF} {\mbox{\sc Disulf}}
\newcommand{\GETCSR} {\mbox{\sc Getcsr}}
\newcommand{\SSTRUC} {\mbox{\sc Sstruc}}
\newcommand{\DSSP} {\mbox{\sc Dssp}}
\newcommand{\THREADER} {\mbox{\sc Threader}}
\newcommand{\ACC} {\mbox{\sc Acc}}
\newcommand{\HBD} {\mbox{\sc Hbd}}
\newcommand{\NGH} {\mbox{\sc Ngh}}
\newcommand{\CNT} {\mbox{\sc Cnt}}
\newcommand{\THREED} {\mbox{\sc 3d}}
\newcommand{\ASGL} {\mbox{\sc Asgl}}
\newcommand{\UHBD} {\mbox{\sc Uhbd}}
\newcommand{\ELLIPSOID} {\mbox{\sc Ellipsoid}}
\newcommand{\RAMA} {\mbox{\sc Rama}}
\newcommand{\DDM} {\mbox{\sc Ddm}}
\newcommand{\TLSFIT} {\mbox{\sc Tlsfit}}
\newcommand{\PRINCONE} {\mbox{\sc Princ1}}
\newcommand{\PRINCTWO} {\mbox{\sc Princ2}}

% Computers, OS:
\newcommand{\PROLOG} {\mbox{\sc Prolog}}
\newcommand{\FORTRAN} {\mbox{\sc Fortran}}
\newcommand{\VAX} {\mbox{\sc Vax}}
\newcommand{\UNIX} {\mbox{\sc Unix}}
\newcommand{\PostScript} {\mbox{\sc PostScript}}
\newcommand{\XENIX} {\mbox{\sc Xenix}}

% AA, AA^2, \pH, pKa, kcat, Km, Ki, Biso, oC, tab
\newcommand{\tab } {\rule{1cm}{0cm}}
\newcommand{\RMS}{\mbox{\sc rms}}
\newcommand{\DRMS}{\mbox{\sc drms}}
\newcommand{\Ang}{\mbox{\AA}}
\newcommand{\kB}{\mbox{$k_B$}}
\newcommand{\Angsq}{\mbox{\Ang\sups{2}}}
\newcommand{\pH}{{\it p}H}
\newcommand{\pKa}{{\it p}K\subs{a}}
\newcommand{\dGw}{$\Delta G_{\mbox{H\subs{2}O}}$}
\newcommand{\kcat } {\mbox{\it k\subs{cat}}}
\newcommand{\Km } {\mbox{\it K\subs{M}}}
\newcommand{\Ki } {\mbox{\it K\subs{i}}}
\newcommand{\Biso } {\mbox{\it B\subs{iso}}}
% \newcommand{\kcat } {$k_{\mbox{cat}}$}
% \newcommand{\Km } {$K_{\mbox{\protect\scriptsize M}}$}
% \newcommand{\Ki } {$K_{\mbox{\protect\scriptsize i}}$}
% \newcommand{\Biso } {$B_{\mbox{\protect\scriptsize iso}}$}

% Latin words:
\newcommand{\Denovo}{\mbox{\em De novo}}
\newcommand{\denovo}{\mbox{\em de novo}}
\newcommand{\insitu}{\mbox{\em in situ}}
\newcommand{\Insitu}{\mbox{\em In situ}}
\newcommand{\Abinitio}{\mbox{\em Ab initio}}
\newcommand{\abinitio}{\mbox{\em ab initio}}
\newcommand{\versus}{\mbox{\em versus}}
\newcommand{\etal}{\mbox{\em et~al.}}
\newcommand{\etc } {\mbox{\em etc}}
\newcommand{\cf } {\mbox{\em cf}}
\newcommand{\ie } {\mbox{\em i.e.}}
\newcommand{\eg } {\mbox{\em e.g.}}
\newcommand{\via } {\mbox{\em via}}
\newcommand{\adhoc } {\mbox{\em ad~hoc}}
\newcommand{\invivo } {\mbox{\em in~vivo}}
\newcommand{\invacuo} {\mbox{\em in~vacuo}}
\newcommand{\invitro } {\mbox{\em in~vitro}}
\newcommand{\viceversa } {\mbox{\em vice~versa}}
\newcommand{\aposteriori } {\mbox{\em a~posteriori}}
\newcommand{\apriori } {\mbox{\em a~priori}}
\newcommand{\cis } {\mbox{\em cis}}
\newcommand{\trans } {\mbox{\em trans}}
\newcommand{\dd}{ \; \mbox{d}}

%Greek characters
% \newcommand{\D}{$\Delta$}
\newcommand{\al}{$\alpha$}
\newcommand{\be}{$\beta$}
\newcommand{\ga}{$\gamma$}
\newcommand{\de}{$\delta$}
\newcommand{\ep}{$\epsilon$}
\newcommand{\micro}{$\mu$}
% Various LaTeX2e definitions:

% Change the default page sizes:
%
\topmargin 0pt
\advance \topmargin by -\headheight
\advance \topmargin by -\headsep
% \addtolength{\topmargin}{-\headheight}
% \addtolength{\topmargin}{-\headsep}
\textheight 9.3in
\oddsidemargin -0.2in
\evensidemargin \oddsidemargin
\marginparwidth 0.4in
\textwidth 6.9in

\newcommand{\beautylb}{\linebreak}
\newcommand{\beautypb}{\clearpage}

\pagestyle{headings}     % numbering style  (or plain, empty, myheadings)

\renewcommand{\baselinestretch}{1.00}    %  relative line spacing

\parskip 1.2mm      %  additional vertical paragraph spacing

\newcommand{\Command}[2]{\subsection{#1 --- #2} \index{#1@{\bf #1}}}

\newcommand{\Commandline}[1]{\begin{description} \item[Command:]
                             #1
                             \end{description}}

\newcommand{\Output}[1]{\begin{description} \item[Output:]
                             #1
                             \end{description}}

\newcommand{\Requirements}[1]{\begin{description} \item[Requirements:]
                             #1
                             \end{description}}

\newcommand{\Description}[1]{\begin{description} \item[Description:]
                             #1
                             \end{description}}

%\begin{htmlonly}
%  \newenvironment{newenv}{{}{}}
%\end{htmlonly}

\latex{\newcommand{\Options}[1]{{\noindent\bf Options:} \\ #1 }}
\html{\newcommand{\Options}[1]{{\noindent\bf Options:} \\ % #1}}
                          \begin{figure}[Hhtb] #1 \end{figure}}}

\newcommand{\OptLine}[5]{\tabtab
      \parbox[t]{2.40in}{{\small\sloppy \K{#1} = #2{#3}}}\hspace{0.016in}
      \parbox[t]{1.35in}{{\small\sloppy\tt #4}}\hspace{0.016in}
      \parbox[t]{2.75in}{{\small\sloppy #5}}\\[1mm]}

\newcommand{\SeeExample}[1]{{\noindent\bf Example:} See #1 command.}

\newenvironment{Examples}
{\begin{description} \item[Example:] \ \\[-6mm]}
{\end{description} \ \\[-2mm]}

% Special formatting codes for special objects
\newcommand{\Scr}[1]{{\tt \_\_#1}}       % modeller script
\newcommand{\V}[1]{{\tt #1}}            % computer value (filename, variable, term, ...)
\newcommand{\Z}[1]{{\tt '#1'}}          % string
\newcommand{\K}[1]{{\sf #1}\index{#1@{\sf #1}}}  % TOP keyword
\newcommand{\C}[1]{{\bf #1}\index{#1@{\bf #1}}}  % TOP command
\newcommand{\OR}{{\tt |}}
\newcommand{\AND}{{\tt \&}}
% write :N after the keyword:
\newcommand{\vartype}[2]{\mbox{$\langle{\tt #1:#2}\rangle$}}
\newcommand{\Real}[1]{\vartype{real}{#1}}
\newcommand{\Integer}[1]{\vartype{integer}{#1}}
\newcommand{\String}[1]{\vartype{string}{#1}}
\newcommand{\Logical}[1]{\vartype{logical}{#1}}
\newcommand{\Quantity}[1]{\vartype{quantity}{#1}}
\newcommand{\Variable}[1]{\vartype{variable}{#1}}
\newcommand{\Constant}[1]{\vartype{constant}{#1}}
\newcommand{\Number}[1]{\vartype{number}{#1}}
\title{\vspace{3cm} \ASGL, Ver 1.2 \\[1cm]
       PostScript Plotting Program \\[3cm]}

\author{Andrej \v{S}ali \\[0.5cm]
The Rockefeller University  \\
1230 York Avenue \\
New York, NY 10021-6399, USA  \\
tel +1-212-327 7550, fax +1-212-327 7540  \\
email \htmladdnormallink{{\tt sali@rockvax.rockefeller.edu}}{mailto:sali@rockvax.rockefeller.edu} \\
URL \htmladdnormallink{{\tt http://guitar.rockefeller.edu/}}{http://guitar.rockefeller.edu/}
}

\date{1 January, 1997}

\begin{document}

\frontmatter

\begin{titlepage}
  \maketitle
\end{titlepage}

\tableofcontents

\newpage

\mainmatter

\part{User's Guide}

\chapter{Introduction}

\section{What is \ASGL ?}


\begin{description}

\item[Purpose:]
      Easy creation of PostScript files containing scientific plots.


\item[Capabilities:] \

\begin{itemize}
\item 2D plots:
      scatter plots, curve plots, smoothed curve plots, transformation
      of axes, histograms, spectra, general axes, and plot labelling;

\item 3D plots: density plots;

\item molecule plots:
      ball-and-stick plots of a molecule in a Brookhaven Protein Databank
      format file; general labelling; virtual Calpha-Calpha
      bonds; stereo plots;

\item the attributes of the objects to be drawn can be varied by the user;
   for example, the grayness and width of lines, the size of fonts,
   the grayness of histogram bars, \etc.
\end{itemize}


\item[Use:] \

\ASGL\ is used via a steering file. A steering file contains commands
specialized for creation of plots. This file is interpreted by \TOP\ which
then calls appropriate Fortran subroutines to create the PostScript output
file. See Chapter~\ref{CHAPTERTOP} for description of \TOP.
\end{description}


\newpage


\section{Using \ASGL\ with the \TOP\ steering file}

The \ASGL\ program is run by:

{\tt asgl job}

\noindent where {\tt job} is the root of the steering file --- the actual
steering file must have an extension {\tt .top}. By default, the output of
the program is then written to the {\tt job.ps} file that can be printed on the
PostScript printer, previewed with a PostScript previewer, modified,
or included in other documents, such as \TeX\ files.

\ASGL\ reads PostScript definitions of line types, font types and
symbols from text file {\tt src/psgl1.ini}. This file can be edited to
extend the capabilities of \ASGL. For example, line widths, grayness,
dash-dot combinations, font types and sizes, symbol types and sizes
can be customized in this way.

There are four coordinate systems (or windows) used by \ASGL. The Base
PostScript system corresponds to the PostScript device and has the
Bounding Box (0,0,612,792). The Paper coordinate system is used
to specify the Bounding Box and its orientation of the window
on the paper that will contain the plot. It overlaps with
the Base PostScript system except that it uses cm; its Bounding Box
is (0,0,21.59,27.94). The World coordinate system is defined by
the data to be plotted. It overlaps with the window specified in
the Paper coordinate system. The Plot coordinate system is used for
creating the plot. The origin of the Plot coordinate system is always (0,0),
XMAX is always 1, and YMAX is such that it retains the X/Y aspect
of the Paper coordinate system. It overlaps with the window specified
in the Paper and World coordinate systems.

Probably the easiest way to use \ASGL\ is to take an example \TOP\ file
from {\tt examples} sub-directory that is closest to what you need and
edit it to suit your requirements exactly. The example \TOP\ files
and their output are given in Chapter~\ref{CHAPTEREXAMPLES}.

A complete list of \ASGL\ commands is given in Chapter~\ref{CHAPTERASGL}.

    \newpage

\section{ASGL installation}

    \begin{verbatim}
                              INSTALLATION


                                ASGL 1.1

                           PostScript Plotting
                                                  v
                    Copyright(c) 1989-1993 Andrej Sali
                            All Rights Reserved





Supported computers:

ASGL 1.1 runs on Silicon Graphics Iris 4D, Convex C2, Sun 4,
IBM RS/6000, DEC Decstation, DEC Alpha station, and compiles with
the public domain f2c fortran-to-c translator. To obtain f2c, use
the anonymous ftp service on research.att.com. Its IP address is
192.20.225.2; login with the username `netlib'. The f2c translator
allows ASGL to run on virtually any UNIX computer.




Installation:


If you have the ASGL.tar.Z distribution file:

  1) Unpack the distribution file:

     zcat ASGL.tar.Z | tar xvf -

     The result will be a directory ./asgl


  2) If you use tcsh Ver 6 or later than HOSTTYPE environment variable
     is defined automatically and you can skip this step.

     Make sure the HOSTTYPE environment variable is defined by doing
     either of:

     a) Define HOSTTYPE in your login script file:

             for sh :  HOSTTYPE=iris4d; export HOSTTYPE

             for csh:  setenv HOSTTYPE iris4d


        Source your login script:

             for sh :  . script_file

             for csh:  source script_file


     b) Edit the script `src/hosttype' to produce the correct result
        on your host.



  3) Set the environment variable ASGLINSTALL to the directory where you
     want to have ASGL installed. Create this directory. For example,
     for the tcsh or csh shells:

     setenv ASGLINSTALL /usr/local/bin
     mkdir $ASGLINSTALL



  4) Compile and install the program, library files, manual, and examples:

     make all

     If you are not using one of the compilers listed above
     you will probably have to modify the Makefile in the
     src\ sub-directory. Hopefully, you won't have to modify
     the fortran code.

     You will also have to compile manually the program collect.f in
     the doc\ directory before you try to create the document by
     `make all'. Usually, `f77 collect.f -o collect' will do.


  5) Change your login script to include the following (for csh or tcsh):

     # Root directory for installed ASGL:
     setenv ASGLINSTALL /usr/local/bin/asgl

     # Set ASGL environment variables and update the command path:
     if (-e $ASGLINSTALL/setasgl) source $ASGLINSTALL/setasgl


   6) Source your login script. You can now start using ASGL. See
      the examples in the tests\ directory. You may (but do not have
      to) delete the ASGL distribution directory.


   7) The `hosttype mechanism' allows transparent ASGL installation
      and use of the same installation directory on some networks of
      different host types. For example, at Harvard we have an NFS
      and Yellow Pages network with only one home directory per user
      for almost all the machine types listed above. In such a case,
      to install ASGL on another host type in the same directory,
      you only have to login to that host, clean the distribution
      directory by `make distclean' and do `make all' again. Exactly
      the same commands (scripts) are used on all hosts to run the
      ASGL programs.
    \end{verbatim}

\newpage

\chapter{Using \ASGL} \label{CHAPTERASGL}

\section{\ASGL\ commands}

\Command      {\#EPSF}{produce encapsulated PostScript}
\Commandline  {\#EPSF [ .ps \OR\ .eps ]}
\Description  {
If the very first line in the steering file starts with the above in the
first column, \ASGL\ will
create a PS file that conforms to the Encapsulated PostScript standard.
In this case, only one page graphics per file can be produced. Optionally,
you can also specify the extension for the PS filename. It is usually
{\tt .eps} for the Encapsulated PostScript, but you may want to keep it
as {\tt .ps} if you depend on it in some other programs. The default is
{\tt .ps}. You can only specify the extension when \C{\#EPSF} is the first
line. If you produce an EPSF file you can include it properly in the
\LaTeX\ document using: \\
% \begin{center}
% {\tt
% \\begin\{center\} \\
%   \\leavevmode \\
%   \\def\epsfsize\#1\#2\{scaling\_factor \#1\} \\
%   \\epsffile\{file\_name.ps\} \\
% \\end\{center\}
% \end{center}
% }
}


\Command      {SET STAMP\_TEXT}{stamp the page}
\Commandline  {SET STAMP\_TEXT = \String{1} \hspace{1cm}
                                 [ \V{DEFAULT} \OR\ \V{NONE}
                                   \V{your text}], STAMP\_SIZE = \Real{1} }
\Description  {If set to \V{DEFAULT} the page will be stamped at the bottom
right
corner with the \ASGL\ version, date, time, filename, and page number.
The default value is \V{DEFAULT} for PostScript and \V{NONE} for Encapsulated
PostScript. The command is not allowed in Encapsulated PostScript.
}


\Command      {READ\_TABLE}{read the Table array of data}

\Options{
\OptLine{FILE}{\String}{1}{'counter'}{ partial or complete filename} \\
\OptLine{ADD\_DATA}{\Logical}{2}{OFF OFF}{} \\
\OptLine{POINT\_MODULUS}{\Integer}{1}{1}{} \\
\OptLine{ROW\_RANGE}{\Integer}{2}{0 0}{} \\
}
\Description{
This command will read a text file containing a rectangular array
of values. The columns represent vectors that can be later
used for plotting as X and Y coordinates. This array will be referred
to as the Table array. If \K{ADD\_DATA[1]} = \V{ON} new columns will be appended to
the right of the existing columns. The new number of data points is the
number of rows in the new file. If \K{ADD\_DATA[2]} = \V{ON} new rows will be
appended to the end of the existing rows. The new number of columns is the
number of columns in the new file. The command will only read the points
whose index satisfies $\mbox{mod}(i-1, \K{POINT\_MODULUS}) = 0$ and is
within boundaries of \K{ROW\_RANGE}. \K{ROW\_RANGE} can be 0 or -999 to
indicate that it is to be ignored. The
total number of points read is approximately for a factor of
\K{POINT\_MODULUS} smaller than the total number of points between selected
rows in a file. This option is useful for plotting very large files.
The line can start with `\#', in which case it will be ignored as far
as the points are concerned. There can be string columns in the file
that can contain data for point labelling by \C{PLOT2D}.
Number/string column identification is achieved in one of the two
ways: If there is a comment line `\#COLUMNS' before any non-comment line,
then that line is used for identification.
The comment line must contain a series of `N' for number columns
and `S' for string columns, in the correct order.
Otherwise, the items from the
first non-comment line are interpreted as numbers or strings.
A string is everything that cannot be interpreted as a number. If you
want blanks in strings, quote them in single quotes '. The last line
starting with `\#CAPTION\_TEXT' is assigned to \K{CAPTION\_TEXT}, which is
useful for automated production of titles. Similarly for
`\#PRINT\_TEXT' and `\#DESCRIPTION'.
}


\Command      {WRITE\_TABLE}{write the Table array of data}

\Options{
\OptLine{FILE}{\String}{1}{'counter'}{ partial or complete filename} \\
\OptLine{NO\_XY\_SCOLUMNS}{\Integer}{2}{0 0}{} \\
\OptLine{ XY\_SCOLUMNS}{\Integer}{0}{}{} \\
}
\Description  {
It will write a text file containing an array of values, where columns
are selected from the Table array using the \K{NO\_XY\_SCOLUMNS} and
\K{XY\_SCOLUMNS} variables.  See \C{WORLD} for explanation of
these variables.}



\Command      {READ\_DPLOT}{read the Density array of data}

\Options{
\OptLine{FILE}{\String}{1}{'counter'}{ partial or complete filename} \\
\OptLine{DPLOT\_FORMAT}{\Logical}{1}{OFF}{} \\
\OptLine{DPLOT\_COLUMN}{\Integer}{1}{1}{} \\
\OptLine{DPLOT\_SYMMETRIZE}{\Logical}{1}{OFF}{} \\
\OptLine{DPLOT\_FILL}{\Real}{1}{0}{} \\
\OptLine{DPLOT\_ORIENTATION}{\String}{1}{'XY'}{ YX} \\
% \K{DPLOT\_ORIENTATION}  = \String{1}  & XY \OR\ YX\\
}
\Description{It will read a text file containing the Density
array of data.  Two formats are possible. In free format
(\K{DPLOT\_FORMAT}=\V{OFF}), a text file must contain two integer dimensions
(NX,NY) followed by data NX * NY values. The first line can contain NX and
NY, at most. The following lines can contain a single row of an array,
at most. The order of reading the elements is:

{\tt read(ioinp,*)NX,NY \\
   do  i = 1, NX \\
     read(ioinp,*) (array(i,j),j=1,NY) \\
   end do
}

This array can then be plotted using \C{DPLOT} command. The
array(1,1) element will appear at the coordinate system origin, in the
lower left corner of the coordinate system. When
formatted input is used (\K{DPLOT\_FORMAT}=\V{ON}), a text file contains any
number of lines in the form:

   I, J, \V{number\_1} \V{number\_2}, ...,  \V{number\_DPLOT\_COLUMN}, ...

These lines are read and the Density array is filled in on the fly as
specified by the I and J indices and the value in column \K{DPLOT\_COLUMN}.
All other numbers in a line are ignored. The elements of the Density
array not assigned explicitly are set to \K{DPLOT\_FILL}.

With the formatted input, when \K{DPLOT\_SYMMETRIZE} = \V{ON}, the array
is also symmetrized, \ie\ array(j,i)=array(i,j) for each line that is read in.

If the \K{DPLOT\_ORIENTATION} is \V{YX}, instead of \V{XY}, the X and Y
axes are swapped during reading in the data.
}




\Command      {WRITE\_DPLOT}{write the Density array of data}

\Options{
\OptLine{FILE}{\String}{1}{'counter'}{ partial or complete filename} \\
\OptLine{DPLOT\_FORMAT}{\Logical}{1}{OFF}{} \\
\OptLine{ DPLOT\_ORIENTATION}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} \\
% \K{DPLOT\_ORIENTATION}   = \String{1}  & XY \OR\ YX\\
}

\Description{It will write a text file containing the Density
array of data.  Two formats are possible. In free format
(\K{DPLOT\_FORMAT}=\V{OFF}), the text file will contain two integer dimensions
(NX,NY) followed by data NX * NY values. The first line will contain NX and
NY, at most. The following lines will contain a single row of an array,
at most. The order of writing the elements is:

{\tt
   read(ioinp,*)NX,NY \\
   do  i = 1, NX \\
     read(ioinp,*) (array(i,j),j=1,NY) \\
   end do
}

When
formatted output is used (\K{DPLOT\_FORMAT}=\V{ON}), the text file will contain
a number of lines in the form:

   I, J, ARRAY

If the \K{DPLOT\_ORIENTATION} is \V{YX}, instead of \V{XY}, the X and Y
axes are swapped during writing out the data.
}



\Command      {WORLD}{define the extent of your data}

\Options{
\OptLine{PERSPECTIVE}{\Logical}{1}{OFF}{} \\
\OptLine{EYE\_TO\_SCR}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} \\
\OptLine{SCR\_TO\_TOP}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} \\
\OptLine{PAPER\_WINDOW}{\Real}{5}{7.0 15.8 17.0 23.0 0.0}{} \\
\OptLine{POSITION}{\Integer}{2}{0 1}{} \\
\OptLine{WORLD\_WINDOW}{\Real}{4}{-999. -999. -999. -999.}{} \\
\OptLine{WORLD\_FRACTION}{\Real}{1}{-999}{} \\
\OptLine{NO\_XY\_SCOLUMNS}{\Integer}{2}{0 0}{} \\
\OptLine{XY\_SCOLUMNS}{\Integer}{0}{}{} \\
\OptLine{ A4\_WINDOW\_MARGIN}{\Logical}{1}{OFF}{} \\
}
\Description  {
This command has to be called before any plotting is done. It
calculates the extent of the plot and initializes the Plot coordinate
system --- it determines its position on a paper. If you selected
automatic World bounds setting, you should have your data already
read by the \C{READ\_TABLE}, \C{READ\_DPLOT}, or \C{READ\_PDB} commands.

When plotting a PDB structure, the \K{PERSPECTIVE}, \K{EYE\_TO\_SCR}, and
\K{SCR\_TO\_TOP} have to be set up at the time of drawing with the
\C{BALL\_STICK} command to properly scale the plot.

   \K{PAPER\_WINDOW}
   defines the position and orientation of a window on the paper.
   The format is (XMIN YMIN XMAX YMAX ORIENTATION). The origin for
   rotation is the origin of the Base PostScript coordinate system
   which is in the lower left corner of a paper. Units are cm and
   degrees. This
   window on the paper will contain the data from \K{WORLD\_WINDOW}. Any
   data points outside this area will be clipped. If orientation of
   the window is 90\degr\ then the plot will be printed in the
   landscape mode.

   In \K{POSITION},
   if the first element is different from 0 then the \K{PAPER\_WINDOW} is
   defined automatically using the position codes (1--37) irrespective
   of the value of \K{PAPER\_WINDOW}. The following convention is used:

   \begin{description}
     \item[1 --  8]  small 1-4, left column; 5-8, right column (8 plots / page)
     \item[9 -- 11]  medium small (3 plots / page)
     \item[12 -- 13]  medium (2 plots / page)
     \item[14]  medium large (1 plots / page)
     \item[15]  large, landscape (1 plots / page)
     \item[16 -- 37]  tiny, portrait (32 plots / page)
   \end{description}

   If the second element is 0, the aspect ratio between X and Y is set
   to 1.3333 (horizontal rectangle), if it is 1 the aspect ratio is 1.0
   (square), if it is 2 the aspect ratio is 3.9 (very extended horizontal
   rectangle).

   \K{WORLD\_WINDOW}
   defines the coordinate axes in the World of the data to be
   plotted. These ranges will correspond to the \K{PAPER\_WINDOW} window.
   However, if any of the four values is -999 (by default this is the
   case), the program will try to calculate that value from the data
   read in by the last data input command (\C{READ\_TABLE},
   \C{READ\_DPLOT}, or \C{READ\_PDB}).

   \K{WORLD\_FRACTION}
   defines the fraction of the number of the central points that are
   used to get the \K{WORLD\_WINDOW} when calculated automatically.
   By default, this is 1. This is useful when there are a small number
   of outliers that you do not want to plot because the large scale
   would observe the relationship between the remaining points.

   \K{NO\_XY\_SCOLUMNS}
   defines the numbers of selected columns in the Table array that
   are to be examined for the maximal and minimal values of X and Y,
   respectively, when calculating the real World extent of the graph.
   If any of the numbers is 0 then \K{NO\_XY\_SCOLUMNS} and \K{XY\_SCOLUMNS}
   are set to reflect the values in \K{XY\_COLUMNS}.
   Use this variable when automatic boundaries are required
   for multi-line plots and it is not clear which data vector should
   be used for bounds setup.

   In multi-plot plots, do not forget that undefined \K{NO\_XY\_SCOLUMNS}
   and \\
   \K{XY\_SCOLUMNS} are set automatically in the first \C{WORLD}
   command and will stay defined until reset with \C{SET} or \C{RESET}
   commands.

   \K{XY\_SCOLUMNS}
   defines the columns for the range searching (see also above).
   The first \K{NO\_XY\_SCOLUMNS(1)} integers define the X-columns
   in the Plotting
   array for X range and the last \K{NO\_XY\_SCOLUMNS(2)} integers are the
   Y columns for the Y range.

   If \K{A4\_WINDOW\_MARGIN} is \V{ON} a line around the Bounding Box of the
   Base PostScript coordinate system is drawn, \ie\ A4 paper is bounded.
}



\Command      {AXES2D}{draw coordinate axes, ticks, and labels}

\Options{
\OptLine{Y\_SCALE}{\String}{1}{'LEFT'}{} \\
\OptLine{CAPTION\_XLEFT}{\Real}{1}{-0.15}{} \\
\OptLine{CAPTION\_XRIGHT}{\Real}{1}{1.07}{} \\
\OptLine{TICK\_FONT}{\Integer}{1}{3}{} \\
\OptLine{X\_LABEL\_STYLE}{\Integer}{1}{2}{} \\
\OptLine{Y\_LABEL\_STYLE}{\Integer}{1}{2}{} \\
\OptLine{X\_LABELS}{\String}{0}{''}{} \\
\OptLine{Y\_LABELS}{\String}{0}{''}{} \\
\OptLine{X\_TICK}{\Real}{0}{-999. -999. -999.}{} \\
\OptLine{Y\_TICK}{\Real}{0}{-999. -999. -999.}{} \\
\OptLine{X\_LABEL\_SHIFT}{\Real}{1}{0}{} \\
\OptLine{Y\_LABEL\_SHIFT}{\Real}{1}{0}{} \\
\OptLine{X\_TICK\_LABEL}{\Integer}{2}{-999 -999}{} \\
\OptLine{Y\_TICK\_LABEL}{\Integer}{2}{-999 -999}{} \\
\OptLine{X\_TICK\_DECIMALS}{\Integer}{1}{-999}{} \\
\OptLine{Y\_TICK\_DECIMALS}{\Integer}{1}{-999}{} \\
\OptLine{Y\_AXIS\_FACTOR}{\Real}{1}{1}{} \\
\OptLine{Y\_AXIS\_FACTOR}{\Real}{1}{1}{} \\
\OptLine{EXPONENT}{\Logical}{1}{OFF}{} \\
% \K{Y\_SCALE}          = \String{1} & \V{LEFT} \OR\ \V{RIGHT} \\
}

\Description  {
It will plot the axes of the coordinate system.

   \K{TICK\_FONT} sets the font size for labeling the ticks.

   \K{X\_LABEL\_STYLE} and \K{Y\_LABEL\_STYLE} select the labelling regime:
   \begin{description}
   \item[1] labels for X,Y-ticks supplied explicitly to the routine.
   \item[2] labels calculated automatically.
   \item[3] labels not displayed at all.
   \end{description}

   \K{X\_TICK} and \K{Y\_TICK} define, in World coordinates, the position
   of the first tick on the X,Y-axes, the spacing between the ticks, and the
   rightmost tick position.

   \K{X\_LABEL\_SHIFT} and \K{Y\_LABEL\_SHIFT} shift the X/Y-axes
   labels. Shifts are specified in the Plot coordinates.

   \K{X\_TICK\_LABEL} and \K{Y\_TICK\_LABEL} set the index of the X/Y-axes
   ticks that are numbered first, and also every which tick from the first
   one on is numbered.

   \K{X\_TICK\_DECIMALS} and \K{Y\_TICK\_DECIMALS} set the number of decimal
   places used in the automatic calculation of the X/Y-axes tick
   labels. If 0, only a dot will appear after an integer. If $-1$ only
   an integer will appear.

   If \K{Y\_SCALE} is \V{RIGHT} it will plot the Y-axis ticks and their
   numbers on the right side of the plot. Default is \V{LEFT}.

   \K{CAPTION\_XLEFT} and \K{CAPTION\_XRIGHT} are returned by \C{AXIS2D}
   for later use by the \C{CAPTION} command in placing the captions next
   to the Y-axis. If these automatic values are not good you can correct
   them manually (rarely needed).

   \K{X\_AXIS\_FACTOR} is used to scale the X-label ticks before the
   label is written out. If \K{EXPONENT} is \V{ON} then `En' is
   added to the tick label where
   $n = \mbox{nint}[\log10(\mbox{\K{X\_AXIS\_FACTOR}})]$.
   If \K{EXPONENT} is \V{OFF} then `En' is not added and could be
   included in the axis label with the \C{CAPTION CAPTION\_POSITION = 4 or 5}
   command.
}




\Command      {PLOT2D}{draw a 2D line or scatter plot}

\Options{
\OptLine{PLOT2D\_SYMBOL\_TYPE}{\Integer}{1}{0}{} \\
\OptLine{PLOT2D\_LINE\_TYPE}{\Integer}{1}{1}{} \\
\OptLine{XY\_COLUMNS}{\Integer}{2}{1 2}{} \\
\OptLine{POINT\_FONT}{\Integer}{1}{6}{} \\
\OptLine{LABEL\_FONT}{\Integer}{1}{6}{} \\
\OptLine{LABEL\_LOCATION}{\Integer}{1}{2}{} \\
\OptLine{LABEL\_COLUMN}{\Integer}{1}{0}{} \\
}
\Description  {
This command will plot a line and/or the points defined by the selected
columns in the Table array.

   \K{PLOT2D\_SYMBOL\_TYPE} defines the symbol to be plotted for every point.
   If 0 nothing is plotted. If set to $-1$, then the centered
   integer indices are plotted for each point.

   \K{PLOT2D\_LINE\_TYPE} defines a line type to be plotted between successive
   points in the Table array. If 0 no line is plotted --- used for
   scatter plots.

   \K{XY\_COLUMNS} selects X and Y columns in the Table array. If any of
   the two columns is not defined, it is substituted by a vector
   $1,2,\ldots,N$.

   \K{POINT\_FONT} selects the font for the point symbol in the case where \\
   \K{PLOT2D\_SYMBOL\_TYPE} = $-1$.

   If \K{LABEL\_COLUMN} is a string column, then the labels in that
   column are drawn for each point. If \K{LABEL\_LOCATION} is 1,
   the label is centered on the point, if 2 the label is to the right
   of the point. \K{LABEL\_FONT} is the font type for the labels.
}





\Command      {SPECTRUM}{draw a bar code plot}

\Options{
\OptLine{PLOT2D\_LINE\_TYPE}{\Integer}{1}{1}{} \\
\OptLine{BAR\_XSHIFT}{\Real}{1}{0.0}{} \\
\OptLine{BAR\_WIDTH}{\Real}{1}{1.0}{} \\
\OptLine{XY\_COLUMNS}{\Integer}{2}{1 2}{} \\
}
\Description  {
This command plots an energy spectrum looking like a vertical bar code.

    \K{PLOT2D\_LINE\_TYPE} defines the line type to be used for horizontal
    energy levels.

    \K{XY\_COLUMNS} selects the Y column in the Table array that specifies
    energy levels. Note that Y column is plotted, not X column. This is to be
    consistent with the \C{WORLD} command.

    \K{BAR\_XSHIFT} specifies the starting X of the energy levels in
    the World coordinates.

    \K{BAR\_WIDTH} defines a relative width of the bars in the World
    coordinates.
}




\Command      {HIST2D}{draw a 2D histogram}

\Options{
\OptLine{BAR\_GRAYNESS}{\Real}{0}{0.7}{} \\
\OptLine{BAR\_WIDTH}{\Real}{1}{1.0}{} \\
\OptLine{BAR\_LINE\_TYPE}{\Integer}{1}{2}{} \\
\OptLine{NO\_XY\_SCOLUMNS}{\Integer}{2}{0 0}{} \\
\OptLine{XY\_SCOLUMNS}{\Integer}{0}{}{} \\
\OptLine{XY\_COLUMNS}{\Integer}{2}{1 2}{} \\
\OptLine{BAR\_XSHIFT}{\Real}{1}{0.0}{} \\
}
\Description{
    This command plots a histogram of X and Y columns in the Table array.

    \K{BAR\_GRAYNESS} defines the grayness of the bar on the scale from
    0.0 (black) to 1.0 (white).

    \K{BAR\_WIDTH} defines a relative width of the bars where 1.0 would
    make two neighbouring bars touch each other. If less than 1 there is
    empty space between bars.

    \K{BAR\_LINE\_TYPE} defines a linetype used to border the bar in the $\Pi$
    shaped way. If linetype is 0 bordering is not done.

    In \K{NO\_XY\_SCOLUMNS}, the first element has to be 1 because there can
    only be one X-column.
    The second element is the number of Y-columns. It is 1 for normal
    histograms and more than 1 for a histogram where bars are stacked on
    top of each other to get a stacked bar at a single X value.

    \K{XY\_SCOLUMNS} specifies X-column and Y-columns in the Table array
    for the histogram. The dimension of \K{XY\_SCOLUMNS} has to be
    \K{NO\_XY\_SCOLUMNS(1)} + \K{NO\_XY\_SCOLUMNS(2)}. The default values
    for \K{NO\_XY\_SCOLUMNS} and \K{XY\_SCOLUMNS} (when the inputs are 0)
    are obtained from \K{XY\_COLUMNS}.  If the X-column is not defined,
    it is substituted by a vector
    1,2,...,N. The X coordinate of the bar specifies its mid-point
    (not the left edge, for example). X-interval corresponding to
    one bar is always calculated automatically as the difference
    between the first and last X divided by the number of bars less 1.
    This works well when you have equal spacing between the points on X
    axis. If not you can always correct the bar width using \K{BAR\_WIDTH}.

    \K{XY\_COLUMNS} is used only when default values for
    \K{XY\_SCOLUMNS} are required.

    \K{BAR\_XSHIFT} shifts the bars for this amount along the X-axis. This is
    to allow the plotting of several bars at the same X without
    modifying the data files.
}





\Command      {DPLOT}{draw a density plot}

\Options{
\OptLine{BAR\_LEGEND}{\Logical}{1}{ON}{} \\
\OptLine{BAR\_LEGEND\_PLACES}{\Integer}{2}{7 1}{} \\
\OptLine{DPLOT\_GRAYNESS}{\Real}{2}{1.0 0.0}{} \\
\OptLine{DPLOT\_LINE\_TYPE}{\Integer}{1}{3}{} \\
\OptLine{DPLOT\_PART}{\String}{1}{'FULL'}{ (LOWER, FULL)} \\
\OptLine{DPLOT\_BOUNDS}{\Real}{2}{-999. -999.}{} \\
\OptLine{DPLOT\_STYLE}{\String}{1}{'GRAY'}{ (GRAY BLACK)} \\
\OptLine{NUMBER\_DENSITY\_PLOT}{\Logical}{1}{OFF}{} \\
\OptLine{NUMBER\_PLACES}{\Integer}{2}{5 2}{ pre- and post-decimal point places} \\
\OptLine{POINT\_FONT}{\Integer}{1}{6}{} \\
\OptLine{PRINT\_FONT}{\Integer}{1}{4}{} \\
\OptLine{PRINT\_DXY}{\Real}{2}{0 0}{} \\
% \K{DPLOT\_PART}          = \String{1} & \V{UPPER} \OR\ \V{LOWER} \OR\ \V{FULL} \\
% \K{DPLOT\_STYLE}   = \String{1} & \V{GRAY} \OR\ \V{BLACK} \\
% \K{NUMBER\_DENSITY\_PLOT}  = \Logical{1} & \\
}
\Description   {
This command will do a density plot of the Density array read in by the \\
\C{READ\_DPLOT} command.

   If \K{BAR\_LEGEND} is \V{ON} it will plot a gray scale code to the right of
   the plot.

   \K{BAR\_LEGEND\_PLACES} sets the number of pre- and post-decimal point
   places for the labelling of the bar legend.

   \K{DPLOT\_GRAYNESS} defines the grayness of the smallest and largest
   value to be plotted, respectively. If you want small to be
   white, set the first element larger than the second one.

   \K{DPLOT\_LINE\_TYPE} defines the line type for the mesh plotted on the
   density plot.

   \K{DPLOT\_PART} selects the part of the Density array to be plotted.

   \K{DPLOT\_BOUNDS} sets the real World bounds on the values of the
   Density array corresponding to the \K{DPLOT\_GRAYNESS} interval.

   \K{DPLOT\_STYLE} selects whether the \K{DPLOT\_BOUNDS}
   range is to be colored with
   various degrees of gray (\V{GRAY}), or every cell within the range is to be
   coloured by the first bound of \K{DPLOT\_GRAYNESS} and all other cells by
   the second bound of \K{DPLOT\_GRAYNESS}.

   If \K{NUMBER\_DENSITY\_PLOT} is set to \V{ON} the number is plotted for each
   cell instead of the gray rectangle. This number shows the height of
   the function. You can use the same mechanism as for \V{GRAY} to show only
   numbers in certain range.

   \K{NUMBER\_PLACES} sets the number of spaces before and after the decimal
   point when \K{NUMBER\_DENSITY\_PLOT} = \V{ON}.

   \K{POINT\_FONT} sets the font type for the numbers when
   \K{NUMBER\_DENSITY\_PLOT} = \V{ON}.

   \K{PRINT\_FONT} sets the font type for the numbers for the bar legend.

   \K{PRINT\_DXY} will offset the X and Y of the number printed in each cell
   (in World coordinates).
}




\Command      {CAPTION}{place a caption next to an axis}

\Options{
\OptLine{CAPTION\_POSITION}{\Integer}{1}{1}{} \\
\OptLine{CAPTION\_FONT}{\Integer}{1}{3}{} \\
\OptLine{CAPTION\_TEXT}{\String}{1}{'undefined'}{} \\
\OptLine{CAPTION\_XLEFT}{\Real}{1}{-0.15}{} \\
\OptLine{CAPTION\_XRIGHT}{\Real}{1}{1.07}{} \\
}
\Description  {
This command puts text at pre-specified positions around the plot.

The sequence of \C{CAPTION} commands for the same type of a caption
is important. The captions
will be placed around the graph starting with the position closest to
the graph. Therefore, a subtitle should be done before the title, but the
X-title should be done before the X-subtitle. \K{CAPTION\_XLEFT} is the
X-position in the Plot coordinates of the leftmost part of the
Y-captions (by default -0.15). \C{AXES2D} returns the precise
values for \K{CAPTION\_XLEFT}, so use \C{CAPTION} after \C{AXES2D} without
specifying \K{CAPTION\_XLEFT}. \K{CAPTION\_XRIGHT} is a similar variable
that is used when \K{Y\_SCALE} = \V{RIGHT}.

The following positions with respect to the graph are available:
\begin{description}
\item[1] above graph, centered
\item[2] below graph, centered
\item[3] left of graph, centered,
\item[4] below graph, right
\item[5] left of graph, top
\item[6] right of graph, center
\item[7] right of graph, top
\item[8] left, top corner of graph
\item[9] right, top corner of graph
\item[10] right, bottom corner of graph
\item[11] left, bottom corner of graph
\item[12] center, top of graph
\end{description}
}





\Command      {RESET\_CAPTIONS}{reset caption positioning}
\Commandline  {RESET\_CAPTIONS}
\Description{Resets the positions for the subsequent captions.
             This command has to be executed after the \C{WORLD} and
             before the \C{AXES2D} commands.}




\Command      {LINE2D}{draw a line}

\Options{
\OptLine{LINE2D\_XY1}{\Real}{2}{0.0 0.0}{} \\
\OptLine{LINE2D\_XY2}{\Real}{2}{0.0 0.0}{} \\
\OptLine{LINE2D\_GRAYNESS}{\Real}{1}{0.0}{} \\
\OptLine{LINE2D\_WIDTH}{\Real}{1}{1.0}{} \\
\OptLine{LINE2D\_WIDTH\_SCALING}{\String}{1}{'Y'}{ 'X' \OR\ 'Y'} \\
\OptLine{LINE2D\_LINE\_TYPE}{\Integer}{1}{0}{} \\
}
\Description  {
Plots a line specified in World coordinates. It uses \K{LINE2D\_LINE\_TYPE}
if defined (i.e. in 1..LINTYPS, where LINTYPS is the number of line types
read from file `psgl1.ini'), otherwise it uses \K{LINE2D\_WIDTH} and
\K{LINE\_GRAYNESS}. If \K{LINE2D\_WIDTH\_SCALING} is \V{X}
(case insensitive), the line width is specified in the units of
the X-axis, otherwise in the units of the Y-axis.}



\Command      {SET\_RECORD}{sets RECORD to selected Table elements}

\Options{
\OptLine{ NO\_XY\_SCOLUMNS}{\Integer}{2}{0 0}{} \\
\OptLine{XY\_SCOLUMNS}{\Integer}{0}{}{} \\
 }
\Description  {
This command puts the selected elements in the first line of
the Table data into the \K{RECORD} variable. \K{RECORD} can then
be used in captioning the plot or plots.

This command is useful in combination with the \C{SELECT\_DATA}
command in order to produce many different captions in one set of
plots, from one data file.
}




\Command      {PRINT}{print a text}

\Options{
\OptLine{PRINT\_XY}{\Real}{2}{1.0 1.0}{} \\
\OptLine{PRINT\_DXY}{\Real}{2}{0 0}{} \\
\OptLine{COORDINATES}{\String}{1}{'WORLD'}{ 'WORLD' \OR\ 'PLOT'} \\
\OptLine{PRINT\_FONT}{\Integer}{1}{4}{} \\
\OptLine{PRINT\_ANGLE}{\Real}{1}{0.0}{} \\
\OptLine{PRINT\_HORIZ}{\Integer}{1}{2}{} \\
\OptLine{PRINT\_VERT}{\Integer}{1}{2}{} \\
\OptLine{PRINT\_TEXT}{\String}{1}{'undefined'}{} \\
\OptLine{PRINT\_MODE}{\String}{1}{'XY'}{ XY \OR\ POINT} \\
\OptLine{PRINT\_POINT}{\Integer}{1}{1}{} \\
\OptLine{XY\_COLUMNS}{\Integer}{2}{1 2}{} \\
% \K{PRINT\_MODE}    = \String{1} & \V{POINT} \OR\ \V{XY} \\
}
\Description  {
Prints text positioned in World (\K{COORDINATES} = \V{WORLD}) or
Plot (\K{COORDINATES} = \V{PLOT}) coordinates
at \K{PRINT\_XY} (\K{PRINT\_MODE} = \V{XY}).
Alternatively, if \K{PRINT\_MODE} = \V{POINT}, the coordinates of the point
\K{PRINT\_POINT} in the columns \K{XY\_COLUMNS} are used. If point index
is out of range, the last point is used. In either case, (X,Y) is
translated for \K{PRINT\_DXY}.
\K{PRINT\_ANGLE} is a rotation of the text, \K{PRINT\_HORIZ} is 1 for
left justified, 2 for centered and 3 for right justified, \K{PRINT\_VERT}
is 1 for bottom aligned, 2 for center aligned and 3 for top aligned.

For all text printing, including the one submitted to the \C{CAPTION}
command, the following conventions hold:

\begin{itemize}
\item Superscript: embedded in \_
\item Subscript  : embedded in $\wedge$
\item Greek char : embedded in @
\end{itemize}

Multi-level embedding is allowed.

Special characters can be printed by using the PostScript character codes.
For example, to print the \Ang character, use `\\305'.
}



\Command      {NEW\_PAGE}{start a new page}
\Commandline  {NEW\_PAGE  NO\_COPIES \Integer{1}}
\Description  {Advances to the next page: the next plot will be
               on the new page. It can only be used when Encapsulated
               PostScript (EPSF) is not selected.}





\Command      {ARROW}{draw an arrow}
\Commandline  {ARROW [options] \\
   \begin{tabular}{ll}
    ARROW\_POSITION = \Real{4} & X1 Y1 X2 Y2 \\
    ARROW\_SHAPE  = \Real{3} & tail thickness, arrow width, arrow length \\
   \end{tabular}}
\Description  {
Draws an arrow from (X1,Y1) to (X2,Y2) (tail to tip), in World coordinates
(\K{COORDINATES} = \V{WORLD}) or in Plot coordinates (\K{COORDINATES} =
\V{PLOT}). The elements of \K{ARROW\_SHAPE} are tail thickness, arrow
width, arrow length in Plot coordinates.}




\Command      {POSTSCRIPT}{write a PostScript command}
\Commandline  {POSTSCRIPT POSTSCRIPT\_TEXT = \String{1}}
\Description {
Takes the \K{POSTSCRIPT\_TEXT} string as a literal PostScript command and
writes it to the output PS file.}





\Command      {TRANSFORM}{transform Table or Density array data}

\Options{
\OptLine{TRF\_TYPE}{\String}{1}{'LOGARITHMIC1'}{} \\
\OptLine{TRF\_PARAMETERS}{\Real}{0}{0.0 1.0}{} \\
\OptLine{TRF\_UNDEFINED}{\Real}{1}{-999999}{} \\
}
\Description  {
Transforms the columns of the Table array selected by \K{XY\_SCOLUMNS}
array. If \K{NO\_XY\_SCOLUMNS} are both 0, it transforms the Density array
instead. You must be careful with labelling the ticks (\C{AXES2D}) and
scaling (\C{WORLD}) when using this option since it transforms the data
itself not only plotting of them.

\K{TRF\_PARAMETERS} sets any parameters that may be required for the
transformation.

\K{TRF\_TYPE} selects the type of transformation:

  \begin{description}
    \item[\V{LOGARITHMIC1}:]  $Y = \ln[\mbox{TRF\_PARAM(1)} +
                            (Y-YMIN) \cdot \mbox{TRF\_PARAM(2)}]$

    \item[\V{LOGARITHMIC2}:]  $Y = \ln[\mbox{TRF\_PARAM(1)} +
                            Y \cdot \mbox{TRF\_PARAM(2)}]$

    \item[\V{LOGARITHMIC3}:]  $Y = \mbox{log10}[\mbox{TRF\_PARAM(1)} +
                            (Y-YMIN) \cdot \mbox{TRF\_PARAM(2)}]$

    \item[\V{LOGARITHMIC4}:]  $Y = \mbox{log10}[\mbox{TRF\_PARAM(1)} +
                            Y \cdot \mbox{TRF\_PARAM(2)}]$

    \item[\V{CUMULATIVE}:]  $Y_i = \sum_{k=1,i} Y_k$

    \item[\V{LINEAR}:]  $Y = \mbox{TRF\_PARAM(1)} +
                            Y \cdot \mbox{TRF\_PARAM(2)}$

    \item[\V{INVERSE}:]  $Y = \mbox{TRF\_PARAM(1)} +
                              \mbox{TRF\_PARAM(2) / Y}$

    \item[\V{EXPONENTIAL}:]  $Y = \mbox{TRF\_PARAM(1)} +
                              \exp[\mbox{TRF\_PARAM(2)} + \mbox{TRF\_PARAM(3)}]$

    \item[\V{NORMALIZE}:]  $Y = Y / \sum_i Y_i$
   \end{description}

    YMIN is the smallest value in all selected columns of the
    Table array or the smallest value in the Density array,
    as appropriate. \V{CUMULATIVE} is not available for
    transformation of the Density array.

    Any transformation that is undefined (for example, a logarithm
    of a non-positive argument, or a division by zero) is assigned
    a value \K{TRF\_UNDEFINED}.
}




\Command      {RESET}{reset \TOP}
\Commandline  {RESET}
\Description{
Reads in the {\tt top.ini} file again. Resets all parameters to its default
values. Use \C{RESET} before plotting the second, third, \etc\ plot in the
same \TOP\ program to prevent surprises resulting from the non-default
values of arguments such as \K{X\_TICK}, \K{XY\_COLUMN}, \etc\ which
were possibly set automatically when producing the first plot.}





\Command      {GET\_BARS}{calculate histogram bars}

\Options{
\OptLine{BAR\_DX}{\Real}{1}{1.0}{} \\
\OptLine{WORLD\_WINDOW}{\Real}{4}{-999. -999. -999. -999.}{} \\
\OptLine{XY\_COLUMNS}{\Integer}{2}{1 2}{} \\
% \K{WORLD\_WINDOW}    = \Real{4} & XMIN YMIN XMAX YMAX \\
}
\Description   {
Transforms the current X vector into a histogram by counting how many
X coordinates fall in a certain interval. The interval size must be
specified explicitly by the real World range \K{BAR\_DX}. The centers
of these intervals
are returned in X and the heights of the bars in Y.  Note that the
current data in the Table array is erased, histogram coordinates
are copied to the current X and Y.
Only XMIN and XMAX are used to determine the X-range. If any of
these two is undefined (-999) default values are supplied as the
largest and smallest X in the data with an added DX on both sides.
XMAX is corrected so that XMAX = XMIN + (N+1)*BAR\_DX where N is the
number of points (bars) in the new Table array. The first bin starts
at XMIN+0.5*DX and the last bin ends at XMAX-0.5*DX. For example,
if you have points with X-coordinates ranging from 0 to 100, you could
set \K{WORLD\_WINDOW} to -5 0 105 0 and \K{BAR\_DX} to 10, which
will create bins 0--9.999, 10--19.999, ..., 90--100.0; they will
be centered on 5, 15, 25, etc. There will also be half of the bin
width on each side of the histograms when it is plotted (from $-5$
to 105 on the X-axis).

\K{XY\_COLUMNS} selects the X and Y columns. If Y column exists before
the call, this routine also calculates the average and standard deviaton
of the Y-values in each bin. These are returned in the two columns
after the currently existing columns.}




\Command      {GET\_DENSITY}{calculate Density plot data}

\Options{
\OptLine{BAR\_DX}{\Real}{1}{1.0}{} \\
\OptLine{BAR\_DY}{\Real}{1}{1}{} \\
\OptLine{WORLD\_WINDOW}{\Real}{4}{-999. -999. -999. -999.}{} \\
\OptLine{XY\_COLUMNS}{\Integer}{2}{1 2}{} \\
%\K{WORLD\_WINDOW}      = \Real{4} & XMIN YMIN XMAX YMAX \\
}
\Description{
Transforms the current X and Y vectors into a density plot (3D histogram)
by counting how many X and Y coordinates fall in a certain interval. The
interval sizes must be specified explicitly by the real parameters
\K{BAR\_DX} and
\K{BAR\_DY}. The heights of the density plot are returned in the Density array.
All four values in \K{WORLD\_WINDOW} are used to determine the X-range.
If any of them is undefined (-999) default values are supplied as the
largest and smallest X and Y in the data with an added DX/DY on all sides.
This makes the WORLD exactly superposable to the world from the 1 .. NBARX,
1..NBARY density plot. This world goes from 0,0 to NBARX+1,NBARY+1. The
center of the first bin is at XMIN+DX,YMIN+DY and the center of the last
bin is at XMAX-DX,YMAX-DY. This gives a 0.5*DX, 0.5*DY margin around
the plotted bins.
XMAX (and YMAX) is corrected so that XMAX = XMIN + (N+1)*BAR\_DX where
N is the number of points (bars) in the new Density array.
\K{XY\_COLUMNS} selects the X and Y columns.
}



\Command      {SHUFFLE\_DPLOT}{re-organize the Density plot data}

\Options{
\OptLine{SHUFFLE\_OPERATION}{\String}{1}{'TRANSPOSE'}{ REVERT\_X, REVERT\_Y} \\
% \K{SHUFFLE\_OPERATION}  = \String{1} & TRANSPOSE \OR\ REVERT\_X \OR\
%                                      REVERT\_Y \\
}
\Description{
The transpose operation only has sense for square matrices. The other
two commands invert the order of the points along the X and Y coordinates,
respectively. To exchange the orientation of the X and Y axes as they
appear on the plot, you should use the \K{DPLOT\_ORIENTATION} option
of the \C{READ\_DPLOT} command.}




\Command      {DENSITY\_TO\_XY}{Density to XY data}
\Commandline  {DENSITY\_TO\_XY \\
}
\Description{
Copies the current density array to the XY table.
}



\Command      {XY\_TO\_DENSITY}{XY to density data}
\Commandline  {XY\_TO\_DENSITY \\
}
\Description{
Copies the current XY table to the density array.
}



\Command      {LEGEND}{draw a legend}

\Options{
\OptLine{SYMBOL}{\String}{1}{'LINE'}{ LINE \OR\ POINT \OR\ BAR} \\
\OptLine{PLOT2D\_LINE\_TYPE}{\Integer}{1}{1}{} \\
\OptLine{PLOT2D\_SYMBOL\_TYPE}{\Integer}{1}{0}{} \\
\OptLine{BAR\_LINE\_TYPE}{\Integer}{1}{2}{} \\
\OptLine{BAR\_GRAYNESS}{\Real}{0}{0.7}{} \\
\OptLine{}{\String}{1}{'description'}{DESCRIPTION} \\
\OptLine{DESCRIPTION\_FONT}{\Integer}{1}{5}{} \\
% \K{SYMBOL}   = \String{1} & \V{LINE}  \OR\  \V{POINT}  \OR\  \V{BAR}    \\
}
\Description{
Plots the legend for objects (curves, points, and bars) at the right
side of the graph. The legend is in the form 'symbol symbol\_description'.
Successive \C{LEGEND} commands print legends one per line, starting at the
top. \C{RESET\_LEGEND} has to be issued before \C{LEGEND}. Note that you can
use this command to place text right to the plot if you specify
invisible object types (0). The value of the \K{SYMBOL}
keyword determines the type of the object symbol in the legend.
\K{DESCRIPTION} is the text describing the symbol.}




\Command      {RESET\_LEGEND}{reset legend positioning}
\Commandline  {RESET\_LEGEND}
\Description  {Resets the starting Y position of the next legend
               to the initial value at the top of the plot.}





\Command      {PLOT\_ERROR\_BARS}{draw error bars}

\Options{
\OptLine{XY\_COLUMNS}{\Integer}{2}{1 2}{} \\
\OptLine{ERROR\_COLUMN}{\Integer}{1}{0}{} \\
