Protex

From tm5
Jump to: navigation, search

ProTex is a Perl script that builds external documentation from code source, with the help of specific keywords/tags in the code. The set of ProTex tags can be used to enforce a specific format for internal documentation, even if there is no plan to produce an external documentation with the Perl parser. In that case, you do not need to install ProTex.

ProTex tags

You can first look at examples in the most recent TM5 code, or at

TM5/tools/protex/examples/template_module.F90

if you have the tools directory in your TM5 installation.

Code header documentation is called a prologue in Protex, and should be between !BOP and !EOP (Beginning and End Of Prologue) tags. Four other keywords are mandatory if you want to parse your code with the Perl script protex:

!MODULE:
!DESCRIPTION:
!INTERFACE:
!HISTORY:

You should replace MODULE with ROUTINE (standalone routine), IROUTINE (for internal subroutine), CROUTINE (for contained routines), or FUNCTION where fits.

Other useful recognized keywords are:

!USES:
!ARGUMENTS:
!INPUT PARAMETERS:
!OUTPUT PARAMETERS:
!INPUT/OUTPUT PARAMETERS:
!RETURN VALUE:
!PUBLIC MEMBER FUNCTIONS:   to list public module routines
!PRIVATE MEMBER FUNCTIONS:  to list private module routines
!PUBLIC TYPES:
!REMARKS:
!TO DO:

And here is a full list of the keywords:

!BOI     begin/end of introduction
!EOI

!BOP     begin/end of prologue
!EOP

!BOPI    begin/end of internal prologue
!EOPI

!BOC     code
!EOC

!BOE     example prologue
!EOE

!QUOTE:
!TITLE:
!AUTHORS:
!AFFILIATION:
!DATE:
!INTRODUCTION:
!ROUTINE:
!MODULE:
!INCLUDE:
!IROUTINE:        internal routine
!CROUTINE:        contained routine
!FUNCTION:
!METHOD:
!CLASS:  
!INTERFACE:
!USES:
!PUBLIC TYPES:
!PRIVATE TYPES:
!PUBLIC MEMBER FUNCTIONS:
!PRIVATE MEMBER FUNCTIONS:
!PUBLIC DATA MEMBERS:
!PARAMETERS:
!ARGUMENTS:
!IMPORT STATE:
!EXPORT STATE:
!INTERNAL STATE:
!DEFINED PARAMETERS:
!INPUT PARAMETERS:
!INPUT/OUTPUT PARAMETERS:
!OUTPUT PARAMETERS:
!RETURN VALUE:
!REVISION HISTORY:
!BUGS:
!SEE ALSO:
!SYSTEM ROUTINES:
!FILES USED:
!REMARKS:
!TO DO:
!CALLING SEQUENCE:
!AUTHOR:
!CALLED FROM:
!LOCAL VARIABLES: 


Installing ProTex

If not part of your TM5 installation, or for a standalone installation independent of TM5, you can get the tools/protex directory from the TM5 repository. For example, to check it out in a protex directory in your home:

svn co https://svn.knmi.nl/svn/TM5/tools/protex  ~/protex

This will give you some examples/templates for your own documentation, along the ProTex script.

Automatic insertation of protex keywords

The protex tools from TM5 also provide you with a general script that automatically add standard ProTex keywords to your code at (almost) the correct place! Give it a try:

addprotex myFile.F90

See README for details if something when wrong even when you specify all the paths.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox