Automatic documentation with protex

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 (by Bob Yantosca) which is a wrapper for protex. Calls protex and pdflatex to convert the output of protex to PDF format.

f90ps

Perl script (by Bob Yantsoca) which is a wrapper for protex. Calls protex, latex, and dvips 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.

If you have root privilege on your system, you can then copy the protex file to /usr/local/bin or whichever directory contains system-wide executables. Otherwise, you can install it to a directory in your own space.

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:

1. The -s option of protex will cause only the module, subroutine, and function headers to be included in the output.
2. The -f option of protex suppresses printing source code file information next to each module or routine name.
3. Calling pdflatex 3 times is necessary to ensure that the table of contents information will be compiled correctly into the final output file.
4. If the f90pdf script hangs for a while then it has probably encountered an error. To continue you may type "r" or exit with "x".

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:

1. The -s option of protex will cause only the module, subroutine, and function headers to be included in the output.
2. The -f option of protex suppresses printing source code file information next to each module or routine name.
3. Note: calling latex 3 times is necessary to ensure that the table of contents information will be compiled correctly into the final output file.
4. Also note: since there is no equivalent "pslatex" command, we must do the intermediate step of creating the dvi file and then calling dvips to create the PostScript file.
5. 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:

1. The -s option of protex will cause only the module, subroutine, and function headers to be included in the output.
2. 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 will cause a title page to be added to the output files. You may omit this if you wish.

Protex header files in more depth

template_introduction.txt

You can use the template_introduction.txt to define a title page for your document, such as:

!------------------------------------------------------------------------------
!          Harvard University Atmospheric Chemistry Modeling Group            !
!------------------------------------------------------------------------------
!BOI
! !TITLE: Front page template
! !AUTHORS: Bob Yantosca and Philippe Le Sager
! !AFFILIATION: School of Engineering and Applied Sciences, Harvard University
! !DATE: May 23, 2008
!EOI
!------------------------------------------------------------------------------

NOTES:

1. The BOI and EOI are used to define extent of the header. Protex will only look at the text between BOI and EOI.
2. Text following !TITLE, !AUTHORS, !AFFILIATION, and !DATE tags must be placed on the same line.
3. You may also specify an optional !INTRODUCTION tag following !DATE, which will become topic #1 in the table of contents. This allows you to go back later and manually insert LaTeX markup later into the output.tex file.

template_module.F90

This file contains headers for declaring a Fortran 90 module, as well for the internal module routines.

Top-of-module header

Here is the protex header that goes at the very top of a Fortran 90 module:

!------------------------------------------------------------------------------
!          Harvard University Atmospheric Chemistry Modeling Group            !
!------------------------------------------------------------------------------
!BOP
!
! !MODULE: GC_SomethingMod.F90
!
! !DESCRIPTION: This module contains the data type to declare a Something
!   object and the methods to work with the Something object. 
!\\
!\\
! !INTERFACE: 
!
MODULE GC_SomethingMod
! 
! !USES:
!
  USE ESMF_Mod
!
  IMPLICIT NONE
!
! !PUBLIC TYPES:
!
  TYPE t_GeosChemSomething 
     !... declare stuff here
  END TYPE t_GeosChemSomething
!
! !PUBLIC MEMBER FUNCTIONS:
!
  PUBLIC :: GC_SomethingRoutine1
  PUBLIC :: GC_SomethingFunction1
!
! !PUBLIC DATA MEMBERS:
!
  INTEGER(ESMF_KIND_I4), PUBLIC :: myPublicVariable  ! public data variable
!
! !REVISION HISTORY:
!  21 May 2008 - R. Yantosca - Initial Version
!
! !REMARKS:
! Protex is great!
!
!EOP
!------------------------------------------------------------------------------

The tags are mostly self-explanatory. However, you must be aware of a few things:

1. The BOP and EOP tags denote the beginning and end of the protex prologue. Protex will search for text between these two tags.
2. You must place the name of the module on the same line as the !MODULE tag.
3. The text following the !DESCRIPTION tag must also start on the same line. Unless yIf you call protex with the -s option (as is done by the f90pdf and f90ps scripts) then this will cause the text to be rendered as formatted text instead of as in fixed-space courier font. This means that:
   • Special LaTeX characters (e.g. _ and #) must be prefaced with a backslash (e.g. \_ and |#) or else this will cause compilation problems.
   • Two manual line breaks !// must be placed at the end of the text to prevent the next tag from starting on the same line.
4. Other than !MODULE and !DESCRIPTION, it is OK to place text below the rest of the tags.
5. References to journal articles or other notes should be placed after the !REMARKS tag.

--Bob Y. 17:02, 27 May 2008 (EDT)