5.1 Concept

We believe that there is no complete system available which fulfills the requirements specified in section 3, thus we have chosen to develop portions of a solution internally. The software documentation tool ProTeX suggested here consists of a number of documenting conventions plus a simple collection of scripts written locally for the DAO's needs. It fulfills the modest goals listed in section 3 and is sufficiently simple to be understood by any DAO developer. It is designed around and constructed solely for Fortran90 development. The scripts are designed to be easily extensible and may be altered in the future to accommodate new types of documentation.

The following tools have been adopted from the public domain.

• TeX and LaTeX\
• latex2html
• perl

The use of ProTeX can be described by the following steps:

1. The user inserts markers into the code which indicate the start and end of certain regions of code, e.g., the introduction,
2. The user inserts keywords as Fortran comments into the code. These keywords determine the mode or section the code is describing. Addition documentation in that section is treated as LaTeX source. Intervening Fortran90 statements should apply to the active section. This documentation should be sufficiently readable to other team members for normal development purposes.
3. In order to produce a LaTeX document, protex is run with the source code as input. Not only are the comments ``stripped'' out of the code, but certain Fortran statements, such as the declaration of variables, are integrated into the document. This ensures that there need not be additional documentation of items which are already self-explanatory.
4. The LaTeX source can be run through the normal LaTeX cycle to obtain a document describing the commented code.
5. If so desired, the LaTeX document can also be run through latex2html to produce an equivalent HTML document.

The keywords can be considered as a comment within the comments: they are prefixed with an exclamation point and capitalized to indicate that they are not merely text. While the markers and keywords which we believe are necessary are already defined, additional ones could be defined with minimal alterations to the ProTeX system. Thus the system is extensible.