%-----------------------------------------------------------------------
%;  Copyright (C) 1995
%;  Associated Universities, Inc. Washington DC, USA.
%;
%;  This program is free software; you can redistribute it and/or
%;  modify it under the terms of the GNU General Public License as
%;  published by the Free Software Foundation; either version 2 of
%;  the License, or (at your option) any later version.
%;
%;  This program is distributed in the hope that it will be useful,
%;  but WITHOUT ANY WARRANTY; without even the implied warranty of
%;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%;  GNU General Public License for more details.
%;
%;  You should have received a copy of the GNU General Public
%;  License along with this program; if not, write to the Free
%;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
%;  MA 02139, USA.
%;
%;  Correspondence concerning AIPS should be addressed as follows:
%;          Internet email: aipsmail@nrao.edu.
%;          Postal address: AIPS Project Office
%;                          National Radio Astronomy Observatory
%;                          520 Edgemont Road
%;                          Charlottesville, VA 22903-2475 USA
%-----------------------------------------------------------------------
\documentstyle [twoside]{article}
\newcommand{\memnum}{88a}
\newcommand{\whatmem}{\AIPS\ Memo \memnum}
%\newcommand{\whatmem}{{\bf D R A F T}}
\newcommand{\memtita}{A User's Introduction to}
\newcommand{\memtit}{The \AIPS\ Gripes Database}
\newcommand{\Memtita}{Gripes Database User's Guide}
\newcommand{\thedate}{20 February 1992}
\date{\thedate}

%
%
\newcommand{\AIPS}{{$\cal AIPS\/$}}
\newcommand{\POPS}{{$\cal POPS\/$}}
\newcommand{\eg}{{\it e.g.},}
\newcommand{\ie}{{\it i.e.},}
\newcommand{\daemon}{d\ae mon}
\newcommand{\boxit}[3]{\vbox{\hrule height#1\hbox{\vrule width#1\kern#2%
\vbox{\kern#2{#3}\kern#2}\kern#2\vrule width#1}\hrule height#1}}
%
\title{
%   \hphantom{Hello World} \\
   \vskip -35pt
   \fbox{{\large\whatmem}} \\
   \vskip 28pt
   \memtita \\
   \vskip 10pt
   \memtit}
\newcommand{\theauthor}{W. D. Cotton, Dean Schlemmer}
\newcommand{\thethanks}{\TeX set and updated to 1994 by Eric W.
              Greisen.}
\author{\theauthor\thanks{\thethanks}}
%
\parskip 4mm
\linewidth 6.5in
\textwidth 6.5in                     % text width excluding margin
\textheight 8.81 in
\marginparsep 0in
\oddsidemargin .25in                 % EWG from -.25
\evensidemargin -.25in
\topmargin -.5in
\headsep 0.25in
\headheight 0.25in
\parindent 0in
\newcommand{\normalstyle}{\baselineskip 4mm \parskip 2mm \normalsize}
\newcommand{\tablestyle}{\baselineskip 2mm \parskip 1mm \small }
%
%
\begin{document}

\pagestyle{myheadings}
\thispagestyle{empty}

\newcommand{\Rheading}{\whatmem \hfill \Memtita \hfill Page~~}
\newcommand{\Lheading}{~~Page \hfill \Memtita \hfill \whatmem}
\markboth{\Lheading}{\Rheading}
%
%

\vskip -.5cm
\pretolerance 10000
\listparindent 0cm
\labelsep 0cm
%
%

\vskip -30pt
\maketitle
%\vskip -30pt
\normalstyle

\begin{abstract}
The \AIPS\ Gripes database is an {\tt emacs}-based tool for
maintaining all of the many user complaints and suggestions received
by the project over its lifetime.  The present document is an in-depth
introduction to the use of this tool.  It does not address how the
tool was constructed, nor does it address the contents of the gripes.
\end{abstract}

%\renewcommand{\topfraction}{0.85}
\renewcommand{\floatpagefraction}{0.75}
%\addtocounter{topnumber}{1}
\typeout{bottomnumber = \arabic{bottomnumber} \bottomfraction}
\typeout{topnumber = \arabic{topnumber} \topfraction}
\typeout{totalnumber = \arabic{totalnumber} \textfraction\ \floatpagefraction}


\section{Introduction}

The \AIPS\ Gripes Database is built within the {\tt emacs} editor. It
is mentioned throughout this document that many of the editor's
functions and key-bindings apply when moving through and editing forms
within the database.  Although it is {\it not} essential, it is
recommended that you familiarize yourself somewhat with {\tt emacs}
before starting. Throughout this document you will encounter some
keystroke shorthand. Some basic definitions are: {\tt \^{ } = CTRL =
Control} key, {\tt ESC = Escape} key, and {\tt SPC = Space} bar. If
you see something like {\tt \^{ }}{\it x}, this requires that you to hold
down the {\tt Control} key and hit the ``{\it x}'' key at the same
time.

The database formerly resided on {\tt baboon}, a Sun Unix-based Sparc
station in Charlottesville.  It now resides on {\tt zia} a Solbourne
workstation server at the Array Operations Center in Socorro.  If you
would like to use the database, you need only log onto virtual machine
``{\tt gripe}.''  If you are using an NRAO Unix machine, simply enter
{\tt rlogin zia -l gripe} at the Unix prompt. If you are logging in
from outside NRAO, the complete rlogin address is {\tt
gripe.aoc.nrao.edu}.  If for any reason this does not work, try to
telnet to {\tt gripe} with the command {\tt telnet 146.88.1.4}.  No
username or password is necessary for any of these logins. The {\tt
viewgripe} procedure should start automatically and, when you exit the
database, you should be logged out and returned to your own system.

After the viewgripe procedure finishes its initialization, the top
level form of the database (the Selection/Options Form) should appear
on your screen.  Within this form you will specify the criteria by
which a particular gripe or group of gripes will be selected.

\section{Entering data and {\tt emacs} functions}

Many of the basic {\tt emacs} functions will work when you are
entering/editing data in the Selection/Options Form (as well as
subsequent forms).  ``Arrow keys,'' if available, should work to move
the cursor from character to character and line to line.  Some of the
other basic {\tt emacs} functions are:
\begin{center}
\begin{tabular}{rl}
{\tt \^{ }f}    & move forward one character \\
{\tt \^{ }b}    & move backward one character \\
{\tt ESC-f}  & move forward one word \\
{\tt ESC-b}  & move backward one word \\
{\tt \^{ }p}    & move up one line \\
{\tt \^{ }n}    & move down one line \\
{\tt \^{ }a}    & move to the beginning of the line \\
{\tt \^{ }e}    & move to the end of the line \\
{\tt DEL}    & delete the character to  the left of the cursor \\
{\tt \^{ }d}    & delete the character which the cursor is on \\
{\tt ESC-d}  & delete one word to the right of the cursor \\
{\tt \^{ }s}    & search forward for a specified string \\
{\tt \^{ }r}    & search backward for a specified string \\
{\tt SPC}    & space one character \\
{\tt RET}    & completion of form --- select gripes \\
{\tt \^{ }x\^{ }c} & exit the database \\
{\tt \^{ }g}    & stop some action by the program
\end{tabular}
\end{center}

Many more functions are available and are defined within the various
help screens found throughout the database (typically activated by
entering `` {\tt ?},'' as you may notice in the menu line at the
bottom of the screen).  However, depending on your location in the
database, some {\tt emacs} functions (including some from the list
above) may be disabled.  For instance, no editing is allowed while you
are viewing a {\tt [read-only]} buffer of an individual gripe.

If you are at a prompt in the Selections/Options form which requires a
fixed choice of entry (\ie\ {\tt Status}, {\tt Display}, etc.),
hitting the {\tt SPC} bar will show the possible entries.  There is
also the usual {\tt emacs} completion function which will allow you to
use the space bar to complete a string in such fields as long as a
minimum number of characters has been entered to make the string
unique.  If there are several options for string completion, you will
also be told the list of possibilities in a separate window.  If there
is ever any difficulty exiting/removing a second window, the sequence
{\tt \^{ }x-1} ({\tt CTRL-x} and then the one key) should clear it.  If
there is not a preset list of options for an entry, entering a blank
will simply insert a blank into the form.  Note, blanks are not the
same as no entry (all underscores).

\section{The \AIPS\ gripes selections/options form}

The initial value of the Selection/Options form appears in
Figure~\ref{fig:SelOpt}.
\begin{figure}
\begin{center}
\begin{verbatim}
                    AIPS Gripes Selection/options

 Selection criteria
     User (Joe Blow)               ______________________________
     Status (new, answer)          new________
     Keyword (MX, DBCON, tape)     _______________
     Beginning date (dd-mmm-yyyy)  01-Jan-93__
     Beginning Gripe no. (3456)    4900_
     Arbitrary string in a gripe   ___________________________________

 Options
     Display (index, full, exit)   index__
     E-Mail address (jblow@esu.edu)___________________________________
\end{verbatim}
\end{center}
\caption{Selection/Options form}
\label{fig:SelOpt}
\end{figure}

\subsection{Retrieving gripes: selection criteria}

The first step to retrieving gripes is to fill in the Selection
Criteria section of the Selection/Options Form. Obviously, the more
specific and complete the selection criteria are, the more likely you
are to obtain a smaller group of gripes.  At least one of the
selection criteria: User, Status, Keyword, or Arbitrary string must be
set.  Be careful not to hit the {\tt RETURN} key until the {\it
entire} form is complete to your satisfaction. You do not need to fill
the form in completely, but with fewer qualifiers, more gripes are
likely to be selected. This could make locating a particular gripe
more time consuming. If you wish to kill the retrieve process at any
time during its execution, type \^{ }g and you will be returned to the
Selection/Options form.

Take care when entering the values in the Selection/Options screen.
Although string searches are not case sensitive, they {\tt are}
sensitive to spelling and syntax.  In other words, the spelling of
your entries for {\tt User}, {\tt Keyword}, and {\tt Arbitrary String
in a Gripe} needs to be entered {\it exactly} as they appear in the
gripes themselves.  If a ``griper'' used an abbreviation or nickname
when they entered a gripe, then you need to enter their name as such.
If there are multiple spellings of their name in the database, only
those gripes matching your entries will be pulled. (For the {\tt
Status} and {\tt Display} options entries, however, there is a
minimum-match entry capability.)  Initials are completely ignored at
this time, so it is unnecessary to enter them.

The selection criteria are discussed individually below.

{\tt User}: is the name of the person entering the gripe.  Initials
are ignored, but the name must otherwise match the name signed to the
gripe.  There are no predefined values for this field and if left
empty (all underscores) gripes entered by all users will be accepted.

{\tt Status}: is assigned to each gripe to indicate the amount of
processing that it has received inside the \AIPS\ gripes system. If
you are entering a gripe {\tt Status}, there are four possible options
from which to choose for gripes entered under this new database
system: {\tt new} gripes have no answer at all, {\tt answer-new}
gripes have been answered but the answers have not been sent to the
persons who wrote them, {\tt answer-sent} gripes have been answered
{\it and} sent, and finally {\tt answer} gripes are {\it all} gripes
which have been answered, whether they have been sent or not.

In addition to the statuses just mentioned, answered gripes prior to
about number 4563 (those entered before about the second week of
November, 1990) may also be marked simply as {\tt answered}. These
will have already been sent to the users, but you must keep this
difference in mind when selecting a group of gripes which may include
some entered before {\tt and} after the transition to the current
database system. Thus, it may be necessary to run your query twice ---
once for each ``epoch'' of entries.

Note that if {\tt Status} is not entered (left all underscores),
gripes with {\it any} status will be accepted.

{\tt Keyword}: is the classification or classifications assigned to
most gripes.  This is frequently the name of the task or verb involved
but may include other items.  If {\tt keyword} is not entered (left
all underscores), gripes with any keyword will be accepted.

{\tt Beginning date}: is a date entered in the form dd-mmm-yy (\eg\
01-Jan-90) to select only gripes entered after the given date.  If
no date is entered, gripes with any entry date are accepted.

{\tt Beginning Gripe no.}: sets the lowest gripe number which will be
selected.  Each Gripe is given a unique number more-or-less in the
order they were entered.  Selection by gripe number is faster than
selection by date.  If no gripe number is entered then any gripe
number is accepted.

{\tt Arbitrary string in a gripe}: allows selection by the presence of
an arbitrary string of up to 35 characters within the gripe.  One
letter ``words'' and numbers are ignored.  The target string can be
anywhere in a gripe file, \eg\ this is useful if you don't know a
user's first name.

\subsection{Retrieving gripes: display options}

Once you are satisfied that the Selection Criteria section of the
Selection/Options form is complete, enter the Display Option(s) by
which you wish to view data on the gripe(s).  As is explained in the
help screen, you may:
\begin{description}
\item[(a) ] Enter {\tt index} to view a simple index of the selected
                 gripes,
\item[(b) ] Enter {\tt full} to skip the index and view a ``slide
                 show'' showing the full text of {\it all} selected
                 gripes,
\item[(c) ] Enter {\tt print} to either print the selected gripes on
                 the NRAO laser printer or write the output to a file
                 ({\tt /tmp/gripestoprint}) (you will be prompted for
                 your choice),
\item[(d) ] Enter {\tt one} to view the (one) gripe whose number was
                 specified in the {\tt Beginning Gripe Number}, or
\item[(e) ] Enter {\tt exit} to exit the program.
\end{description}
A valid Display option must be given.

If you think you might like a copy of any of the gripes which will be
displayed, enter your e-mail address at the E-Mail Address Options
prompt at the bottom of the form.  You may send these gripes to {\it
any} valid e-mail address which is supported through NRAO networks.


\section{Retrieving a gripe index}

Unless you know that your query will return only a handful of gripes,
it would probably be best to start by viewing an index of your
selection of gripes. After entering {\tt index} at the Display prompt,
pressing {\tt RETURN} will display a concise list (ordered by gripe
number) of the gripes which match the criteria you selected.  Key
properties of each gripe will be displayed along with a one-line
summary of the gripe itself. The help screen (called by entering a
{\tt ?}) for the index should cover the basics of cursor movement and
individual gripe selection. Most {\tt emacs} functions still apply.
(If you need additional explanation of key bindings, etc., {\tt ESC-x
Helper-help} or {\tt ESC-x Helper-describe-bindings} should help.
These are usually available at any point in the database.)  A sample
Gripe index is shown in Figure~\ref{fig:index}.
\begin{figure}
\begin{center}
\begin{verbatim}
                     AIPS Gripe index

  No.   User              Date         Status      Keyword(s)
 4092 Alan Bridle         08-MAR-1990  NEW         EXTLIST
     Want option to list only a single file.
 4093 Alan Bridle         09-MAR-1990  NEW         VTESS
     VTESS writes wrong map type in header
 4142 Alan Bridle         23-MAR-1990  NEW         TVLOD
     Failed on IVAS
 4152 Alan Bridle         26-MAR-1990  NEW          PRTTP
      PRTTP bombed
 4153 Alan Bridle         26-MAR-1990  NEW          Output file names
     Why both OUTPRINT and OUTFILE
 4204 Alan Bridle         19-APR-1990  NEW          SL2PL
     Slice plots go offscale
 4205 Alan Bridle         19-APR-1990  NEW          SLCOL
      SLCOL doesn't collate slices
 4216 Alan Bridle         23-APR-1990  NEW          UVMAP
      UVMAP should work for packed data.
 4217 Alan Bridle         23-APR-1990  NEW         EXTLIST
     Needs a page formatter
 4218 Alan Bridle         23-APR-1990  NEW          SL2PL
     SL2PL is dying with a floating point exception
 4219 Alan Bridle         23-APR-1990  NEW         SL2PL
     SL2PL making plots that kill QMSPL and TVPL
 4220 Alan Bridle         25-APR-1990  NEW         pointless warnings
      Get rid of the non-standard program messages
\end{verbatim}
\end{center}
\caption{Sample gripe index}
\label{fig:index}
\end{figure}

\subsection{Viewing specific gripes}

From the index form, you are allowed to move the cursor to any gripe
in the index and view its full content by hitting the {\tt RETURN}
key.  You may then scroll through successive gripes ({\tt SPC} bar) or
previous ones ({\tt P}) or return to the index listing ({\tt q}).
Again, entering a {\tt ?} will give additional help for active
functions within the gripe screen.  Once a Gripe appears on the
screen, you can obtain a copy of it by e-mail by entering a lowercase
{\tt m}.  If you did not give an e-mail address in the
Selection/Options form, you will be prompted for one at this point. If
you are using an NRAO machine in Socorro, NM, entering an uppercase
{\tt L} will spool this information to the laser printer.  Entering
{\tt q} successively will bring you back out of the database to the
Selection/ Options form. A sample Gripe (the first one in the Gripe
index) is shown in Figure~\ref{fig:sampgripe}.
\begin{figure}
\begin{center}
\begin{verbatim}
                     AIPS Gripe report _GRIPE-NO: 4092

_GRIPE-ENTERED: 08-MAR-1990 12:13:09   _SYSTEM: NRAO1 Convex C1 7.1
_STATUS: NEW   _KEYWORD: EXTLIST
_ONE-LINE: Want option to list only a single file.
_USER: Alan Bridle   _USER-NUMBER: 76   _AIPS-RELEASE:  15JUL90

_GRIPE: It would be nice if EXTLIST had an option to list data only for the
extension version nominated by INVERS, rather than for INVERS plus all
higher version numbers, as it is now.  An example is the application
in which you have made many slice files (\eg\ 100) and wish to extract
the parameters of, say the ninth.  The present input structure allows
you to suppress the unwanted data for the first eight, but EXTLI then
insists on telling you about the last ninety!  Would it be more
logical for INVERS to specify the ONLY version number to be reported,
rather than the FIRST one, as now?


_ANSWERED-BY:     _ANSWER-DATE:
_ANSWER:
\end{verbatim}
\end{center}
\caption{Sample gripe file}
\label{fig:sampgripe}
\end{figure}

\subsection{Retrieving information on the gripers from the index}

If you wish additional information on the person responsible for a
particular gripe, move the cursor to that gripe number and enter a
lowercase {\tt a}. This will give the ``griper's'' address(es), phone
number(s), user number, etc.  If you want information about any {\it
other} person in the address database, entering a lowercase {\tt l}
anywhere in the Gripe Index form will yield a prompt for {\tt Name:}
at the command line.  Enter a name (syntax and spelling sensitive) to
retrieve said information.  Once the User Information form appears on
the screen, you can obtain a copy of it by e-mail by entering a
lowercase {\tt m}.  If you did not give an e-mail address in the
Selection/Options form, you will be prompted for one at this point. If
you are using an NRAO machine in Socorro, NM, entering an uppercase
{\tt L} will spool this information to the laser printer.  To return
to the gripe index, type a lowercase {\tt q}. A sample user
information file is shown in Figure~\ref{fig:userinfo}.
\begin{figure}
\begin{center}
\begin{verbatim}
                 AIPS User Information  _USER-NUMBER: 76

_USER: Alan Bridle
_ADDRESS: NRAO
 Edgemont Road
 Charlottesville, VA 22903
_PHONE: (804) 296-0375
_EMAIL: abridle@nrao.edu
\end{verbatim}
\end{center}
\caption{Sample user information file}
\label{fig:userinfo}
\end{figure}

\section{Viewing all selected gripes}

If you want to skip the gripe index and simply review the entire
contents of {\it all} gripes selected, you should enter {\tt full} at
the Display Options prompt of the Selection/Options form.  The first
gripe in the selected list will appear in its entirety.  Again, this
is read-only, and thus you are only allowed to use the {\tt emacs}
functions and key-bindings which can move the cursor and string-search
through the gripes.  You can only page through each gripe one at a
time.  When you have exhausted the list, you will be returned to the
Selection/Options form.  Again, additional help can be obtained at any
point by typing {\tt ?}, {\tt ESC-x Helper-help}, or {\tt ESC-x
Helper-describe-bindings}. Entering {\tt q} will bring you back to the
Selection/Options form.

\section{Database support/assistance}

This concludes the documentation for use of the \AIPS\ Gripes
Database.  If there are any problems with the system or in your
understanding of how to use it, please contact the database manager
(Gustaaf van Moorsel) at the National Radio Astronomy Observatory at
(505)835--7396 or send an e-mail message to {\tt gvanmoor@nrao.edu}.
We also welcome any suggestions for improving the performance or
configuration of this database.  If there are any features which you
would like to see added to this system, please let us know.

\vfill\eject
%\end{document}

%\documentstyle [twoside]{article}
\newcommand{\memnumb}{88b}
\newcommand{\whatmemb}{\AIPS\ Memo \memnumb}
%\newcommand{\whatmem}{{\bf D R A F T}}
\newcommand{\memtitb}{A Programmer's Guide to}
\newcommand{\Memtitb}{Gripes Database Programmer's Guide}
\title{
%   \hphantom{Hello World} \\
   \vskip -35pt
   \fbox{{\large\whatmemb}} \\
   \vskip 28pt
   \memtitb \\
   \vskip 10pt
   \memtit}
%
%
%
%\begin{document}

\pagestyle{myheadings}
\thispagestyle{empty}

\newcommand{\Rheadingb}{\whatmemb \hfill \Memtitb \hfill Page~~}
\newcommand{\Lheadingb}{~~Page \hfill \Memtitb \hfill \whatmemb}
\markboth{\Lheadingb}{\Rheadingb}
%
%

\vskip -.5cm
\pretolerance 10000
\listparindent 0cm
\labelsep 0cm
%
%

%\vskip -30pt
%\maketitle
\begin{center}
\begin{tabular}{c}
   \hphantom{Hello World} \\[-7pt]
   \fbox{{\large\whatmemb}} \\[35pt]
   \LARGE\memtitb \\[15pt]
   \LARGE\memtit \\[28pt]
   \large\theauthor\protect\footnotemark \\[23pt]
   \large\thedate
\end{tabular}
\end{center}
\footnotetext{\thethanks}

\normalstyle

\vskip 29pt
\begin{abstract}
The \AIPS\ Gripes database is an {\tt emacs}-based tool for
maintaining all of the many user complaints and suggestions received
by the project over its lifetime.  The present document is an in-depth
guide for programmers and the Gripe Manager to maintain the Gripes
Database and to maintain the database tools. It assumes a working
knowledge of the User's Introduction to the \AIPS\ Gripes Database and
of {\tt emacs}.
\end{abstract}

%\renewcommand{\topfraction}{0.85}
\renewcommand{\floatpagefraction}{0.75}
%\addtocounter{topnumber}{1}
\typeout{bottomnumber = \arabic{bottomnumber} \bottomfraction}
\typeout{topnumber = \arabic{topnumber} \topfraction}
\typeout{totalnumber = \arabic{totalnumber} \textfraction\ \floatpagefraction}


\section{Introduction}

The \AIPS\ Gripes Database is built within the {\tt emacs} editor
using the {\tt lq--text} string search system to aid in the selection
of files.  Most of the functions are implemented as {\tt emacs} Lisp
routines with {\tt lq--text} routines being invoked as subprocesses to
{\tt emacs}.  The two purposes of this document are (1) to describe
how to enter new gripes, modify or answer gripes and the distribution
of gripes and (2) to document the software system used for the Gripes
system.

\section{Access to the gripes database}

Programmer/Gripe manager access to the gripes database is through the
account (username) {\tt aipgripe} on {\tt zia}.  (If you wish only to
{\it use} the database (read-only privilege), you may also log into
virtual machine {\tt gripe}.) The gripes database system is started
using the procedure {\tt viewgripe}.  Programmers/Gripes Managers then
have the full user functionality available, as well as a variety of
management tools which are not documented in the on-line on-line help
and are only available when logged into account {\tt aipgripe}.

\section{Structure of the database}

   The Gripes database system consists of a number of parts: the text
of the gripes, user address information, and {\tt lq--text}
information for both of these types of information.  The gripe and
user information is kept in a collection of files, one per gripe or
user.  These files consist of coded keywords, starting with {\tt \_}
(underscore) and ending with {\tt :} (colon) and
containing only upper-case letters and {\tt -} (minus).  This allows
these files to be decomposed into a list of keyword-value pairs which
can then be manipulated by lisp functions.  Gripe files have names of
the form {\tt gripe{\it xxxx}.grp} where {\it xxxx} is the gripe
number and live in {\tt \~{ }aipgripe/gripe} or {\tt \~{ }gripe/gripe},
or {\tt /aips1/gripe/gripe}.  User information files have names of the
form {\tt {\it username}.info} and live in {\tt \~{ }gripe/adr}.
{\tt Lq-text} files for rapid searches of either of these databases
are kept in {\tt \~{ }gripe/gripedir} and {\tt \~{ }gripe/adrdir} for
gripes and user information, respectively.

\section{Entering new gripes}

Gripes may be entered into this system through three possible routes:
conversion of old \TeX-format gripes, conversion of new \AIPS\ {\tt
GR} files, or by interactively entering new gripes in {\tt viewgripe}.
Each of these are executed using lisp functions in {\tt \~{
}gripe/lisp/newgripes.el} which is set to auto load.  Since the
inclusion of a new gripe involves assigning a new, unique gripe number
(using function gripe-number), no other routes are allowed.  (Most of
the gripes lisp functions have documentation available through the
{\tt emacs} {\tt describe-function} feature.)  The functions for
entering new gripes are described in the following:

(A) The function {\tt convert-texgripes} reads the older \TeX-based
gripe files ({\tt GZ}, {\tt GX}, {\tt GS}, and {\tt GT} files ---
harvested and typeset) and extracts gripes and user information and
enters them into the new system.  A user information file will only be
added (created) if none exists for a given user and will need to be
edited to put needed linefeeds into the addresses.  To use this
function, open a window on the input file ({\tt \^{ }x-4 \^{ }f}, then
enter the name of the file --- default location {\tt /aips1/gripe}),
position to the top of the file and execute {\tt convert-texgripes}
({\tt ESC-x convert-texgripes}). The routine should run to completion
with the gripe and user files added.

(B) The function {\tt convert-AIPS-gripes} reads the \AIPS\ binary
gripe ({\tt GR}) files and extracts the gripes and corresponding user
information and enters them as individual files in the new system.
A user information file will only be added if none exists for the user
and will need to be edited to put needed linefeeds into the addresses.
To use this function, open a window on the input file ({\tt \^{ }x-4
\^{ }f}, then enter the name of the file --- default location {\tt
/aips1/gripe}), position to the top of the file and execute
{\tt convert-AIPS-gripes} ({\tt ESC-x convert-AIPS-gripes}).

(C) The function {\tt init-gripe-form} allows interactive input of a
gripe.  First, it initializes a new buffer containing a ``fill-in the
blanks'' form and automatically assigns a new gripe number and the
current date and time to it.  To use this function, hit {\tt ESC-x
init-gripe-form}. The buffer is then edited and saved with a {\tt
\^{ }X\^{ }S}  --- this will correct the status if an answer is given
and cause the {\tt lq--text} files to be updated. If you wish to stop
and return to the Selection/Options form, {\tt \^{ }x-b AIPS-GRIPE}
will switch buffers. Other buffer-switch options can be displayed by
hitting {\tt \^{ }x-b ?}.

(D) The function {\tt init-user-info} allows input/editing of user
information files.  It will first prompt you for a user name and, if
there is no information for that user, a new buffer is initialized for
interactively entering the data. If an information file for the named
user already exists, this file is displayed in a window for possible
editing.  A user information file may have multiple aliases by using
several {\tt \_USER:} name pairs.  An important point to remember when
entering an address is that each line after the first should begin
with a blank space.  This will assure correct pagination when printing
the mailing labels.  The user information files are then saved with a
{\tt \^{ }X\^{ }S} command, which will also update the {\tt lq--text}
files. Again, {\tt \^{ }x-b SPC} will show you all possible buffers to
which you can switch.

\section{Managing {\tt lq-text} files}

When gripe or user information files are updated they are re-indexed
automatically in the {\tt lq--text} system.  In addition, there is the
function {\tt rebuild-lqtext} to re-build the {\tt lq--text} system.
This should be run occasionally to insure that the files are up to
date.  {\tt rebuild-lqtext} will prompt for the file type to be
rebuilt; answer {\tt gripe} for gripes and {\tt adr} for user
information files.

\section{Editing existing gripes/user information files}

If a large number of gripes need editing, such as when assigning
keywords to new gripes, use Display option {\tt edit} in the main menu
of {\tt viewgripe}.  Each of the selected gripes will be displayed in
gripe number order in a window for editing.  The files can be saved
and indexed using the {\tt \^{ }X\^{ }S} command.  The command {\tt
ESC \^{ }C} will then advance to the next gripe.  Selecting by
status {\tt new} and a beginning gripe number is usually appropriate.

Gripes or user information files, displayed in any of the ways
described in the user documentation, can be switched to edit mode by
typing a lower case {\tt e} when the cursor is in the window.  This
file can then be saved and indexed using {\tt \^{ }X\^{ }S} and the
edit terminated with {\tt ESC \^{ }C}.  The status of any gripe
being given an answer will automatically be updated.

\subsection{A few words about gripe selection}

In order to accomodate this new gripe system, slight modifications have
been made to ``pre-database'' gripes. One important modification is the
status of the gripes. Answered gripes prior to about \#4563 (those
entered before about the second week of November, 1990) will have a
status of {\tt answered}, as opposed to {\tt answer}, {\tt
answer-new}, or {\tt answer-sent}. You must keep this in mind,
particularly when selecting a group of gripes which may have had some
entered before {\it and} after the transition to the current database
system. Thus, it may be necessary to run your query twice --- once for
each ``epoch'' of entries.

If, at any time, you wish to select only one gripe, you may do so by
first entering the number of that gripe at the {\tt Beginning Gripe
Number} prompt of the Selection/Options form and then entering {\tt
one} at the {\tt Display Options} prompt. This will quickly display
the specified gripe.

\subsection{A word about printing gripes}

If, at any time, you wish to obtain a hardcopy of a gripe (or gripes),
selecting the {\tt print} option from the Selection/Options form will
invoke a prompt as to whether to send the output to a printer or to
write it to a file.  If the {\tt file} option is selected, the output
is written in file {\tt /tmp/gripestoprint}.  Any answer other than
{\tt file} will be taken as {\tt printer}. You will note that {\tt
one} and {\tt print} cannot be selected simultaneously.  Therefore, if
you wish to print only one gripe, your other selection criteria must
be sufficiently unique such that only one will actually be selected by
it. We recommend using the {\tt Arbitrary String in Gripe} where
possible.

\section{Answering gripes}

To insert an answer to a gripe, first select the appropriate gripe(s)
in an index display and then display the gripe to be answered.  Typing
a lower case {\tt e} will switch to {\tt edit} mode.  Enter your name
as the person responsible for the answer, the current date, and the
answer in the appropriate places in the form.  A {\tt \^{ }x\^{ }s}
will then automatically correct the status, save the file, and
re-index it in the {\tt lq--text} system.  At this point it would be
friendly to mail the griper the answered gripe.  There are two ways to
do this. From the edit mode, you can immediately send the gripe to the
user (or to any e-mail address) by hitting {\tt ESC-x
mail-user-answer} (you will be always be prompted for a valid address
and also a return address in case the mail message bounces).  The
subject heading for the mail message will read {\tt Response to AIP
Gripe}.  If, within the editor, you need to verify an address, you may
use the lookup utility by hitting {\tt ESC-x lookup-user}.

You can also mail a gripe from outside the editor by first returning
to the gripe index with {\tt ESC\^{ }c}.  If you don't know the
e-mail address you can look it up by typing a lower case {\tt a} at
this point.  Then re-select the gripe by hitting \hbox{{\tt RETURN}}.
At this stage, a lower case {\tt m} will cause the gripe to be mailed,
prompting you for an address.  (Note: this assumes that you did not
enter an e-mail address on the top level form.  If you did, then the
gripe file will be mailed to the address entered in the form and you
will not be asked for the address.)

\section{Sending answered gripes}

If you would like to prepare the selected gripes for mailing, you
should enter {\tt send} at the Display Options prompt of the
Selection/Options form.  The {\tt Status} in the Selection Criteria
section of the Selection/Options form should also be filled out as
{\tt answer-new} (\ie\ gripe answered but not yet sent).  The
procedure called by this entry will make two files with the selection
criteria you specified: one is a file containing the gripes which have
been filtered for printing and mailing ({\tt /tmp/gripestomail}), and
the other is a file containing the corresponding gripers' addresses in
a form suitable for printing labels on the line printer ({\tt
/tmp/gripeaddresses}). This procedure will also change the status of
these gripes from {\tt answer-new} to {\tt answer-sent}.  Once the
{\tt send} option has been run from the Selection/Options form, it
cannot be run from there again, whether or not you restart {\tt
viewgripe}, since the contents of the gripe files will have been
changed.

If something goes wrong with the above procedure and you need to
make the gripe print and address files over again, exit {\tt
viewgripe} and restart it.  When the Selection/Options form appears,
issue the command {\tt sendgripes} (invoked with {\tt ESC-x
sendgripes}).  This procedure will recognize that its input list ({\tt
gripe-by-user}) is empty and will recover the list it last used from
file {\tt savegripelist} which lives in the {\tt gripe} directory.

\section{Buffers used by the gripe system}

There are a number of buffers used in the {\tt viewgripe} system whose
names don't usually appear in the mode line.  It is frequently
desirable to switch to one one these buffers when something goes
wrong.  (The {\tt switch-to-buffer} command is invoked by {\tt \^{
}X-b} with name completion supported).  These buffers are:
\begin{description}
\item{{\tt AIPS-GRIPE}} --- buffer contains the main
    Selections/Options form.  Hitting {\tt RETURN} will invoke
    whatever function is selected on the form.
\item{{\tt GRIPE-INDEX}} --- buffer contains the index of selected
    gripes and is usually created even if it is not displayed.  The
    usual functions can be invoked when visiting this buffer.
\item{{\tt LQTEXT-ERROR}} --- buffer will contain any messages,
    usually error and warning messages, resulting from running {\tt
    lq--text} in a subprocess.  If something goes wrong at this stage
    the usual symptom is the claim of {\tt No gripes selected}.  A
    more accurate report may be found in this buffer.
\end{description}

\section{Files used by the gripe system}

The \AIPS\ gripe manipulation system is based on the {\tt lq-text}
system to select files and lisp programs running in {\tt emacs} to
manipulate the gripes.  In addition to the gripes, a database of user
address information is also maintained.  There are several directories
in this system:
\begin{description}
\item{{\tt \~{ }gripe/bin}} contains shell scripts to interact with
    {\tt lq--text}.
\item{{\tt \~{ }gripe/lisp}} contains the lisp source code.
\item{{\tt \~{ }gripe/gripe}} contains the current gripe files, one
    gripe per file with names of the form {\tt gripe{\it
    gripe\_no}.grp}.
\item{{\tt \~{ }gripe/gripedir}} contains the files that {\tt
    lq--text} needs for the gripes.
\item{{\tt \~{ }gripe/adr}} contains the user information in files
    with names of the form {\tt {\it user\_name}.info}.  Aliases are
    allowed inside the file and {\tt lq--text} is used to actually
    find the correct file.
\item{{\tt \~{ }gripe/adrdir}} contains the files that {\tt lq--text}
    needs for the user information.
\end{description}

There are three kinds of program files needed for this system: {\tt
emacs} lisp programs (names ending in {\tt .el}), shell scripts, and a
few miscellaneous ones (named below with the full path).  They are:
\begin{description}
\item{{\tt gripeinit.el}} is the file that is run when the {\tt
    viewgripe} script is executed.  It loads the necessary files and
    brings up the selection menu.  Sets up to auto load {\tt
    sendgripes} and {\tt init-gripe-form}.
\item{{\tt gripeutil.el}} contains a number of utility routines.
    The main command of interest to programmers and the gripes manager
    is {\tt rebuild-lqtext} which re-builds a set of {\tt lq--text}
    files.
\item{{\tt mfe.el}} contains the form fill-out package.
\item{{\tt newgripes.el}} contains programs to enter new gripes into
    the system.  They are {\tt init-gripe-form} to initialize a buffer
    for a new gripe; {\tt init-user-info} to initialize a user info
    file; {\tt convert-texgripes} to convert old \TeX\ gripes; and
    {\tt convert-AIPS-gripes} to convert \AIPS\ binary gripe files.
\item{{\tt viewgripe.el}} contains programs to access and manipulate
    the gripes, both for user read-only access and programmer/gripe
    manager access.  Function {\tt view-gripe} is the top level
    routine.
\item{{\tt sendgripes.el}} contains programs to prepare files for the
    distribution of answered gripes and to update the gripe file to
    indicate this.  Function {\tt sendgripes} is the top level
    routine.
\item{{\tt aipsconsult.el}} This program runs the ``on-line''
    consultant routine for those programmers who need ``psychiatric''
    help after using \AIPS\ or the Gripes Database.
\item{{\tt viewgripe}} script to set environment variables for the
    gripe and user information files and to start up {\tt emacs}
    loading the appropriate files.
\item{{\tt lqmerge}} script to select a list of gripe files which
    contain a list of given phrases.  Output is to a file named in the
    call sequence.
\item{{\tt adrfind}} script to find the user information file
    containing a specified string.
\item{{\tt upgripe}} script to re-index a gripe file in the {\tt LQ}
    text system.
\item{{\tt upadr}} script to re-index a user information file in the
    {\tt LQ} text system.
\item{{\tt rebuild}} script to perform tasks of both the {\tt upgripe}
    and {\tt upadr} scripts in a batch-like mode. It can be set to run
    automatically at regular intervals to keep the gripe and user
    information files current.
\item{{\tt \~{ }gripe/gripe/nextnumber}} contains the next gripe
    number to be assigned.  It is maintained by function {\tt
    gripe-number} (in {\tt gripeutil.el}).
\item{{\tt \~{ }gripe/gripe/savegripelist}} contains the last {\tt
    gripe-by-user} list sent to {\tt sendgripe}.  This is kept for
    error recovery purposes.
\item{{\tt \~{ }gripe/Remote\_user}} is the shell remote users (user
    {\tt gripe}) get when they login.  It prompts for a terminal type
    (with a default) traps some errors and starts up {\tt viewgripe}.
\end{description}

\section{Database support/assistance}

This concludes the documentation for programers' use of the \AIPS\
Gripes Database.  If there are any problems with the system or in your
understanding of how to use it, please contact the database manager
(Gustaaf van Moorsel) at the National Radio Astronomy Observatory at
(505)835--7396 or send an e-mail message to {\tt gvanmoor@nrao.edu}.
We also welcome any suggestions for improving the performance or
configuration of this database.  If there are any features which you
would like to see added to this system, please let us know.

\section{Harvesting gripes\protect\footnotemark}

\footnotetext{This section was written by Brian Glendenning 1990 Dec 12 and
    revised by Glen Langston on 1992 May 04.}

\subsection{{\tt Gather.GetMany}}

{\tt Gather.GetMany} is a shell script to gather binary gripe \AIPS\
{\tt GR} files from a collection of machines available over the
network.  Because the shell script relies on the remote machine having
the ``remote shell'' ({\tt rsh}) command, it will only work on Unix
machines.

A simple file, {\tt Gather.Hosts}, controls where {\tt Gather.GetMany}
will look for gripes.  Each line of the file contains three fields
separated by spaces.   First the name of the machine, next the name of
an account with privilege to read/write the {\tt GR} files, and third
the path to the GR file.  Additionally, any line beginning with a {\tt
\#} sign in the first column is a comment and is otherwise ignored.
A sample {\tt Gather.Hosts} file is:
\begin{verbatim}
# Comments have to start in the first column with a # sign
# Format is:
#Site                via HOST         account    path to DA00
#
CVILLE-SUNS    baboon.cv.nrao.edu     aipgripe   /AIPS/DA00/BABOON
NRAO1          baboon.cv.nrao.edu     aipgripe   /nrao1/aips/code/DA00/NRAO1
AOC-SUNS       aguila.aoc.nrao.edu    aipsmgr    /AIPS/DA00/AGUILA
AOC-CONVEXES   aquila.aoc.nrao.edu    aipsmgr    /yucca/AIPS/DA00/YUCCA
AOC-IBMS       zuni.aoc.nrao.edu      aipsmgr    /AIPS/DA00/ZUNI
\end{verbatim}

Each machine listed in {\tt Gather.Hosts} needs to permit the person
running {\tt Gather.GetMany} to use {\tt rsh} as the appropriate user
(see {\tt man rhosts}).  For instance, suppose {\tt Gather.GetMany} is
being run as user {\tt aipgripe} on machine {\tt baboon}.  Then the
file {\tt .rhosts} in the home directories of {\tt aipgripe} on {\tt
baboon}, and of {\tt aipsmgr} on {\tt aguila} should contain the lines
\begin{verbatim}
                      baboon.cv.nrao.edu aipgripe
                      baboon aipgripe
                      baboon.cv.nrao.edu aipsmgr
                      baboon aipsmgr
\end{verbatim}

There must be a ``dummy'' {\tt GR} file that contains no gripes.  This
is used to reset the gripes file to none by copying over the original
{\tt GR} file.  If the {\tt GR} file is named {\tt GRC00000;1}, then
the dummy {\tt GR} file should be named \hbox{{\tt GRCdummy;1}}.  (If
the format ``version'' of the files changes in a future release of
\AIPS, the {\tt C} will become {\tt D}, then {\tt E} etc.  {\tt
Gather.GetMany} is smart enough to do the right thing until we get
past {\tt Z} and this will probably never happen.)

The script {\tt Gather.GetMany} uses the script {\tt Gather.GetOne} to
get gripes from one site.  When run, {\tt Gather.GetOne} will
concatenate all the remote {\tt GR} files it can get in the file {\tt
GRCremote} (or {\tt GRDremote} etc).  Because {\tt Gather.GetOne}
always appends, you must remove the {\tt GRCremote} file once the
gripes in it are entered into the gripes system.  As it runs, {\tt
Gather.GetOne} will write progress messages on the terminal.  It will
also put the messages into a log file called {\tt Gather.Log}.

Conditions that {\tt Gather.GetMany} tries to notice and report include:
\begin{verbatim}
              Machine or network down
              No gripes entered on this host
           *  No GR files on host
           *  No ``dummy'' file on host
              Copy fails
           *  Concatenate fails (out of local disk?)
\end{verbatim}
The items marked with {\tt *} indicate something that needs to be
looked into; everything else is normal if it doesn't persist.

\subsection{Contents of a raw gripe}

The {\tt GRCremote} file contains many invalid characters as well as
valid gripes.  Each Gripe is composed of 10 pieces, and each piece is
contained between an pair of curly brackets ( ``{\tt \{}'' and ``{\tt
\}}'' ).  It is critical for the Gripe harvesting that there are {\it
exactly 10 pairs of curly brackets, and that the correct information
is entered in its respective set of brackets}.  What should appear in
the ten (10) required sets of brackets is:
\begin{verbatim}
              1.   {date and time}
              2.   {computer}
              3.   {user# and version of AIPS}
              4.   {username}
              5.   {user address}
              6.   {user phone}
              7.   {gripe}
              8.   {one-line description of gripe}
              9.   {user e-mail address}
             10.   {I have NO IDEA what goes here}
\end{verbatim}
\addtocounter{footnote}{1}\footnotetext{the answer to the gripe, dummy}

\subsection{Adding {\tt GRCremote} to the database}

After harvesting the gripes, several steps remain before the gripe is
sitting happily in the gripes database.
\begin{description}
\item{1.}\ Edit the {\tt GRCremote} file to remove the extraneous
           characters (mostly {\tt \^{ }@}s and {\tt \^{ }M}s).
\item{2.}\ Then start up the gripes database as user {\tt aipgripe}
           using {\tt viewgripe} as described above.
\item{3.}\ Bring the new {\tt GRCremote} file in by typing the control
           sequence {\tt \^{ }X4\^{ }F} (which will ask for the name
           of a file to edit) and then the full name of the file.  It
           will appear in one of the {\tt emacs} windows.
\item{4.}\ Move into the file and type the control sequence {\tt ESC-x
           convert-AIPS-gripes}.  {\tt emacs} will say something about
           editing files in the background.
\item{5.}\ Leave the {\tt GRCremote} file by typing the control
           sequence {\tt \^{ }X0}.
\item{6.}\ Look at the list of new gripes with the gripes data-base
           command {\tt index}.
\end{description}

\end{document}
