Table of Contents
!!. You can place a block of comments before a statement to be commented, or after the statement itself. For example:
!! Support for variable-length strings. module stringis equivalent to
module string !! Support for variable-length strings.but not
module string; !! Support for variable-length strings.because here the comment is on a different statement than
You can use free-form continuations to have a multi-line comment block the same statement as the one to be commented. For example:
module string & !! Support for variable-length strings. & !! @version 1.0 !! @author Joe BloggsThis doesn't make much sense for modules, but I find it useful for commenting variables. The before-statement version is:
!! Support for variable-length strings. !! @version 1.0 !! @author Joe Bloggs module stringYou can even use a mix, which may be useful for certain applications:
!! Support for variable-length strings. !! @author Joe Bloggs module string !! @version 1.0
Instead, there is a ``smart'' form for documentation. One or more blank lines
(each optionally prefixed with
!!) indicate a paragraph break.
Lines of text are prefixed by
!!, as already indicated. Line
breaks in the comments do not cause line breaks in the generated output.
A line can be treated as verbatim text by putting a
v is treated as a space, but
otherwise no processing is performed on the line. There is a multiline
verbatim mode using
!!> (begin) and
> are intended to be
v's turned on their side.) Again, the
> characters are treated as spaces, which means the following
has uniform indentation:
!! An example of this module's usage is !!> call copier_read ("input_file") !! call copier_write ("output_file") !!< call copier_closeThe most interesting feature is the list mode. This was designed to look like how people (or myself at least) do ASCII lists. An element of a list is marked with a dash
-after an arbitrary number of spaces. All lists at this level must have the dash at the same indentation. Dashes with more indentation denote nested lists. Text at the same or lesser indentation than the last dash denotes the end of a list. For example:
!! Mouths are defined by the following operations: !! - Eat, which can be performed in two modes, !! - open-mouth or !! - closed-mouth. !! The latter mode is preferred. !! - Chew !! There are more operations, but this serves as an example.This text is formatted in HTML as:
Finally, there are two type-face modifiers, italics and bold
(also known as emphasis and strong, respectively). Italic mode is started with
_ at the beginning of a word, and ended with an
underbar at the end of a word. For example,
big. Underbars within italic text are replaced by spaces, so
_really big_ and
_really_big_ both produce really
big. (Note: italicizing the word ``big'' is not encouraged!)
Similarly, bold mode has the same semantics but uses the character
* instead of
_. Note that multiple lines of
either mode is currently not supported.
@author A. Person
A. Personto the list of authors. Only one author should be provided per
@authorstatement. They are all collected and placed at the end of the comment block.
1.2.3q. There should only be one
@versionstatement per comment block. It is displayed at the end of the comment block, after the authors.
f90docprogram itself is very easy to use. The main option is
-c(p|s|h), described at the bottom. After that, you can specify a list of Fortran 90 files (e.g.,
*.f90if that's expanded by your shell).
You can specify
-free before a group of
Fortran files to specify whether to use fixed or free form. The default is
Before a Fortran 90 file, you can use
-o file.html to specify the
output HTML document, affecting only the next source file. By default, the
HTML documents will be generated in the current directory, and have the names
of the corresponding top-level modules, subroutines, functions, or programs.
An unnamed program will be written to
program.html by default.
specifies the format of the
in the files to be processed.
-cp specifies that comments should
be treated as verbatim (preformatted) text. This always works.
-cs specifies that comments should be formatted
``smartly.'' This is the recommended option, and is
-ch specifies that comments are written in HTML,
htmling.pl, under "
PUBLIC GLOBALS" you can find
$htmling::suppress_calls = 0;
1removes the list of routines called from each unit. This is for if you want backward compatibility.
$htmling::calls_make_links = 0;
1, the list of called routines makes links in the obvious way; i.e., a call to
xyzwill generate a link to
At some point I will get around to cleaning up f90doc in major ways, e.g., making it object-oriented, possibly switching to Python, adding real cross-module linking support, etc. But don't hold your breath. However, I will try to add features (again as time permits) if people make specific requests.