Tornado Reference : Tornado Utilities
refgen - Tornado Reference documentation generator
refgen [-book bookName] [-chapter chapterName] [-config configFile] [-cpp] [-expath pathList] [-exbase basedir] [-h] [-int] [-l logFile] [-mg] [-out outDir] [-verbose] fileList
This tool implements a table-driven process for extraction of documentation from source. Input tables define a "meta-syntax" that specifies the details of how documentation is embedded in source files for a particular programming language. Similarly, output tables define the mark-up details of the documentation output.
Some conventions about how documentation is embedded in source code do not depend on the source language, and can therefore not be changed from the configuration tables.
Routines are organized into libraries, and each library begins with a DESCRIPTION section. If a DESCRIPTION heading is not present, the description section is taken to be the first comment block after the modification history. Some input languages (such as shellscript) may optionally begin with a section headed SYNOPSIS instead.
The first line in a library source file is a one-line title in the following format: sourceFileName - simple description
That is, the line begins (after whatever start-of-comment character is required) with the name of the file containing it, separated by space, hyphen, and space from a simple description of the library.
The first line in a routine's description (after the source-language-dependent routine delimiter) is a one-line title in the same format.
Routine descriptions are taken to begin after the routine-title line, whether or not a DESCRIPTION tag is present explicitly.
Section headings are specified by all-caps strings beginning at a newline and ending with either a newline or a colon.
Italics, notably including Text variables--that is, words in the documentation that are not typed literally, but are instead meant to be replaced by some value specific to each instance of use--are marked in the source by paired angle brackets. Thus, to get the output textVar, type <textVar>.
Boldface words are obtained as follows: General mechanism: surround a word with single quotes in the source. Special words: words ending in "Lib" or in a recognized filename suffix are automatically rendered in bold. For example, fileName.c, object.o, myStuff.tcl all appear in boldface.
Simple lists can be constructed by indenting lines in the source from the margin (or from the comment-continuation character, if one is required in a particular source language). For example: line one line two
Library descriptions are automatically prefaced by a synopsis of the routines in that library, constructed from the title lines of all routines.For most input languages, a SYNOPSIS section is supplied automatically for each routine as well, extracted from the routine definition in a language-dependent manner specified in the input meta-syntax tables. Input languages that do not support this have empty strings for $SYNTAX(declDelim); in such languages, the SYNOPSIS section must be explicitly present as part of the subroutine comments.
For some languages, the routine definition is also used to create a PARAMETERS section automatically.
The online form of documentation is assumed to fit into a structure involving a parent file (which includes a list of libraries) and a routine index. Several of the procedures in this library require names or labels for these files, in order to include links to them in the output. The parent file and routine index need not actually exist at the time that procedures in this library execute.
DESCRIPTION tags are supplied automatically for all description sections, whether or not the tag is present in the source file.
SEE ALSO sections are always present in the output for routine descriptions, whether or not they are present in the source. SEE ALSO sections for routine descriptions automatically include a reference to the containing library.
The following keywords, always spelled in all capital letters and appearing at the start of a line, alter the text that is considered for output. Some directives accept an argument in a specific format, on the same line.
- NOROUTINES
- Do not generate subroutine documentation from this file (must appear in the library section).
- NOMANUAL
- Suppresses the section where it appears: either an entire routine's documentation, or the library documentation. Routine documentation can also be suppressed in language-specific ways, specified by matching a regular expression in the meta-syntactic list LOCALdecls. See refDocGen for a command line option that overrides this.
- INTERNAL
- Suppresses a section (that is, all text from the directive until the next heading, if any). See refDocGen for a command line option that overrides this.
- APPEND filename
- Include documentation from filename in the output as if its source were appended to the file containing the APPEND keyword.
refgen supports a simple markup language that is meant to be inconspicuous in source files, while supporting most common output needs.
The following table summarizes refgen explicit markup (numbered notes appear below the table):
Note Markup Description \" text to end of line Comment in documentation. 'text ...' or `text ...' Boldface text. <...> Italicized text. [1] \\ or \/ The character \. [2] \< \> \ \` \' The characters < > ` '. \| The character | within a table. [3] \ss ... \se Preformatted text. \cs ... \ce Literal text (code). \bs ... \be Literal text, with smaller display. [4] \is \i ... \i ... \ie Itemized list. [5] \ml \m ... \m ... \me Marker list. [6] \ts ... \te A table. \sh text A subheading. \tb reference A reference followed by newline.
[1] The escape sequence \\ is easier to remember for backslash, but \/ is sometimes required if the literal backslash is to appear among other text that might be confused with escape sequences. \/ is always safe.
[2] < and > must be escaped to distinguish from embedded HTML tags. must be escaped to distinguish from HTML character entities. Single quotes must be escaped to distinguish from the refgen automatic bolding convention.
[3] Newlines and whitespace are preserved between \ss and \se, but formatting is not otherwise disabled. These are useful for including references to text variables in examples.
[4] \is and \ie mark the beginning and end of a list of items. \i is only supported between \ls and \le. It marks the start of an item: that is, it forces a paragraph break, and exempts the remainder of the line where it appears from an increased indentation otherwise applied to paragraphs between \is and \ie. Thus, the following:
\is \i Boojum A boojum is a rare tree found in Baja California. \i Snark A snark is a different matter altogether. \ieYields output approximately like the following:
- Boojum
- A boojum is a rare tree found in Baja California.
- Snark
- A snark is a different matter altogether.
[5] \ml and \me delimit marker lists; they differ from itemized lists in the output format--the marker beside \m appears on the same line as the start of the following paragraph, rather than above.
[6] Between \ts and \te, a whole region of special syntax reigns, though it is somewhat simplified from the original mangen's table syntax. Three conventions are central:
(a) Tables have a heading section, and a body section; these are delimited by a line containing only the characters - (hyphen), + (plus) and | (stile or bar), and horizontal whitespace.
(b) Cells in a table, whether in the heading or the body, are delimited by the | character. \| may be used to represent the | character.
(c) Newline marks the end of a row in either heading or body.
Thus, for example, the following specifies a three-column table with a single heading row:
\ts Key | Name | Meaning ----|------------|------------ | ampersand | bitwise AND \| | stile | bitwise OR # | octothorpe | bitwise NAND \teThe cells need not align in the source, though it is easier to read it (and easier to avoid errors while editing) if they do.
Key Name Meaning ampersand bitwise AND | stile bitwise OR # octothorpe bitwise NAND
-book - This option allow to define which book the documented routine / library will belong to. The default value is "Wind River Systems Reference Manual" -chapter - Related to the -book option, this option allows to set the documented routine / library chapter. The default value is set to "Wind River Systems Reference Libraries" -category - Related to the -book option, this option allows to set the documented routine / library category. It can be used for example to differentiate routines available for different host platforms -config configname - Read configuration information from the file configname if this optional parameter is present, the default configuration is C2html -cpp - This option specifies that the list of given files is to be treated as C++ files. A special processing is then done to recover from all the class members -expath pathList - Preempt EXPANDPATH settings recorded within files with the explicitly-supplied colon-delimited path list -exbase basedir - To simplify working under incomplete trees, use basedir rather than WIND_BASE as the root for expand-file searching -int - If this optional parameter is present, format all available documentation, even if marked INTERNAL or NOMANUAL, and even for local routines -l logFile - specifies that logFile is to be used to log refgen errors, if -l option is not specified, the stdandard output is used -mg - Convert from mangen markup "on the fly" (in memory, without saving the converted source file) -out outputDirectoryName - Save output documentation file in outputDirectoryName -verbose - Print reassuring messages to indicate something is happening sourceFileList - Any other parameters are taken as names of source files from which to extract and format documentation.
Generate HTML manual pages for a BSP sysLib.c file:
% cd $WIND_BASE/target/config/myBsp % refgen -mg -book BSP_Reference -chapter <myBsp> -category <myBsp> \ -out $WIND_BASE/vxworks/bsp/myBsp sysLib.c
refLib.tcl
refgen, VxWorks Programmer's Guide: Coding Conventions, htmlLink, htmlBook, windHelpLib