ARJO SEGERS
KNMI, The Netherlands
Date: 3 March 2009
Perl filter to produce a LATEX compatible document from a Fortran source code with standard ProTEX prologues.
Original script by NASA GMAO.
Modifications include:
Protex annotations are special marks in comment lines. In a Fortran90 code, they may look like:
!ProTeX: 1.14-AJS ! !BOI ! ! % Look at this comment as if the '! ' is not there, ! % and what remains should be interpreted as LaTeX. ! % <-- This '%' therefore marks comment, and can be used to comment ! % on the protex annotations. In the tex file formed by ProTex, ! % these lines are visible as comments. ! ! % Always use a whitespace after the '!', required to split the line. ! ! !INTRODUCTION: ! This a description of the code. ! !EOIThe following comment types are recoqnized:
file type comment string Fortran90 ! scripts # C \\ADA --
A useful first ProTeX statement is to identify the lowest version number of the protex script that is able to interpretate the comment:
!ProTeX: 1.14-AJSIf not set, the default '1.14' is used.
The highest level of Protex annotations surround a block of code and define the function of the block. In the example above, the '!BOI' and '!EOI' marks define the begin/end of the 'introduction'. The supported begin/end marks are:
block begin mark end mark description introduction cBOI cEOI introduction text prologue cBOP cEOP function/subroutine headers prologue internal cBOPI cEOPI function/subroutine headers for internal usage code cBOC cEOC source code
The introduction is the first section in the tex document. Optionally, a title page is written.
The following is an example of a an introduction in Fortran90.
!BOI ! ! % At least one of the following keyswords should be set ! % to create a title page: ! ! !TITLE: ProTeX v. 1.15 ! !AUTHORS: Arjo Segers ! !AFFILIATION: KNMI, The Netherlands ! !DATE: 21/04/2004 ! ! % Add one or more sections using the 'INTRODUCTION' keyword. ! ! % Non-keyword lines before the '!INTRODUCTION' keyword ! % will mess up the tex file and should therefore be ! % introduced with a '%' as tex comment. ! ! !INTRODUCTION: Introduction ! ! % Text after the 'INTRODUCTION' keyword is interpreted as tex, ! % and therefore might contain tex commands. ! % Use the tex 'verbatim'-environment or the ProTeX shorthands ! % '\bv'..'\ev' to pass text literally. ! ! This is a very useful introduction. ! !EOI
The 'Prologue' describes functions and subroutines.
!BOP
!
! !MODULE: xxx
! %\subsection{Fortran: Module Interface xxx (Source File: fff)}
!
! !INCLUDE: xxx
! %\subsubsection{Include File xxx (Source File: fff)}
!
! !ROUTINE: xxx
! %\subsubsection{xxx (Source File: fff)}
!
! !FUNCTION: xxx
! %\subsubsection{xxx (Source File: fff)}
!
! !IROUTINE: yyy xxx
! %\subsubsection [yyy] {yyy xxx}
!
!
! % The following keywords are optional.
! % The remainder of a keyword line is skipped.
! % Text up to the next keyword is passed verbatim.
!
! !PUBLIC TYPES: \sf
! !PRIVATE TYPES: \sf
! !PUBLIC MEMBER FUNCTIONS: \sf
! !PRIVATE MEMBER FUNCTIONS: \sf
! !PUBLIC DATA MEMBERS: \sf
!
! !DEFINED PARAMETERS: \sf
!
! !INTERFACE: \sf
! !GENRIC NAME: \sf
!
! !USES: \em
! !PARAMETERS: \em
! !ARGUMENTS: \em
! !INPUT PARAMETERS: \em
! !INPUT/OUTPUT PARAMETERS: \em
! !OUTPUT PARAMETERS: \em
! !RETURN VALUE: \em
!
! !SYSTEM ROUTINES: \sf
! !FILES USED: \sf
! !CALLING SEQUENCE: \sf
! !CALLED FROM: \sf
! !LOCAL VARIABLES: \sf
! !REMARKS: \sf
! !BUGS: \sf
! !TO DO: \sf
! !SEE ALSO: \sf
! !AUTHOR: \sf
! !REVISION HISTORY: \sf
!
! % The discription is a special keyword, since the text
! % following the keyword is interpreted as tex.
! % Use the '-x' command line option to pass descriptions
! % in verbatim mode.
!
! !DESCRIPTION:
! This is the description.
! Text is interpreted by tex.
!
!
! !CLASS: xxx
! %\subsection{C++: Class Interface xxx (Source File: fff)}
!
! !METHOD: xxx
! %\subsubsection{xxx (Source File: fff)}
!
!EOP
Example in Fortran90:
!BOP
! !ROUTINE: Welcome
!
! !INTERFACE:
subroutine Welcome( status )
! --- in/out ------------------------------
! !ARGUMENTS:
integer, intent(out) :: status
! --- doc ---------------------------------
! !DESCRIPTION:
!
! Print a welcome message.
!
! !RETURN VALUE:
!
! Non-zero on error.
!
!EOP
! --- begin -------------------------------
! print welcome message:
print *, 'hallo!'
! ok
status = 0
end subroutine welcome
Use marks BOPI/EOPI to define a prologue that is usually for internal usage only; output of such a prologue is ommited if with the '-i' option.
Be carefull with 'end{verbatim}' in the sourcefile; this will cause LaTeX to break ...
INTERFACE:
protex [-h] [-b] [+-inlsxf] [-FSCA] [src_file(s)]ARGUMENTS:
Help flag:
-h Help mode: list command line options
Skip/include flags:
-b Bare mode, meaning no preamble, etc.
-i (+i) internal mode: omit prologues marked !BOPI
-s (+s) Shut-up mode, i.e., ignore any code from BOC to EOC
-l (+l) Listing mode, default is prologues only
mark description default -b -i -s -l
------------- -------------------- ------- -- -- -- --
Preamble (titlepage) + -
BOI , EOI Introduction +
BOP , EOP Prologue +
BOPI, EOPI Prologue Internal + -
BOC , EOC Code + -
source listing - +
Style flags:
-n (+n) New Page for each subsection (wastes paper)
-x (+x) No LaTeX mode, i.e., put 'DESCRIPTION' in verbatim mode
-f (+f) No source file info
File type flags:
flag file type comment
---- --------- -------
-F Fortran ! (default)
-S script #
-C C //
-A ADA --
DESCRIPTION:
Perl filter to produce a LATEXcompatible document from a DAO Fortran source code with standard ProTEX prologues. If source files are not specified it reads from stdin; output is always to stdout.
The options can appear in any order. The options, -h and -b, affect the input from all files listed on command-line input. Each of the remaining options effects only the input from the files listed after the option and prior to any overriding option. The plus sign turns off the option. For example, the command-line input,
protex -bnS File1 -F File2.f +n File3.f
will cause the option, -n to affect the input from the files,
File and File2.f, but not from File3.f. The
-S option is implemented for File1 but is overridden by
the -F for files File2.f and File3.f.
SEE ALSO:
For a more detailed description of ProTeX functionality,
DAO Prologue and other conventions, consult:
Sawyer, W., and A. da Silva, 1997: ProTeX: A Sample
Fortran 90 Source Code Documentation System.
DAO Office Note 97-11
REVISION HISTORY:
20 Dec 1995 da Silva First experimental version
10 Nov 1996 da Silva First internal release (v1.01)
28 Jun 1997 da Silva Modified so that !DESCRIPTION can appear after !INTERFACE,
and !INPUT PARAMETERS etc. changed to italics.
02 Jul 1997 Sawyer Added shut-up mode
20 Oct 1997 Sawyer Added support for shell scripts
11 Mar 1998 Sawyer Added: file name, date in header, C, script support
05 Aug 1998 Sawyer Fixed LPChang-bug-support-for-files-with-underscores
10 Oct 1998 da Silva Introduced -f option for removing source file info
from subsection, etc. Added help (WS).
06 Dec 1999 C. Redder Added LaTeX command "\label{sec:prologues}" just
after the beginning of the proglogue section.
13 Dec 1999 C. Redder Increased flexbility in command-line
interface. The options can appear in any
order which will allow the user to implement
options for select files.
01 Feb 1999 C. Redder Added \usepackage commands to preamble of latex
document to include the packages amsmath, epsfig
and hangcaption.
10 May 2000 C. Redder Revised LaTeX command "\label{sec:prologues}"
to "\label{app:ProLogues}"
10 Oct 2002 da Silva Introduced ARGUMENTS keyword, touch ups.
15 Jan 2003 R. Staufer Modified table of contents to print only section
headers - no descriptions
25Feb2003 R. Staufer Added BOPI/EOPI and -i (internal) switch to provide
the option of omitting prologue information from output files.