DAO Office Note 97-11 Office Note Series on
Global Modeling and Data Assimilation

Richard B. Rood, Head
Data Assimilation Office
Goddard Space Flight Center
Greenbelt, Maryland

ProTeX : A Sample Fortran 90 Source Code Documentation System

William Sawyer
Arlindo da Silva
Data Assimilation Office, Goddard Laboratory for Atmospheres
Goddard Space Flight Center, Greenbelt, Maryland

This paper has not been published and should
be regarded as an Internal Report from DAO.

Permission to quote from it should be
obtained from the DAO.

Goddard Space Flight Center
Greenbelt, Maryland 20771
July 1997

Abstract:

This office note recommends a software documentation system for code currently under development at the DAO. The suggested documenting conventions and software tools outlined within allow for automatic generation of LaTeX- and HTML-based documentation of data structures and code, without requiring a large manpower investment beyond the concise documentation of the code itself.

Comments and suggestions for alterations are solicited.

 
• Contents
• List of Tables
• 1 Introduction
• 2 Rationale for an Automated Documentation System
  • 2.1 LAPACK
    • Example:
  • 2.2 LAPACK90
    • Example:
  • 2.3 PPGP
    • Example:
  • 2.4 Epilogue: Lessons for the Future
• 3 Goals and Assumptions
• 4 Available Public Domain Software
  • 4.1 FWEB
    • Example:
  • 4.2 SRC2TEX
    • Example:
  • 4.3 DOCFOR
• 5 Suggested Solution
  • 5.1 Concept
  • 5.2 Usage
  • 5.3 Possible Extensions
• References
• APPENDIX: Reference Manual for ProTeX
  • A.1 Documenting Conventions
    • Introduction Keywords:
    • Prologue Keywords:
    • Example 1: ATESS Routine
    • Example 2: DGESV_F90 revisited
  • Tools: LaTeX Generation with ProTeX
    • Mapping of code to a LaTeX document
    • Example: DGESV_F90 LaTeX Output
    • DGESV_F90() -- Fortran90 wrapper to LAPACK DGESV
  • A.3 Tools: automatic generation of documentation
  • A.4 ProTex Templates
    • A.4.1 Template for routines which are not internal to modules
    • A.4.2 Template for a routine internal to a module
    • A.4.3 Template for a module
    • A.4.4 Template for a Fortran include file
    • A.4.5 Template for an Introduction
• About this document ...