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.