📄 refgen.html
字号:
<html><head><!-- /vobs/wpwr/docs/tornado/hutils/refgen.html - generated by refgen from ../../resource/doctools/refgen.tcl --> <title> refgen </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.html"><i>Tornado Reference : Tornado Utilities</i></a></p></blockquote><h1>refgen</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>refgen</strong> - Tornado Reference documentation generator</p></blockquote><h4>SYNOPSIS</h4><blockquote><p>refgen [-book <i>bookName</i>] [-chapter <i>chapterName</i>] [-config <i>configFile</i>][-cpp] [-expath <i>pathList</i>] [-exbase <i>basedir</i>] [-h] [-int] [-l <i>logFile</i>] [-mg] [-out <i>outDir</i>] [-verbose] <i>fileList</i><p></blockquote><h4>DESCRIPTION</h4><blockquote><p><p>This tool implements a table-driven processfor extraction of documentation from source. Input tables define a"meta-syntax" that specifies the details of how documentation isembedded in source files for a particular programming language.Similarly, output tables define the mark-up details of thedocumentation output.<p></blockquote><h4>OVERALL CONVENTIONS</h4><blockquote><p>Some conventions about how documentation is embedded in source codedo not depend on the source language, and can therefore not bechanged from the configuration tables.<p></blockQuote><h4>Overall Input Conventions</h4><blockQuote><p>Routines are organized into <i>libraries</i>, and each librarybegins with a DESCRIPTION section. If a DESCRIPTION heading isnot present, the description section is taken to be the firstcomment block after the modification history. Some input languages(such as shellscript) may optionally begin with a section headedSYNOPSIS instead.<p>The first line in a library source file is a one-line titlein the following format:<i>sourceFileName</i> - <i>simple description</i><p>That is, the line begins (after whatever start-of-comment characteris required) with the name of the file containing it, separated byspace, hyphen, and space from a simple description of the library.<p>The first line in a routine's description (after thesource-language-dependent routine delimiter) is a one-line title inthe same format.<p>Routine descriptions are taken to begin after the routine-title line,whether or not a DESCRIPTION tag is present explicitly.<p>Section headings are specified by all-caps strings beginning at anewline and ending with either a newline or a colon. <p>Italics, notably including <i>Text variables</i>--that is, words in thedocumentation that are not typed literally, but are instead meant to be replaced by some value specific to each instance of use--are marked in thesource by paired angle brackets. Thus, to get theoutput <i>textVar</i>, type <b><textVar></b>.<p>Boldface words are obtained as follows: <b>General mechanism:</b> surround a word with single quotes in thesource.<b>Special words:</b> words ending in "Lib" or in a recognized filenamesuffix are automatically rendered in bold. For example, <b>fileName.c</b>,<b>object.o</b>, <b>myStuff.tcl</b> all appear in boldface.<p>Simple lists can be constructed by indenting lines in the sourcefrom the margin (or from the comment-continuation character, if oneis required in a particular source language). For example:line oneline two<p></blockQuote><h4>Overall Output Conventions</h4><blockQuote>Library descriptions are automatically prefaced by a synopsis ofthe routines in that library, constructed from the title lines ofall routines.<p>For most input languages, a <b>SYNOPSIS</b> section is suppliedautomatically for each routine as well, extracted from the routinedefinition in a language-dependent manner specified in the inputmeta-syntax tables. Input languages that do not support this haveempty strings for <b>$SYNTAX(declDelim)</b>; in such languages, the<b>SYNOPSIS</b> section must be explicitly present as part of thesubroutine comments.<p>For some languages, the routine definition is also used to createa <b>PARAMETERS</b> section automatically.<p>The online form of documentation is assumed to fit into astructure involving a parent file (which includes a list oflibraries) and a routine index. Several of the procedures in thislibrary require names or labels for these files, in order to includelinks to them in the output. The parent file and routine index neednot actually exist at the time that procedures in this libraryexecute.<p><b>DESCRIPTION</b> tags are supplied automatically for all descriptionsections, whether or not the tag is present in the source file.<p><b>SEE ALSO</b> sections are always present in the output for routinedescriptions, whether or not they are present in the source. SEEALSO sections for routine descriptions automatically include areference to the containing library. <p></blockquote><h4>OUTPUT DIRECTIVES</h4><blockquote><p>The following keywords, always spelled in all capital lettersand appearing at the start of a line, alter the text thatis considered for output. Some directives accept an argumentin a specific format, on the same line.<p><dl><dt><b>NOROUTINES</b><dd>Do not generate subroutine documentation from this file (must appear in the library section).<dt><b>NOMANUAL</b><dd>Suppresses the section where it appears: either an entire routine'sdocumentation, or the library documentation. Routine documentationcan also be suppressed in language-specific ways, specified bymatching a regular expression in the meta-syntactic list<b>LOCALdecls</b>. See <b>refDocGen</b> for a command line option thatoverrides this.<dt><b>INTERNAL</b><dd>Suppresses a section (that is, all text from the directive until thenext heading, if any). See <b>refDocGen</b> for a command line optionthat overrides this.<dt><b>APPEND</b> <i>filename</i><dd>Include documentation from <i>filename</i> in the output as if its sourcewere appended to the file containing the <b>APPEND</b> keyword.</dl></blockquote><h4>EXPLICIT MARKUP</h4><blockquote><p>refgen supports a simple markup language that is meant to beinconspicuous in source files, while supporting most common outputneeds.<p>The following table summarizes refgen explicit markup (numberednotes appear below the table):<p><table><tr valign=top><th align=left>Note </th><th align=left>Markup </th><th align=left>Description</tr><tr><td colspan="3"><hr></tr><tr valign=top><td align=left></td><td align=left>\" <i>text to end of line</i> </td><td align=left>Comment in documentation.</tr><tr valign=top><td align=left></td><td align=left>'text ...' or `text ...' </td><td align=left>Boldface text.</tr><tr valign=top><td align=left></td><td align=left><...> </td><td align=left>Italicized text.</tr><tr valign=top><td align=left>[1] </td><td align=left>\\ or \/ </td><td align=left>The character \.</tr><tr valign=top><td align=left>[2] </td><td align=left>\< \> \ \` \' </td><td align=left>The characters < > ` '.</tr><tr valign=top><td align=left></td><td align=left>\| </td><td align=left>The character | within a table.</tr><tr valign=top><td align=left>[3] </td><td align=left>\ss ... \se </td><td align=left>Preformatted text.</tr><tr valign=top><td align=left></td><td align=left>\cs ... \ce </td><td align=left>Literal text (code).</tr><tr valign=top><td align=left></td><td align=left>\bs ... \be </td><td align=left>Literal text, with smaller display.</tr><tr valign=top><td align=left>[4] </td><td align=left>\is \i ... \i ... \ie </td><td align=left>Itemized list.</tr><tr valign=top><td align=left>[5] </td><td align=left>\ml \m ... \m ... \me </td><td align=left>Marker list.</tr><tr valign=top><td align=left>[6] </td><td align=left>\ts ... \te </td><td align=left>A table.</tr><tr valign=top><td align=left></td><td align=left>\sh text </td><td align=left>A subheading.</tr><tr valign=top><td align=left></td><td align=left>\tb reference </td><td align=left>A reference followed by newline.</tr><tr valign=top>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -