docfor is an automatic documentation-maker perl script which is invoked like this, for example, from the ../doc directory:
docfor ../src/*.fIt produces an html file for each routine and a file "buttons.html", which consists of a button and file reference for each routine's html file.
Searches are case-insensitive with optional spaces permitted between words.
DOUBLE PRECISION FUNCTION INTEGER FUNCTION REAL FUNCTION LOGICAL FUNCTION SUBROUTINE BLOCK DATA
These occur in a comment; searches are case-insensitive.
DESCRIPTION: -- 1st or 2nd word in line RETURNS: -- 1st or 2nd word in line CONDITIONS: -- 1st or 2nd word in line PURPOSE: -- 1st or 2nd word in line AUTHOR: -- 1st or 2nd word in line VALUE: -- 1st or 2nd word in line FUNCTIONAL -- 1st word in line onlyThis list is based on brief experience with what works, and will likely expand as needed. Mispellings are not recognized.
docfor attempts to be flexible in recognizing documentation headers at the beginnings of FORTRAN routines. It recognizes all of the FORTRAN routine definitions, including blockdata, but does require a function to be type-declared, as per the STAR coding style manual. It is flexible as regards spacing, provided words themselves aren't broken up (ie, INTEGER FUNC TION wouldn't work, even though it's legal FORTRAN). All searches are case-insensitive with optional spacing between words in multi-word searches.
Once it sees the start of a routine, it goes into "header mode", and just copies the lines from the routine into the html file until it decides the header is done. It makes that decision by first "arming" on any of several arming-words, occuring as the first or second word on a line. Those that require a colon permit optional spaces between the word and the colon. Once armed, the first non-comment line terminates "header mode", and it starts looking for the next routine (blank lines and form feeds are comments).
docfor permits actual declaration statements to become part of the document, including parameter and include statements, provided they occur in certain places, which is after the routine-definition statement and before a comment containing one of the arming-words in the right place.
If it encounters an "=" before an inline comment character on a line (and not part of a parameter statement); or an END statement; or an EOF, it spits out a warning message, then exits "header mode" and continues. It doesn't just stop on the first non-comment, since this way it can incorporate "working comment" argument declarations.
The html files consist of a highlighted routine-declaration, with all its arguments, and continued if that's how it's written in the *.f file. The rest of the header is just encapsulated in an "as-is" block, and appears as in the source.
In addition to these html files, docfor also produces a "buttons" file, named buttons.html, consisting of a line for each routine found which refers to the corresponding html file for that routine. The button is named after the routine itself, stripped clean and case-preserved (the *.html filenames are all lower-cased), and is appended with a one-line description if the routine was written with a line containing:
Brief description: This routine does something.The "brief description:" is required, with no alternatives at the moment. The "Brief Desription:" portion is stripped off and not put in the buttons file. docfor also prints a line on the terminal for each routine found, as well as error messages when docfor determines that it's confused.
The buttons.html file should get renamed or incorporated somewhere else, with perhaps a minimal of editting, such as to eliminate reference to some routines, if desired. Several buttons.html files, corrsponding to multiple routine-documentation lists, may be generated, with each buttons.html file renamed or included before the next step is started.
Generally, when docfor makes an error it's because an end-header arming-word is absent, and it does well there, too, in not incorporating very much code before it figures out that it's not in the header anymore. And of course it prints warnings for these cases.
Once the various *.html files are produced, and the buttons.html file renamed or incorporated, the documentor has only to put things in the right place for WWW.