Automatic documentation with protex: Difference between revisions
No edit summary |
No edit summary |
||
Line 3: | Line 3: | ||
We shall use protex to auto-document all ESMF-compatible code created at Harvard. We therefore recommend GEOS-Chem users to become familiar with protex. | We shall use protex to auto-document all ESMF-compatible code created at Harvard. We therefore recommend GEOS-Chem users to become familiar with protex. | ||
'''''NOTE: | '''''NOTE: In order to use protex, you must have the various LaTeX utilities (e.g. latex, pdflatex, dvips, etc.) installed on your system. These should come standard with most builds of Unix or Linux.''''' | ||
== Downloading protex == | == Downloading protex == |
Revision as of 19:41, 23 May 2008
Protex is a very useful Perl script that can strip information from a standard Fortran document header and save that to a LaTeX file. Protex was developed at the Goddard Space Flight Center by Arlindo Da Silva, Will Sawyer, and others.
We shall use protex to auto-document all ESMF-compatible code created at Harvard. We therefore recommend GEOS-Chem users to become familiar with protex.
NOTE: In order to use protex, you must have the various LaTeX utilities (e.g. latex, pdflatex, dvips, etc.) installed on your system. These should come standard with most builds of Unix or Linux.
Downloading protex
Click here to download a tarball file with the protex script, template headers, and sample output files.
To install protex, do the following:
gunzip protex.tar.gz tar xvf protex.tar
This will install the following files into the protex subdirectory:
- README
- A file that describes the contents of the tar file.
- protex
- Perl script (by Arlindo da Silva et al) from GSFC that converts special F90 header comment tags into LaTeX format.
- f90pdf
- Perl script which is a wrapper for protex. Calls protex and pdflatex to convert the output of protex to PDF format.
- f90ps
- Perl script which is a wrapper for protex. Calls protex, latex, and dvipdf to convert the output of protex to PostScript format.
- template_introduction.txt
- Front page template file for use with the protex script. Use this template to specify the title of the document, authors, affiliation, and date. This should always be the first file passed to protex.
- template_includefile.h
- Template header file with sample F90 declarations
- template_module.F90
- Template F90 module with module header and internal routines.
- template_routine.F90
- Template F90 file for a standalone program or routine (i.e. not contained in a module).
- sample.pdf
- Sample PDF output file, created from the template_includefile.h, template_routine.F90 and template_module.F90 files.
- sample.ps
- Sample PostScript output file, created from the template_includefile.h, template_routine.F90 and template_module.F90 files.
Generating PDF documentation
To generate a PDF file, type:
f90pdf [list of files]
This will create the files:
- output.tex
- Documentation file in LaTeX format file
- output.pdf
- Documentation file in PDF format
You may choose to rename these as you see fit. f90pdf is a convenience wrapper script. It executes the following commands:
protex -s -f [list of files] > output.tex pdflatex output.tex pdflatex output.tex pdflatex output.tex rm *.dvi *.aux *.log *.toc
NOTES:
- The -s option of protex will cause only the module, subroutine, and function headers to be included in the output.
- The -f option of protex suppresses printing source code file information next to each module or routine name.
- Calling pdflatex 3 times is necessary to ensure that the table of contents information will be compiled correctly into the final output file.
- If the f90pdf script hangs for a while then it has probably encountered an error. To continue you may type "r".
Gnerating PostScript documentation
To generate a PostScript file, type:
f90ps [list of files]
This will create the files:
- output.tex
- Documentation file in LaTeX format file
- output.ps
- Documentation file in PDF format
You may choose to rename these as you see fit. Like f90pdf, f90ps is a convenience wrapper script. It executes the following commands:
protex -s -f [list of files] > output.tex latex output.tex latex output.tex latex output.tex dvips output.dvi -o output.ps rm *.dvi *.aux *.log *.toc
NOTES:
- The -s option of protex will cause only the module, subroutine, and function headers to be included in the output.
- The -f option of protex suppresses printing source code file information next to each module or routine name.
- Note: calling latex 3 times is necessary to ensure that the table of contents information will be compiled correctly into the final output file.
- Also note: since there is no "pslatex" command, we must do the intermediate step of creating the dvi file and then calling dvips to create the PostScript file.
- If the f90ps script hangs for a while then it has probably encountered an error. To continue you may type "r".
Generating HTML documentation
To generate HTML documentation from F90 files, type:
protex -s -f [list of files] > output.tex latex2html output.tex
This will call the latex2html utility (which ships standard with Linux) to parse the LaTeX file "output.tex" and create navigatable HTML pages.
NOTES:
- The -s option of protex will cause only the module, subroutine, and function headers to be included in the output.
- The -f option of protex suppresses printing source code file information next to each module name.
Sample output files
We have created sample output files for you (sample.pdf, sample.ps) from the F90 template files located in this directory. These were created with the following commands:
f90pdf template_introduction.txt *.h *.F90 mv output.pdf sample.pdf
f90ps template_introduction.txt *.h *.F90 mv output.ps sample.ps
Note that by placing the template_introduction.txt file first before any Fortran files (*.h, *.F90), this wlll cause a title page to be added to the output files. You may omit this if you wish.
--Bob Y. 15:37, 23 May 2008 (EDT)