For those of you interested in how I maintain this documentation, here are descriptions and pointers to the behind-the-scenes tools that I use. If you aren't passably familiar with the internals of a Makefile, then this description isn't going to be much good since everything is driven by a Makefile in my IDL procedures directory. As I create new routines, the name (with a .ps tag) is added to the Makefile.
I use this routine to generate new printed listings of changed routines and have added the on-the-fly creation of the html pages displayed from my Web page. A procedure has two files, the .pro file which is the source code and the .ps file which is a Postscript file that is a formatted listing. A listing is out of date and must be regenerated whenever the .pro file is touched.
Rebuilding the .ps file is easy. I have my own program "pspr" which generates a pretty listing. Any program that generates a new output file, postscript or otherwise will work just fine here. When this step happens, I take the opportunity to do a few things. (1) make a copy of the procedure to an Export directory which makes it easy for me to do partial updates to other sites I maintain, (2) regenerate the html file from the documentation header (Astronomy Users Library format), (3) and then print the postscript.
The next level of the Makefile concerns the "catalog" of procedures. The catalog depends on all the procedures, so that if one is touched, the catalog must be rebuilt. There are three components to my catalog and are all generated from an important intermediate file, "cat.db". This file is generated using a simple C program named "idlprodb". This program extracts the name, one line description, and category from the documentation header and puts the info in a tab-delimited table. Then, the three components are generated from perl scripts. These components are (1) plain ASCII file with a summary of the routines generated by "db2txt", (2) TeX format listing of the routines generated by "db2tex", and (3) HTML format listing of the routines generated by "db2html". The HTML file is what you see from the Web. I use the TeX file for my own uses and the ASCII file is kept with the combined tar file from the exported routines. Note that the db2html and db2tex scripts grab a header and footer file to help make the output file complete. That eases the process of changing contents of the output that describe the automatically generated information.
When the catalog is regenerated I also collect these routines into a tar file, run it through gzip, and then move the new copy of my library to the distribution area.
So, when it's time to refresh the documentation in my notebook I type make catalog and I get printouts of any changed routines, the Web tree is updated and the exported files are refreshed. It may not be totally simple but it does work for me. Any suggestions for improvements are gratefully accepted.
Here's a list of the files needed to maintain my documentation. Copies of these files can be downloaded from our ftp site.
| Makefile | Master makefile to control documentation. |
| cat_head.html | Fixed head of main html file |
| cat_head.tex | Fixed head of TeX file |
| cat_tail.html | Fixed tail of main html file |
| cat_tail.tex | Fixed tail of TeX file |
| doc.sty | TeX style file used to format the TeX catalog listing |
| pro2html.c | C program that creates HTML file from documentation header |
| idlprodb.c | C program that creates extracted database of procedure information |
| db2html | Perl script to create html file from database |
| db2tex | Perl script to create TeX file from database |
| db2txt | Perl script to create ASCII file from database |
| pspr.c | C program to generate fancy postscript printout |
| fgetline.c | C support routine |
| sindex.c | C support routine |