                 Instructions for LaTeXing Going AIPS
                          W. D. Cotton
                            02/05/90

Running Latex:
------- -----

   In the file gavol*.tex there is an includeonly statment which gives
the names of the files to actually include.  Only this statment needs to
be changed to process a limited number of chapters.  When making the
index file (gavol*.idx) all of the chapters, appendices etc. should be
included or they will not show up in the index.  On CVAX:

$ texini
$ latex gavol1
$ dviqms gavol1
$ las gavol1.bit

   On the Sun system the file can be LaTeXed and previewed but cannot be
printed on one of the normal NRAO printers.  LaTeX must be run on a
machine running version 4... of Sun OS.  To run Tex stuff one needs to
add the following to the .cshrc file in his home directory:

alias   tex             /home/ccc/local/bin/tex.3.5
alias   las             "lpr -d"
alias   preview         /home/ccc/local/bin/dvitool.3.5
alias   dviqms          /home/ccc/local/bin/dvips810
alias   addtex          "set path=($path /home/ccc/local/bin)"

Then saying addtex to the monitor will add the directory with the Tex
exectuables to your search path.  Note: do this in a window that you
don't mind having hung up when ccc goes down.  With the above
declarations, Tex and preview can be run on Suns under OS 3.5.  Latex
needs to be run under 4...

   To run LaTeX type:
% addtex                      (only needed once)
% latex gavol1

   To run the previewer (only works if you are running suntools on that
machine):

% addtex                      (only needed once)
% preview gavol1

    Unfortunately the .dvi files cannot be copied to CVAX and processed
there; latex has to be rerun.


Making the Index
------ --- -----

   Latex doesn't have a complete set of tools for making a complete
index.  LaTeX will make an .idx file with all of the index instructions
in it.  However, it contains no tools for translating this into a .tex
file that you need to actually make an index.  Chris Flatters has
written a korn shell script that will do this operation for a flat index
(i.e. no subindexing).   This is in a file named gaindex.ksh.  At
present this can only be from a Convex using the syntax:

% ksh gaindex.ksh gavol1.idx > index1.tex      ( for Going AIPS vol 1)

The resulting .tex file can then be included into the document.  Some
editing will be needed; see notes in gavol?.tex.

   The necessary korn shell script is:
# gaindex -- make an index for Going AIPS
# April 13, 1989
#-----------------------------------------------------------------------
#   A LaTeX .idx file is converted to the correct form to be used in
#   the LaTeX "theindex" environment.  The finished index is printed on
#   the standard output.  Note: the page numbers are sorted into
#   alphabetic rather than numeric order.
#
#   Usage: gaindex .idx_file
# from Bourne shell
#  %ksh gaindex file.idx > index.tex
#-----------------------------------------------------------------------
# Check number of arguments:
    if (($# != 1))
    then printf -u2 Usage: gaindex .idx_file
         exit 1
         fi

awk ' { startstr = index($0, "{") + 1
        endstr = index($0, "}")
        len = length($0)
        str = substr($0, startstr, endstr - startstr)
        rest = substr($0, endstr + 2, len - endstr - 1)
        endch = index(rest, "-")
        ch = substr(rest, 1, endch - 1)
        endpg = index(rest, "}")
        pg = substr(rest, endch + 2, endpg - endch - 2)
        printf "%s|%s|%s\n", str, ch, pg }' $1 |
    sort -nt\| +2 |
    sort -nt\| +1 |
    sort -ft\| +0 -1 |
    uniq |
    awk 'BEGIN	{ FS = "|"; oldstr = "" }
	        { if ($1 == oldstr)
                     printf ", %d--%d", $2, $3
                  else
                    {
                       oldstr = $1
                       printf "\n\\item %s %d--%d", $1, $2, $3
	            }
                 }'



Making figures
------ -------

   The program fig will allow you to make figures using a interactive
graphics tool.  An executable for Sun OS 3.5 of this program is on
gorilla in /usr/bin.  The source, icon etc are in ~bcotton/fig on
gorilla.  For Sun OS 4... there is an executable in /home/ccc/local/bin
(i.e. the addtex will add this directory to your search path).

   There doesn't seem to be any documentation for fig at nrao but with a
little playing around it is mostly obvious.  There are some bugs but
basically it works.  When you have what you want you should write the
result into a file name ending in .fig (it only seems to write into the
default directory).  Then you have to translate the .fig file into
something useful.

TransFig

   This program(s) translates .fig files into any of a number of
potentially useful forms.  Documentation for this may be obtained from
WDC or DCW.   The output formats that are available are: PicTeX,
postscript, LaTeX, epic, eepic and tpic.  Of these I have only tried the
Latex version.  This is probably the most restrictive of the set but for
the simple figures in Going AIPS it is sufficient.  (Only straight line
segments and text are likely to work.

   This is only available on Sun OS 4...  After the addtex command you
can run transfig to produce a latex file from a figure in myfig.fig with:

% transfig -L latex myfig.fig
% make -f Makefile myfig.tex

   The output of TransFig still needs a bit of work to make it useable.
In particular, the text is specified to be written as a font macro
\svtntt.  I couldn't find this so I changed it to \rm.  Unfortunately,
this font is not quite the right size and the text is written in blocks
of 3 letters.  This combination results in rather unpleasing figures so
I concatenated the blocks of text so that the spacing between characters
is OK.  Also, sometimes the text doesn't come out quite where you want
it so you can change the location in the put command used for text:
\put(xloc,yloc){\makebox......
Usually changing xloc by 5 or 10 units is sufficient; use the previewer
to check the results.
   Something in this procedure offends dviqms on CVAX and it claims
"checksum mismatch" but seems to produce the correct results.

   The figures for Going AIPS volumn 1 are: popsfig, aipsfig, sysfig,
aplfig, qfig, docfig, aplfig, incfig, qyfig and yfig.


Making the Shopping Lists
------ --- -------- -----

   The shopping lists can be made using the utility programs SHOPA
and SHOPB.  These tasks should work on either VMS or Unix but the
description given here is biased towards Unix.  In either case, a
logical/environment variable named MYDIR needes to be set to point to
the directory that you are working in
(e.g. %setenv MYDIR /mnt/myname/aips).
Both of these programs use AIPS i/O utilities so are excessively verbose
and hard to kill.

   SHOPA extracts the one liners from a list of files given in a file
in MYDIR named SHOPA.LIS one name per line, the first line of the
file should be the logical name of the directory being extracted.  Only
one directory per run of SHOPA may be processed.
   SHOPA opens its output file SHOPA.OUT with append so it mak be
run as many times as necessary.  The directories needed for the Appendix
to Going AIPS are APLSUB, APLNOT, APLGEN, AIPSUB, QPSAP, QNOT, QSUB,
YSUB, YNOT and YGEN.
   SHOPA.LIS can be formed under Unix as shown in the following
example for $APLSUB: (the initial directory is to be MYDIR)
%setenv MYDIR `pwd`
%echo APLSUB > SHOPA.LIS
%cd $APLSUB
%"ls" *.FOR *.C >> $MYDIR/SHOPA.LIS    (the double quotes may be
                                           necessary if you have ls
                                           aliased to some nonstandard)
%cd $MYDIR

   SHOPA.OUT needs to be sorted and merged to a file named
shopping.sort; this can be done under Unix using:
%sort +0 -4 -u -f -o shopping.sort SHOPA.OUT

   SHOPB can then be used to reformat this file.  SHOPB reads
MYDIR:shopping.sort and writes MYDIR:shopping.list.  This output file
will probably need some hand editing before putting into Going AIPS;
especially adding the \subsection{...} around the category names,
discarding the rest of the category line and putting \begin{verbatim}
and \end{verbatim} around the category listings.  This is easily done
with an emacs keyboard macro.
