Title:            Revisions to Programmer Documentation
Responsible:      Wes Young (wyoung@nrao.edu)
Originator:       Wes Young (wyoung@nrao.edu)
Exploders:        aips2-doc aips2-workers
Time Table:
    Date of issue:     1996 February 12		Done
    Comments due:      1996 February 16		Done
    Revised proposal:  1996 February 22		Done
    Final comments     1996 February 27		Done
    Decision date:     1996 February 29		Accepted

Statement of goal:

Better organization of Programmer Documentation.

Proposed Changes

1. Reorganize the AIPS++ on-line programmer documentation page.  Please visit


http://tarzan.aoc.nrao.edu/~wyoung/newonline/newonline.html

   to see the proposed revision.

2. Bring the AIPS++ Programmer manual up-to-date.  Please visit


http://tarzan.aoc.nrao.edu/wyoung/htmldir/Coding/Coding.html

   to get a flavor of what the change might look like.  This manual
   will be split into three volumes.  Volume 1 would be background
   and overview material, Volume 2 would be Package and Module, and
   Volume 3 and Class reference.

3. Remove most machine names from the URL's in the documentation.

4. Convert any useful texinfo files into LaTeX.

5. Write package documentation in HTML.

6. Separate postscript files for all chapters of the Programmer's Reference
   Manual (as well as two postscript files for Background and Package
   Volumes.  The class reference manual could be printed out on an as
   needed basis).

7. Review and update chapters in in the Programmer's Reference Manual.

8. Tag all files with dates and who did the revision.

Expected impact

1. Reorganization of the on-line documentation page should provide more useful
   information at a higher level so users don't have to dig so much.

2. Removing machine names should improve response for local hypertext
   documentation service.

3. Package documentation needs to be written.

4. The Programmer's reference manual stays a collection of documents.  In the 
   proposed revision, the manual is  broken into three volumes; Background,
   Packages, and Class Reference.  Chapters in the Background should be written
   in LaTeX (A number of chapters were originally written in texinfo but
   have been converted to LaTeX).  Chapters written in the Packages Reference
   will have Package and Module.  The Class Reference will be HTML description
   files.

5. All chapters in the Background section need to be reviewed and brought
   up-to date by their authors (assuming they still work on the project).

6. Make-rules and documentation tree need to be identified and implemented
   for converting LaTeX files into html.

7. References from HTML to LaTeX documents will require parsing the labels.pl
   file to find the right name for the link.  Maybe cxx2html could do this
   automatically for us?

8. Convert the AIPS++ System Manual into LaTeX.

9. We will have to identify tools for integrating LaTeX and HTML documents.

Proposed Documentation changes

Some reorganization and lots of rewriting and writing of details.

----

Some Random Comments

In the hypertext Programmer's Reference Manual the pointers to the
postscript files are not valid.