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.
You can first look at examples in the most recent TM5 code, or at
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:
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
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:
See README for details if something when wrong even when you specify all the paths.