%-----------------------------------------------------------------------
%;  Copyright (C) 1997
%;  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
%-----------------------------------------------------------------------

                 Changing a CookBook chapter

                       Eric W. Greisen

***********************************************************************

A Indexing the CookBook

1. Macros for indexing:

     indx{arg}   puts arg in the visible text and makes a normal index
                 entry of arg in normal font
     Indx{arg}   puts arg in the visible text and makes a bold index
                 entry of arg in normal font (used for primary refs to
                 arg)

     tndx{arg}   puts arg in the visible text and makes a normal index
                 entry of arg in tt font
     Tndx{arg}   puts arg in the visible text and makes a bold index
                 entry of arg in tt font (used for primary refs to
                 arg)

     iodx{arg}   makes a normal index entry of arg in normal font, arg
                 does not appear in the text.
     Iodx{arg}   makes a bold index entry of arg in normal font, arg
                 does not appear in the text (used for primary refs to
                 arg)

     todx{arg}   makes a normal index entry of arg in tt font, arg
                 does not appear in the text.
     Todx{arg}   makes a bold index entry of arg in tt font, arg
                 does not appear in the text (used for primary refs to
                 arg)

      Examples:

         On a primary page describing IMAGR:
              ... task {\tt \Tndx{IMAGR}} now ...

         On a passing reference to EDITR:
              ... and {\tt \tndx{EDITR}} has ...

         On a passing reference to coordinates:
              ...  \indx{coordinates} ....

         On a major ref to self-cal:
              ... it is called \Indx{self-calibration}.

         On a ref to something which does not appear in the desired
         exact form on a page:
              ... \iodx{Clark Clean algorithm} ...

         When the special symbol does not occur on a page in which it
         is discussed:
              ...  \todx{FILEBOX} ...

         etc.


2. Run TEX on the CookBook chapter;
      I use a proc COOKIT n for chapter n:

           tex COOK$1.TEX
           dvips COOK$1
           mv COOK$1.ps COOK$1.PS

      This automatically writes out a COOKn.NDX file with unsorted
      index entries for chapter n.

      For debugging, add the line \def\Shindex{T} after the COOK82.MAC
      input and all index entries will have boxes around them.
      Unfortunately, this may affect line and page breaks a little
      which limits its usefulness.


3. To look at the index so generated:

      a. Copy $AIPSPUBL/COOKI.TEMP to your working area.  To look at
         only the chapter n, remove all COOK*.NDX except COOKn.NDX.

      b. Run proc INDEXIT:

            rm COOKNX.SRT COOKI.TEX
            cat COOK*.NDX | sort -bfd -t: -k 2,2 -k 3n,3 -k 4n,4 > COOKNX.SRT
            export MYDIR=`pwd`
            RUN COOKNX
            COOKIT I

      c. Sometimes TEX has problems such as:

            ! Output loop---25 consecutive dead cycles.
            <to be read again>
                            \end
            l.164 \end

         Type an i for insert and then one or more \eject's as

            ? i
            insert>\eject

         This arises because the index is two columns and may get in
         trouble if the last column is the first on a page.


4. To prepare the actual index chapter COOKI is much more complicated
   and is best left to me to do the final polishing.  For my benefit
   I add the notes:

      a. Copy $AIPSPUBL/COOKI.TEMP and $AIPSPUBL/COOK*.NDX to my area.

      b. Run INDEXIT.

      c. Fix long line
         "Very Long Baseline Interferometry --- Techniques and Applications"
         to
         \icls{Very Long Baseline Interferometry}{}{}
         \icls{\hskip 0.8cm --- Techniques and Applications}{G}{21}

      d. Fix START_TPSERVERS to START\_TPSERVERS

      e. Rerun COOKIT, check output for pagination inserting \eject to
         squeeze things or \vfill\eject to expand.

      f. Rerun COOKIT and find last full 2-column page.  After it,
         insert

            \eject
            \def\twocol{F}\hsize 6.5in
            \endit{

         followed by half of the remaining index entries; then at end
         of line of last one in 1st col

                      }%
            {

         then at end of line of last

                      }

            \tenpoint
            \subsectt{I.1.  Additional \indx{recipe}s}
            \subsubsectt{I.1.1.  Hawaiian banana cream pie}

         or whatever fits.


***********************************************************************

B. Other things to watch for:

   a. The revised date and the version to which the text applies:

          \def\titlea{15-Apr-1998 (revised 11-July-1997)}

      says that this chapter is updated for 15APR98 but last actually
      modified on 11-July-1997.  Users and Ernie need this info to
      decide whether they need a new chapter or not.

   b. Some chapters have figures, so we prepare two versions of the
      PostScript files:

      Set
         \def\doFIG{F}
      in the file, then COOKIT n, then
         mv COOKn.PS COOKn.0.PS

      Then set
         \def\doFIG{T}
      in the file and rerun COOKIT n.

   c. chkout and putbck:

      Check out the TEX and NDX files:

         chkout $AIPSPUBL/COOKn.TEX $AIPSPUBL/COOKn.NDX

      Edit, index, COOKIT etc until ready

      Add copyleft statement to both PS files between the
      %%BoundingBox and the %%EndComments cards.

      Remove the old PS files (rcs would make immense files so start
      afresh each time)

         remove $AIPSPUBL/COOKn.*PS

      Then put all back

         putbck $AIPSPUBL/COOKn.TEX $AIPSPUBL/COOKn.NDX
         putbck $AIPSPUBL/COOKn.PS $AIPSPUBL/COOKn.0.PS


***********************************************************************

C. Table of Contents, WWW pages, recipes:

   Again, these are best left to me.  Let me know that you have
   changed a chapter and I will take care of things.  What I do is:

   a.  Re-edit COOKn.TEX to improve pagination and select the recipes
       that fit to make an even number of pages.  Also change
       $AIPSPUBL/RECIPE.TEX to match.

   b.  Edit COOK0.TEX et al much like any other chapter to match the
       changes to COOKn's sections, page numbers, and recipes.

   c . Edit the www cook.html to match the changes in COOK0 and to put
       down revision info about COOKn.

   d.  Copy $AIPSPUBL/COOKn.*PS and $AIPSPUBL/COOK0.*PS to the ftp
       area.


***********************************************************************
