121.latex

\documentstyle{report}


\textwidth=5.5in
\textheight=8.5in
\oddsidemargin=0mm
\evensidemargin=0mm
\parindent=0mm
\parskip=5mm
% \headsep=10mm
% \headheight=4mm
% \topmargin=-10mm
\raggedbottom
\itemindent=1in

\pagestyle{headings}

\begin{document}

% User Interfaces:
%  march-92 initial writeup for prototype report 	pjt

\chapter{User Interface}

During the prototype stage a basic command line user interface was
build, with which tasks have been constructed.  Some work was spend
in showing that both the AIPS interpreter and the Graphical User Interface
(GUI) are plug-in compatible user interfaces.  For example, a functional
GUI for Khoros\footnote{(c) University of New Mexico} is available for
demo purposes.  The AIPS shell interpreter can be thought of in terms of
the Miriad\footnote{(c) BIMA} shell interpreter. 


\section{Astronomers vs.  Programmers}

The basic (command line) user interface is a series of ``{\it
keyword=value}'' pairs, which we call {\bf program
parameters}\footnote{The name {\bf parameter} and {\bf keyword} are
sometimes used both}. 

The {\tt class Param} (see {\tt Param.h}) implements one single such
{\bf parameter}.  In addition to a name and a value, a parameter has a
variety of other attributes, such as a one-line help string (useful when
being prompted etc.), a type, a range and optional units.  All of these
are character strings; parsing and error checking is done at a different
level.  The programmer however will never interact with a parameter
through it's class interface.  This is done with the {\tt class Input},
which is some kind of container of {\tt Param}'s, with a variety of user
interface attributes (help-level, message/debug-level etc). 

Although the programmer must supply the user interface with a number of
predefined {\bf program parameters}, the user interface itself will
create a small number of {\bf system parameters} (help=, debug=).  The
purpose of these is to tell the task how to communicate with the user
and it's environment, and give the user control over these items.  For
example, the user may want to be prompted, with error recovery, and see 
(debug) messages above a certain threshold level. 

For the benefit of the Programmer, the user interface also defines a
number of standard parameters (``templates''), which can be copied and
bound to a program parameter.

Parameter names are to be found by minimum match, if so requested
by the user.

Most programs are probably happy with a simple set of parameters,
like a linear list. We have discussed hierarchical keywords
and in Section~\ref{s:hier} a few thoughts are expressed.

All input as well as output is controlled by the user interface. The
Astronomer has a varying degree of control over how and where
input and output occurs. In the command line interface 
system control occurs through a small number of system parameters, which
can be preset by environment variables, supplied as if they were
parameters on the command line, or both.

For example, a interactive UNIX shell session may look like:

\begin{verbatim}
    1% setenv DEBUG 1
    2% setenv HELP prompt,aipsenv
    3% program key1=val1 key3=val3
    4% program val1 val2 key4=val4 key5=val5 debug=0
    5% unsetenv HELP DEBUG
    6% program help=pane > prog.pane
\end{verbatim}

After having preset the DEBUG and HELP modes in commands {\tt 1\%} and
{\tt 2\%}, commands {\tt 3\%} and {\tt 4\%} will act accordingly: the
user is prompted, and parameter default values are restored and saved
from an AIPS environment file before and after invocation.  In addition,
in command {\tt 4\%} the user decided not to see any messages.  Command
{\tt 6\%} gives an example of the self-describing mode of programs,
where a pane description file for Khoros has been constructed. 

\newpage

\section{Programmers: Where is my {\tt main}?}

No, we don't want you to use {\tt main(int argc, char **argv)} anywhere
in your code.  Instead, use {\tt aips\_input()}, {\tt aips\_main()} and
{\tt aips\_output()}. 

\noindent
To summary, your section of code could then look something like:

\footnotesize\begin{verbatim}
    //aips++
    //  Hypothetical Silly Interactive Contour Plotter 
    // 
    
    #include <Main.h>       		// Standard declarations needed for an AIPS++ main program
    #include <SillyImage.h>

   aips_input(Input &inputs)		// Definition of the allowed Program Parameters
    {
      inputs.Version("19-mar-92 PJT");
      inputs.Usage("Hypothetical Silly Interactive Contour Plotter");

      inputs.Create(              "in",      "",      "Input file",        "InFile",  "r!");
      inputs.Create(              "levels",  "",      "Contour levels",    "RealArray");
      inputs.StdCreate("lstyle",  "lstyle",  "solid", "My Contour line type");
      inputs.StdCreate("lwidth");
      inputs.Create(              "annotate","full",  "What annotation?",  "String",  "full|brief|none|publication");
      inputs.StdCreate("device");
    }

    aips_main(Input &inputs)		// Computation box - this could be spawned to various machines
    {
        String    dname     = inputs.GetString("device");
        Device device(dname);

        do {

            File      f         = inputs.GetFile("in");
            RealArray contours  = inputs.GetRealArray("levels");
            String    lstyle    = inputs.GetString("lstyle");
            Int       lwidth    = inputs.GetInt("lwidth");

            contours.Sort();       // Make sure this array is sorted

            if(contours.Count() > 20) cwarning << "A lot of contours buddy\n"
            if(countour.Count() == 0) break;
                
            cdebug.Level(1);
            cdebug << "Plotting " << contours.count() << " contours\n"
                   << Level(2) << contours << "\n";
 
            SillyImageContour(f.name(),contours.Count(),contours.Value(),
                              lstyle, lwidth, dname);

        } while (inputs.More());

        device.Close();
    }
\end{verbatim}\normalsize

\newpage
Comments:

\begin{itemize}
\item
In {\tt aips\_input}, the {\bf program parameters} are defined through
the {\tt Create} member function.  In addition, a {\tt Version} and {\tt
Usage} string should be supplied to the user interface. 


\item

The {\tt aips\_input} routine could be automatally made by a code
generator from a description section encoded in the source code of the
program itself, much like Mark Calabretta`s proposal discussed last
fall.  The advantage of this is that we can generate more elaborate
online context and level dependant help.  It should not be too hard to
create readable documents in page description languages like man, latex
or texinfo.  The Andrew Toolkit, which has been considered too, is a
different story. 

\item

A number of standard {\tt ostream}'s ({\tt cwarning}, {\tt cerror} and
{\tt cdebug}) are to be provided for\footnote{Not present in this
prototype}, acting much like {\tt cerr}; they handle warning messages,
fatal error messages and a (Astronomer controlable message level) debug
output.  After a fatal error the program will exit gracefully.  A
specified number of fatal errors can be overridden by a system parameter
(error=).  The Programmer can also define a cleanup function, say {\tt
aips\_cleanup}, which is called before the program really quits.  Even a
recover function could be supplied with which Programmers can recover
from a known localized fatal error. 

\item
Alternatively, variable argument ({\tt <stdarg.h>}) versions of
the above output could be made available under the names {\tt error},
{\tt warning} and {\tt debug}:

\begin{verbatim}
    #include <stdarg.h>

    void error(char *fmt ...);
    void warning(char *fmt ...);
    void debug(int level, char *fmt ...);
\end{verbatim}

\item
The {\tt aips\_main} function acts as a replacement for where C/C++ programmers
commonly define their {\tt main}. A true {\tt main(int argc, char **argv)} is
present in the AIPS library (See {\tt Main.C}), and gets automatically linked in
when you \verb+#include <Main.h>+. 

\item
An {\tt Output} object has not been defined yet. 

\item

\end{itemize}


\newpage
\section{Heirarchical parameters}
\label{s:hier}

A hierarchical parameter would be set using the format

\begin{verbatim}
        key.class1.class2.class3=value
\end{verbatim}

(e.g.  ``{\it xaxis.grid.style=dotted}'') we will use a notation where the 
hierarchical level is given by a the appropriate number of dots
that the keyname starts with. To start with an example, a somewhat
elaborate program which would clearly benefit from hierarchical
keywords

\footnotesize\begin{verbatim}
    <Key>           <StdKey>        <Type>      <Range>
    ====            ========        ======      =======

    in              infile          InFile      r|w|w!|rw|.....
    .region         xyzselect       String
    contour                         bool        t|f
    .levels                         RealArray   sort($0,$N)
    .style          lstyle          String      solid|dotted|dashed|....
    .thickness      lwidth          int         0:5
    .color          color           String      cyan|red|green|0x134|....
    greyscale                       bool        t|f
    .minmax                         Real[2]     $1<$2
    .gamma                          Real        >=0
    .invert                         bool        t|f
    .colormap       colormap        InFile      bw|rainbow|..
    xaxis
    .ticks                          Real[2]     
    .grid                           Real
    ..style         lstyle
    ..thickness     lwidth
    .label                          String
    ..font          font            InFile      (calcomp|helvetica|roman)(10,12,15,20)
    yaxis
    .ticks                          Real[2]     
    .grid                           Real
    ..style         lstyle
    ..thickness     lwidth
    .label                          String
    ..font          font            InFile      (helvetica|roman)(10,12,15,20)
    annotate                        String      none|brief|full|publication

\end{verbatim}\normalsize





Comments/Problems:

\begin{itemize}

\item
The order in which keywords are ``created''\footnote{See 
{\tt Input::Create()}} is still important, not only
to properly define their hierarchy, but foremost to allow shortcuts with
nameless specification of parameters on the command line. E.g.
``{\tt ccdplot ngc1365u 'box(10,10,20,20)' t 10:20:2 grey=t ann=full}''
would be interpreted as {\tt in=ngc1565u} etc. Obviously
once a parameter was named, all subsequent ones need to be too
(assuming the command line is parsed left to right).	

\item 

{\tt Range} must contain a boolean expression, where \verb+$0+ is the
name of an array, \verb+$N+ the number of elements, \verb+$1+,
\verb+$2+, \verb+$3+, ...  \verb+$($N)+ the array elements, \verb+&+ and
\verb+|+ the boolean operators, \verb+:+ to denote an implied do-loop
(with optional second \verb+:+ followed by the stride). A fairly
rich syntax will be made available.


\item 

{\tt File} could be the same as a {\tt String} but 
could also be usefull class (InFile and OutFile) in itself,
with name, file pointer? and appropriate wildcard expansion of
the string into the full filename.

\item 

{\tt xaxis,yaxis}: these two keywords are clearly related.  In prompt
mode it would be annoying if the Astronomer sat through the whole {\tt
xaxis} family, and then wants to do the {\tt yaxis} tree with the
defaults now inherited from the {\tt xaxis} tree.  (perhaps only the
label name would be different (though the most appropriate default would
be the one from the image header, if available).  The programmer must
leave the defaults in {\tt yaxis} blank, and take the {\tt xaxis}
equivalent if none supplied in the {\tt yaxis} equivalent. 


\end{itemize}


\section{Terminology/Glossary}

\begin{itemize}

\item[{\bf program}]
Executable within the Unix environment, that has
the AIPS user interface.

\item[{\bf task}]
-- same as above?

\item[{\bf parameter}]
Has a name, value, help and all that other good stuff. They come
as {\bf program parameters} and {\bf system parameters}, though
a third kind, the {\bf standard parameters}\footnote{The name
{\bf template parameters} is perhaps more appropriate, but 
confusing in the C++ environment} are internally defined by
the user interface. Programmers can bind {\bf standard
parameters} to {\tt program parameters} at compile time.

\item[{\bf keyword}]
The name of a parameter.

\item[{\bf default}]
The value of a parameter as defined by {\tt aips\_input},
though possibly overriden by previous settings of the
Astronomer if the user interface was told to
(aipsenv file, commandline)

\end{itemize}


%     ==================================================================

\section{KHOROS User Interface}

A small excersize to let Khoros talk to a simple user interface is
presented here.  The essential information needed by Khoros to 
run 'foreign' programs, is a User Interface Specification (UIS),
also referred to as a {\bf pane} file (each basic program in Khoros
typically comes with a {\tt program.pane} file).

Since an AIPS++ task is self-describing and can supply the caller with
internal information about it's knowledge of keywords, it is relatively
straightforward to automate this process and have each program
create a {\tt pane} file from itself.

For example,

\begin{verbatim}
    program help=pane > program.pane
\end{verbatim}

where the {\tt program.pane} could be something like:

\begin{verbatim}
-F 4.2 1 0 170x7+10+20 +35+1 'CANTATA for KHOROS' cantata
 -M 1 0 100x40+10+20 +23+1 'An AIPS++ program' aips++
  -P 1 0 80x38+22+2 +0+0 'View an image' view
  -I 1 0 0 1 0 1 50x1+2+2 +0+0 '???' 'in' 'Input Image' in
  -H 1 13x2+1+4 'Help' 'Help for view' aips.help
  -R 1 0 1 13x2+39+4 'Run' 'RunMe' khoros2aips view
  -E
 -E
-E
\end{verbatim}

Currently most parameters are string parameters, except input and
output files, which need to be labeled as such in the creation
phase. 

Comments/Problems:

\begin{itemize}

\item

Array or composity parameters can only be implemented as strings, 
since Khoros cannot handle those (as far as I can see at this moment).

\item

Khoros does not allow for mixed (structured) keywords, unless
structured via their mutually exclusive or inclusive 
tags.


\item

Though AIPS programs lend themselves to the dataflow based model,
they may not like their existing files to be overwritten.
By default, interconnecting Khoros programs output with
another input creates a temporary (assumed re-usable) filename.
It is up to the user to define a fixed name. This turned out to
be very laborious and annoying for the user. The user can also
decide to use shared memory or sockets, in which case this
difference disappears. This will cause problems 
if datasets are implemented as directories (e.g. Miriad).

\item

Programs that are sending output to {\it stdout} or {\it stderr}, or for
that matter, reading from {\it stdin} will get stuck.  If one sticks to
the load-and-go principle, like AIPS programs normally are,
there is no problem with input.  Output is another story.  The {\it
stdout} goes to the screen (whichever cantata was started up from), and
{\it stderr} will appear in the error window that the glyph will pop up. 

\item

The pane/subform files should be organized in the KHOROS tree,
{\tt \$KHOROS\_HOME/<toolbox>/repos/cantata/}

\item 

The on-line documentation (referenced by the -H line on a pane file) comes
in two options: single file and directory. If the name, referenced
on the -H help line, is a directory, within that directory there can
be several files which will be displayed.  Khoros/Cantata comes with a
program {\tt formatdoc}, which converts an nroff-like document in the
format that this help system wants (more or less ascii).

\end{itemize}

\section{The KHOROS demo}

\begin{verbatim}
    cd /home/saturn/pteuben/bima
    demo
\end{verbatim}

This will start up {\tt cantata}, with the demo predefined for you. The
setup was saved in a file called {\tt demo.workspace.Z}.

You can also manually load in new programs as follows:
\begin{itemize}
\item
pull down the {\tt Workspace} menu, and 
select the {\tt File Utilities} option. 

\item 
Fill in the name of the relevant pane file 
in the {\tt UIS Filename} entry and hit RETURN to import them into
cantata's drawing space: drag the cursor
into the drawing space of {\tt cantata} to ``drop'' the glyph.
The demo incoorporates pane files for the
following programs: {\tt observe.pane, calib.pane, invert.pane},
{\tt clean.pane} and {\tt view.pane}. 

\end{itemize}


Some comments:

\begin{itemize}
\item

programs are represented by a glyph, the white rectangles, with on the
top a red (bomb), blue (form) and green (on/off) button.  They represent
a Quit, Edit and Run functionality.  Typically a user selects the
programs to run, opens a glyph by clicking on the middle/ blue (form)
button, and fills out the necessary parameters. 

\item

Input file's parameters inside the pane (visible after you've clicked on
the blue button) come with a file browser to easy filename insertion. 

\item

Parameters can use the program default by unsetting the option button. 
It normally comes as a filled black square, meaning the entered value
will be the one used by the program. 

\item

dataflow lines (the green lines) can be created by first clicking on an
{\bf out} (OutFile) arrow, followed by an {\bf in} (InFile) arrow.  An
OutFile can be split (i.e.  goto various InFile's), but of course one
cannot merge various OutFile's into one InFile.  Any previous
connections would then be broken. 

\item 

dataflow lines can be files (default), sockets or shared memory. 
Intermediate results are typically lost, after you exit from Khoros,
though can always be stored into a file at demand.  Click the mouse
while pointing at a dataflow line, and you'll see what they mean with
this. 

\item
With the RESET button (on the left) you can force the flow to
be run all the way through for the next RUN. Ne sure all required
inputs and outputs are connected, otherwise the flow will be
interrupted. An inactive in/out can be recognized as a grey arrow,
as opposed to a black arrow, inside the yellow rectangles.

\item
Saving a workspace can be done within the 
WORKSPACE/File Utilities menu option. The default demo is in
{\tt demo.workspace.Z}.

\end{itemize}


\chapter{documentation}

\section{hypertext}

Available systems, mostly public domain:


\begin{itemize}

\item

texinfo; various programs available are

\begin{itemize}
\item 
info: screen (curses) based

\item
xinfo: x-windows based

\item
ivinfo: interviews based

\item
info.el: emacs based

\item
hyperbole (but see also below) - epoch / emacs.

\item 
hyperman

\end{itemize}

\item

xman: 

\item

hman: needs Motif1.1.2

\item

hyperbole

\end{itemize}



%===========================================================================

%===========================================================================

\end{document}