tepam::doc_gen(3tTcl's Enhanced Procedure and Argument Mantepam::doc_gen(3tcl)
______________________________________________________________________________
NAME
tepam::doc_gen - TEPAM DOC Generation, reference manual
SYNOPSIS
package require Tcl 8.3
package require tepam 0.5
package require tepam::doc_gen ?0.1?
tepam::doc_gen::generate ?-format format? ?-style style?
?-header_footer? ?-dest_file dest_file? name
tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern
search_pattern? ?-src_string src_string | -src_file src_file?
?-dest_file dest_file? ?name?
______________________________________________________________________________
DESCRIPTION
This package generates documentations of TEPAM procedures (procedures
that have been declared with tepam::procedure). The documents are gen-
erated in the classic UNIX document style using the following document
sections: Name, Synopsis, Description, Arguments and Example. TEPAM Doc
Gen provides support for various document formats. Support for addi-
tional formats can be added if necessary.
The TEPAM Doc Gen package provides the following commands:
tepam::doc_gen::generate ?-format format? ?-style style?
?-header_footer? ?-dest_file dest_file? name
This command generates the documentation for a specified proce-
dure (name) in one of the supported formats (TXT, HTML, POD
(Perl Doc), DT (TclLib DocTool), or in a custom specific format.
The format is specified via ?format?. The flag ?-header_footer?
adds to the documentation file header and footer. If ?dest_file?
is specified the documentation is stored in a file (the file
header and footer are added automatically in this case) and the
file name is returned. Otherwise the documentation string is re-
turned by generate.
tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern
search_pattern? ?-src_string src_string | -src_file src_file?
?-dest_file dest_file? ?name?
This command inserts procedure documentations into an existing
master document at the locations indicated by insertion place-
holders which are matching the pattern of ?search_pattern?. The
existing master document is either provided as data to the argu-
ment (?src_string?) or via a file (?src_file?). The final docu-
ment is returned by patch if no destination file is defined
(?dest_file?). Otherwise, the document is stored in the speci-
fied file, and the number of insertion placeholders that could
be handled successfully is returned.
Any insertion placeholders of the master document are handled by
default. By defining the argument ?name? the documentation in-
sertion will be restricted to a particular procedure.
ARGUMENTS
?-format format?
Specifies the documentation format. TEPAM Doc Gen provides sup-
port for the following formats:
o TXT - Text format (default)
o HTML
o POD - Perl Plain Old Documentation format (PerlPOD)
o DT - TclLib DocTool format
Section ADDING SUPPORT FOR NEW DOCUMENT FORMATS shows how sup-
port for additional formats can be added.
?-style style?
The documentation is by default generated in Tcl style (e.g.
command arg1 arg2 ...). C-style documentation can be generated
by setting this argument to 'C' (e.g. command(arg1,arg2,...)).
?-dest_file dest_file?
If ?dest_file? is defined the documentation is written into the
specified destination file. Otherwise the documentation string
is returned by the commands generate and patch.
name / ?name?
This is the name of the procedure for which the documentation
has to be generated. This is a mandatory argument for generate,
but an optional argument for patch.
?-header_footer?
Generate adds to the generated procedure documentation the file
header and footer only if a file is generated. By selecting the
flag ?-header_footer? the header and footer are also generated
if the documentation is returned as string by generate.
?-src_string src_string | -src_file src_file?
Patch inserts procedure documentations into an existing document
that is either provided as string to the argument (?src_string?)
or as a file (?src_file?). One of these two arguments need to be
specified.
?-search_pattern search_pattern?
The argument ?search_pattern? defines the documentation inser-
tion placeholder used in a document. It is a regular expression
accepted by regexp and needs to contain a parenthesized sub-ex-
pression that contains the procedure name for which the documen-
tation needs to be inserted.
The default insertion placeholder pattern is \{!(.*?)!\}, which
means that the procedure name will be embedded between {! and
!}. The section EXAMPLES contains a custom insertion placeholder
pattern example.
PREDEFINED DOCUMENT FORMATS
TEPAM Doc Gen pre-defines the following document formats:
TXT - TEXT FORMAT
The documentation will be generated in a simple text format if this
format is selected. The format can be customized via the following
variable:
tepam::doc_gen::Option(TXT,MaxLineLength)
Default: 80
This variable defines the line wrapping limit (character posi-
tion).
HTML - HTML FORMAT
TEPAM Doc Gen generates CSS styled HTML files. The HTML documentation
can be customized via the following variable:
tepam::doc_gen::Option(HTML,CssFile)
Default: "tepam_doc_stylesheet.css"
This variable specifies the CSS stylesheet file that is referred
by the generated HTML files.
The CSS stylesheet can be customized to change the documentation for-
matting. A good starting point to create a customized CSS stylesheet is
to use the CSS file provided by the TEPAM Doc Gen example/demo. The
HTML documentation uses the following CSS class styles:
o h1.tepam_page_title - Document page title. Only used by generate
if a file is created or if the header and footer are built (flag
?-header_footer? selected).
o div.tepam_command_help - Documentation container. The entire
procedure documentation is placed inside this container.
o p.tepam_section_title - Section title (e.g. Name, Synopsis, De-
scription, ...)
o p.tepam_sub_section_title - Sub-section title (used to separate
the documentation of multiple sub-procedures)
o p.tepam_name - Name section
o p.tepam_synopsis - Synopsis section
o p.tepam_description - Single description paragraph
o ul.tepam_description_list - Item of a HTML bulleted/unordered
list inside the description section
o dt.tepam_argument - Item of a HTML description list used to list
the procedure arguments
o p.tepam_argument_description - Argument description paragraph
o p.tepam_argument_attribute - Argument attribute line
o pre.tepam_example - Example section
POD - PERL DOCUMENT FORMAT
The documentation is generated in the Perl Plain Old Documentation for-
mat (PerlPOD) if this format is selected.
DT - TCLLIB DOCTOOLS FORMAT
The documentation is generated in the Tcllib DocTools format if this
format is selected.
ADDING SUPPORT FOR NEW DOCUMENT FORMATS
Support for a new document format can be added by defining in the
tepam::doc_gen namespace a set of procedures that generate the differ-
ent document components.
The following documentation listing contains tokens that refer to the
different document generation procedures:
<01>
<03> <20s> NAME<20e>
<30s> message_box - Displays text in a message box<30e>
<20s> SYNOPSYS<20e>
<40s> message_box [-mtype <mtype>] <text><40e>
<20s> DESCRIPTION<20e>
<21s> message_box<21e>
<54s> message_box [-mtype <mtype>] <text><54e>
<50s> This procedure allows displaying a text in an message box. The following
message types are supported:<50e>
<51> <53s> * Info<53e>
<53s> * Warning<53e>
<53s> * Error<53e> <52>
<50s> If the text parameter is use multiple times the different texts are
concatenated to create the message text.<50e>
<20s> ARGUMENTS<20e>
<60> <62s> [-mtype <mtype>]<62e>
<63> <65s> Message type<65e>
<66s> Default: "Warning"<66e>
<66s> Multiple: yes<66e>
<66s> Choices: Info, Warning, Error<66e> <64>
<62s> <text><62e>
<63> <65s> One or multiple text lines to display<65e>
<66s> Type: string<66e>
<66s> Multiple: yes<66e> <64><61>
<20s> EXAMPLE<20e>
<70> <72s> message_box "Please save first the document"<72e>
<73s> -> 1<73e> <71><04>
<02>
There are 2 types of document generation procedures:
Content generation procedures (e.g. <40s>...<40e>)
These procedures generate some document content based on the
text that is provided as procedure argument. The listing above
shows two tokens for these procedures to indicate the beginning
and the end of the generated content.
Control generation procedures (e.g. <03>)
These procedures generate control constructs, for example to
generate the prolog code and epilog code for lists, sections,
etc. These procedures have no argument.
The following set of procedures needs to be defined to provide support
for a new document format:
01 - gen($Format,Header) {Text}
Only called if doc_gen generates a file or if it is called with
the flag ?-header_footer?. The procedure creates the file
header. The provided parameter is the procedure name for which
the documentation has to be generated.
02 - gen($Format,Footer) {Text}
Only called if doc_gen generates a file or if it is called with
the flag ?-header_footer?. The procedure creates the file
footer.
03 - gen($Format,Begin) {}
Generates the documentation prolog (preamble)
04 - gen($Format,End) {}
Generates the documentation epilog
20 - gen($Format,SectionTitle) {Text}
Generates a section title (e.g. Name, Synopsis, Description,
...). The raw title text is provided as parameter
21 - gen($Format,SubSectionTitle) {Text}
Generates a sub-section title. Sub-sections are used if a single
documentation is generated for multiple sub-commands to make a
separation between them. The raw title text is provided as pa-
rameter
30 - gen($Format,Name) {Text}
Generates the name section (without title). The raw section text
is provided as parameter.
40 - gen($Format,Synopsis) {Text}
Generates the synopsis section (without title). The section text
provided as parameter is pre-formatted (the argument strings are
generated by gen($Format,ArgumentString)).
50 - gen($Format,Description) {Text}
Generates a description paragraph. The raw paragraph text is
provided as parameter.
51 - gen($Format,DescriptionListBegin) {}
Generates the prolog of a bulleted/unordered list inside the de-
scription section. This prolog is usually the start code of a
list structure.
52 - gen($Format,DescriptionListEnd) {}
Generates the epilog of a bulleted/unordered list inside the de-
scription section. This epilog is usually the end code of a list
structure.
53 - gen($Format,DescriptionListItem) {Text}
Generates a text item in a bulleted/unordered description list.
The raw item text is provided as parameter.
54 - gen($Format,DescriptionSynopsis) {Text}
Generates the synopsis line on the beginning of the description
section. The command can return an empty string if no synopsys
line is required at this place.
Some formats (e.g. Tcl DocTools) require that the synopsis line
is defined in the description section, to build then automati-
cally the synopsis section. The section text provided as parame-
ter is pre-formatted (the argument strings are generated by
gen($Format,ArgumentString)).
60 - gen($Format,ArgumentListBegin) {}
Generates the prolog of argument list (definition/non-bulleted
list). This prolog is usually the start code of a definition
list.
61 - gen($Format,ArgumentListEnd) {}
Generates the epilog of the argument list. This epilog is usu-
ally the end string of a list structure.
62 - gen($Format,ArgumentListItem) {Name IsOptional IsNamed Type}
Generates an argument item line inside the argument list. This
command can rely on gen($Format,ArgumentDetailBegin) since the
parameters are identical.
63 - gen($Format,ArgumentDetailBegin) {}
Generates the argument details prolog (preamble).
64 - gen($Format,ArgumentDetailEnd) {}
Generates the argument details epilog
65 - gen($Format,ArgumentDescription) {Text}
Generates the argument description (single paragraph).
66 - gen($Format,ArgumentAttribute) {Text}
Generates a single argument attribute string. The command is
called individually for each attribute.
70 - gen($Format,ExampleBegin) {}
Generates the example section prolog (preamble)
71 - gen($Format,ExampleEnd) {}
Generates the example section epilog
72 - gen($Format,ExampleCommandLine) {Text}
Generates a single command line in the example section. The com-
mand is called for each individual command line.
73 - gen($Format,ExampleResultLine) {Text}
Generates a command result line
80 - gen($Format,ArgumentString) {Name IsOptional IsNamed Type}
Generates the part of the command line or the synopsis that is
specific to an argument. The generated string has to indicate if
an argument is optional, named and if it is a flag.
The following parameters are provided to this procedure:
Name Name of the argument
IsOptional
If true (=1) the argument is optional which should be in-
dicated by the generated string (for example by putting
the argument into brackets {[]} or into question marks
'?'):
gen(TXT,ArgumentString) mtype 1 0 string -> "[mtype]"
IsNamed
If true (=1) an argument is a named argument (option).
The generated string should in this case contain the ar-
gument/option name, followed by the argument itself:
gen(TXT,ArgumentString) mtype 0 1 string -> "-mtype <mtype>"
Named arguments can also be optional:
gen(TXT,ArgumentString) mtype 1 1 string -> "[-mtype <mtype>]"
Type Indicates the type of the argument. If the type is set to
none the argument is a flag, which needs to be indicated
by the generated string. Example:
gen(TXT,ArgumentString) close 1 1 none -> "[-close]"
EXAMPLES
TEPAM::DOC_GEN::GENERATE
The TEPAM Doc Gen package can be explored by generating the documenta-
tion of the command tepam::doc_gen::generate. The following example
generates the document in text format (default format):
tepam::doc_gen::generate tepam::doc_gen::generate
The next example generates the documentation in HTML format:
tepam::doc_gen::generate -format HTML tepam::doc_gen::generate
The flag ?header_footer? adds also the file header and footer:
tepam::doc_gen::generate -format HTML -header_footer tepam::doc_gen::generate
The documentation can directly be stored in a file. The file header and
footer are automatically generated in this way:
tepam::doc_gen::generate -format HTML -dest_file doc_gen.html tepam::doc_gen::generate
The generated HTML file refers a CSS stylesheet file (default:
tepam_doc_stylesheet.css). To display the HTML file correctly this CSS
stylesheet file needs to be copied into the directory of the generated
HTML file.
The Tcl DOC Tools format can be used as intermediate format to generate
other formats, for example HTML:
# Generate the documentation in Tcl Doc Tool format
set dt [tepam::doc_gen::generate -format DT -header_footer tepam::doc_gen::generate]
# Create a new doc tools object (HTML format)
package require doctools
::doctools::new myDoc -format html
# Open the HTML file, and write the HTML formatted documentation
set fHtml [open doc_gen.dt.html w]
puts $fHtml [myDoc format $dt]
close $fHtml
TEPAM::DOC_GEN::PATCH
While generate provides a limited number of possibilities to vary the
document structure, patch offers more flexibility. Multiple documenta-
tions for different procedures and meta information can for example be
added.
The following listing shows how the patch command works. It defines
first a HTML master document string that contains 2 procedure documen-
tation placeholders ({*<ProcedureName>*}). There placeholders are re-
placed by patch with the generated documentation of the referred proce-
dures. Since nonstandard placeholders are used, patch is called with an
explicit placeholder pattern definition (argument search_pattern).
# Define the HTML master document
set HtmlMasterDoc {\
<html>
<head>
<title>tepam::doc_gen</title>
<link rel="stylesheet" href="tepam_doc_stylesheet.css">
<meta content="documentation" name="keywords"></meta>
</head>
<body>
<h1>tepam::doc_gen</h1>
<h2>Generate</h2>
{*tepam::doc_gen::generate*}
<h2>Patch</h2>
{*tepam::doc_gen::patch*}
</body>
<html>\
}
# Patch the master document: This will replace the placeholders by the
# procedure documentation divisions:
tepam::doc_gen::patch -format HTML -search_pattern {\{\*(.*?)\*\}} \
-src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html
SEE ALSO
tepam(3tcl), tepam::procedure(3tcl)
KEYWORDS
automatic documentation, documentation, procedure documentation
CATEGORY
Documentation tools
COPYRIGHT
Copyright (c) 2013, Andreas Drollinger
tcllib 0.5.0 tepam::doc_gen(3tcl)