Tornado Reference : Tornado Utilities

refgen

NAME

refgen - Tornado Reference documentation generator

SYNOPSIS

   refgen [-book bookName] [-chapter chapterName] [-config configFile]
          [-cpp] [-expath pathList] [-exbase basedir] [-h] [-int] [-fname]
          [-l logFile] [-mg] [-out outDir] [-sort] [-verbose] fileList

DESCRIPTION

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.

OVERALL CONVENTIONS

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.

Overall Input Conventions

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

Overall Output Conventions

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.

OUTPUT DIRECTIVES

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).

NO MANUAL (one word)

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. This is especially useful when a library has been broken into several pieces for manageability, but still constitutes one logical library. Note that this directive is merely a text substitution. If you append a file in a different directory, then further APPEND or EXPAND directives, may give unexpected results.

EXPAND filename typename

Extract the definition of typename (either a struct or an enum) from the header file filename. If filename begins with a slash (/), its path root is WIND_BASE unless overridden with the -exbase option. Otherwise, refgen searches for filename in its EXPANDPATH list, which defaults to the current working directory.

EXPANDPATH pathname

Sets the list of directories to be searched when processing an EXPAND directive. If pathname begins with a slash (/), its path root is WIND_BASE unless overridden with the -exbase option. Otherwise, pathname is appended to the current working directory. If no EXPANDPATH directive is supplied, the list consists of only the current working directory. Only one EXPANDPATH directive is legal, and it should appear before any EXPAND directives, preferably in the library description. Note that the current working directory is not automatically added to an explicit EXPANDPATH. Note also, that if there is more than one header file with the same name, refgen searches those files until it finds a type definition or runs out of files.

Examples:

APPEND long2Lib.c

Adds the text of long2Lib.c to the end of the file.

EXPANDPATH .:/target/h:/target/h/sys

Defines the search path to be .:$WIND_BASE/target/h:$WIND_BASE/target/h/sys

EXPANDPATH target/h:target/h/sys:.

Defines the search path to be ./target/h:./target/h/sys:.

EXPAND taskLib.h WIND_LCB

Causes refgen to look for a type definition for WIND_LCB in each taskLib.h in the EXPANDPATH until it finds one.

EXPAND ../../h/taskLib.h WIND_LCB

Without any EXPANDPATH statement, refgen takes the relative path from the current working directory (this example would presumably refer to $WIND_BASE/target/h/taskLib.h), but if an EXPANDPATH statement does exist, it looks relative to each of the directories in that list.

EXPLICIT MARKUP

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.

Notes on Markup

[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. \ie Yields 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 \te Key Name Meaning ampersand bitwise AND | stile bitwise OR # octothorpe bitwise NAND The cells need not align in the source, though it is easier to read it (and easier to avoid errors while editing) if they do.

PARAMETERS

-book	-	This option allow to define which book the documented routine/library will belong to. The default value is "VxWorks API Reference"
-chapter	-	Related to the -book option, this option allows to set the documented routine / library chapter. The default value is set to "VxWorks 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	-	configname is of the form in-format2out-format, where in-format is the file type (valid options are Auto, Asm, bsp, C, Cpp, CTcl, File, Java, Pcl, sh, and Tcl) The Auto option deduces the file type from the file extension. out-format can be any of default, html, or txt. The default option is html. The default for configname is Auto2default. A file with a name formatted like configname must exist for the actual configuration refgen attempts after any automatic selection and defaults.
-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
-dependencies	-	Do not process input files, but print the dependency part of the build rule for the input file.
-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
-fname	-	Include the file name in the help entry description. This will help to identify the library name in the help cross reference entries.
-int	-	If this optional parameter is present, format all available documentation, even if marked INTERNAL or NO MANUAL, 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)
-nameOutFile	-	Same as -dependencies. (Deprecated)
-out outputDirectoryName	-	Save output documentation file in outputDirectoryName
-sort	-	sorts the routines list (if any). This makes the generated doc file have the routines sorted alphabetically
-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

EXAMPLE

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

INCLUDES

refLib.tcl

SEE ALSO

VxWorks Programmer's Guide: C Coding Conventions, htmlLink, htmlBook, windHelpLib