[comment {-*- tcl -*- doctools manpage}]
[manpage_begin doctools_fmt n 1.0]
[copyright {2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
[copyright {2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
[moddesc   {Documentation tools}]
[titledesc {Specification of simple tcl markup for manpages}]
[description]
[para]

This manpage specifies a documentation format for manpages. It is
intended to complement both the [syscmd doctoc] format for writing
tables of contents and the [syscmd docidx] format for writing indices.
See [syscmd doctoc_fmt] and [syscmd docidx_fmt] for the specification
of these two formats.


[para]

This format is called [syscmd doctools].

It provides all the necessary commands to write manpages.

Like for the [syscmd doctoc] and [syscmd docidx] formats a package is
provided implementing a generic framework for the conversion of
[syscmd doctools] to a number of different output formats, like HTML,
TMML, nroff, LaTeX, etc.

The package is called [package doctools], its documentation can be
found in [syscmd doctools].

People wishing to write a formatting engine for the conversion of
[syscmd doctools] into a new output format have to read
[syscmd doctools_api]. This manpage will explain the interface between
the generic package and such engines.


[section OVERVIEW]

[syscmd doctoc] is similar to LaTex in that it consists primarily of
text, with markup commands embedded into it. The format used to mark
something as command is different from LaTeX however. All text between
matching pairs of [lb] and [rb] is a command, possibly with
arguments. Note that both brackets have to be on the same line for a
command to be recognized.

[para]

In contrast to both [syscmd doctoc] and [syscmd docidx] this format
does allow plain text beyond white space. This plain text will be the
contents of the described manpage.


[section {FORMATTING COMMANDS}]
[list_begin bullet]
[bullet]

The main commands are [cmd manpage_begin], [cmd manpage_end],
[cmd moddesc], [cmd titledesc], and [cmd description]. Four of these
five are required for a manpage. The optional command is
[cmd titledesc]. The first two are the first and last commands in a
manpage. Neither text nor other commands may precede
[cmd manpage_begin] nor follow [cmd manpage_end].  The command
[cmd description] separates header and body of the manpage and may not
be omitted.

[nl]

The remaining commands ([cmd moddesc] and [cmd titledesc]) provide
one-line descriptions of module and specific title respectively.

[bullet]
The only text allowed between [cmd manpage_begin] and
[cmd description] is the command [cmd require]. Other commands or
normal text are not permitted. [cmd require] is used to list the
packages the described command(s) depend(s) on for its operation. This
list can be empty.

[bullet]
After [cmd description] text and all other commands are allowed. The
text can be separated into highlevel blocks using named
[cmd section]s.  Each block can be further divided into paragraphs via
[cmd para].

[bullet]
The commands [cmd see_also] and [cmd keywords] define whole sections
named [emph {SEE ALSO}] and [emph KEYWORDS]. They can occur everywhere
in the manpage but making them the last section is the usual thing to
do. They can be omitted.

[bullet]

There are five commands available to markup words, [cmd arg],

[cmd cmd], [cmd opt], [cmd emph] and [cmd strong]. The first three are
used to mark words as [emph {command arguments}], as

[emph {command names}] and as [emph optional]. The other two are
visual markup to emphasize words. The term [emph words] is used in a
loose sense here, i.e application of the commands to a sequence of
words is entirely possible, if they are properly quoted. [emph Note]
that usage of [cmd strong] is discouraged as this command is
deprecated and only present for backwards compatibility

[bullet]

Another set of commands is available to construct (possibly nested)
lists. These are [cmd list_begin], [cmd list_end], [cmd lst_item],
[cmd bullet], [cmd enum], [cmd call], [cmd arg_def], [cmd opt_def],
[cmd cmd_def], and [cmd tkoption_def]. The first two of these begin
and end a list respectively.

[nl]

The argument to the first command denotes the type of the list. The
allowed values and their associated item command are explained later,
in the section detailing the [sectref Commands].

[nl]

The other commands start list items and each can be used only inside a
list of their type. In other words, [cmd bullet] is allowed in
bulletted lists but nowhere else, [cmd enum] in enumerated lists and
[cmd lst_item] and [cmd call] are for definition lists. These two
commands also have some text directly associated with the item
although the major bulk of the item is the text following the item
until the next list command.

[nl]

The last list command, [cmd call] is special. It is used to describe
the syntax of a command and its arguments. It should not only cause
the appropriate markup of a list item at its place but also add the
syntax to the table of contents (synopsis) if supported by the output
format in question. nroff and HTML for example do. A format focused on
logical markup, like TMML, may not.

[bullet]
The command [cmd usage] is similar to [cmd call] in that it adds the
syntax to the table of contents (synopsis) if supported by the output
format. Unlike [cmd call],  this command doesn't add any text to the
output as a direct result of the command. Thus, it can be used
anywhere within the document to add usage information. Typically it is
used near the top of the document, in cases where it is not desireable
to use [cmd call] elsewhere in the document, or where additional usage
information is desired (e.g.: to document a "package require" command).

[list_end]

[section Commands]
[list_begin definitions]

[call [cmd vset] [arg varname] [arg value] ]

Sets the formatter variable [arg varname] to the specified
[arg value]. Returns the empty string.

[call [cmd vset] [arg varname]]

Returns the value associated with the formatter variable
[arg varname].

[call [cmd include] [arg filename]]

Reads the file named [arg filename], runs it through the expansion
process and returns the expanded result.


[call [cmd manpage_begin] [arg command] [arg section] [arg version]]

This command begins a manpage. Nothing is allowed to precede
it. Arguments are the name of the command described by the manpage,
the section of the manpages this manpages lives in, and the version of
the module containing the command. All have to fit on one line.

[call [cmd manpage_end]]

This command closes a manpage. Nothing is allowed to follow it.

[call [cmd moddesc] [arg desc]]

This command is required and comes after [cmd manpage_begin], but
before either [cmd require] or [cmd description]. Its argument
provides a one-line description of the module described by the manpage.

[call [cmd titledesc] [arg desc]]

This command is optional and comes after [cmd manpage_begin], but
before either [cmd require] or [cmd description]. Its argument
provides a one-line expansion of the title for the manpage. If this
command is not used the manpage processor has to use information from
[cmd moddesc] instead.

[call [cmd copyright] [arg text]]

This command is optional and comes after [cmd manpage_begin], but
before either [cmd require] or [cmd description]. Its argument
declares the copyright assignment for the manpage. When invoked more
than once the assignments are accumulated.

[nl]

A doctools processor is allowed to provide auch information too, but a
formatting engine has to give the accumulated arguments of this
command precedence over the data coming from the processor.

[call [cmd description]]

This command separates the header part of the manpage from the main
body. Only [cmd require], [cmd moddesc], or [cmd titledesc] may
precede it.

[call [cmd require] [arg pkg] [opt [arg version]]]

May occur only between [cmd manpage_begin] and [cmd description]. Is
used to list the packages which are required for the described command
to be operational.

[call [cmd section] [arg name]]

Used to structure the body of the manpage into named sections. This
command is not allowed inside of a list or example. It implicitly
closes the last [cmd para]graph before the command and also implicitly
opens the first paragraph of the new section.

[call [cmd para]]

Used to structure sections into paragraphs. Must not be used inside of
a list or example.

[call [cmd see_also] [arg args]]

Creates a section [emph {SEE ALSO}] containing the arguments as
cross-references. Must not be used inside of a list or example.

[call [cmd keywords] [arg args]]

Creates a section [emph KEYWORDS] containing the arguments as words
indexing the manpage. Must not be used inside of a list or example.

[call [cmd arg] [arg text]]

Declares that the marked [arg text] is the name of a command argument.

[call [cmd cmd] [arg text]]

Declares that the marked [arg text] is the name of a command.

[call [cmd opt] [arg text]]

Declares that the marked [arg text] is something optional. Most often used
in conjunction with [cmd arg] to denote optional command arguments.

[call [cmd emph] [arg text]]

Emphasize the [arg text].

[call [cmd strong] [arg text]]

Emphasize the [arg text]. Same as [cmd emph]. Usage is
discouraged. The command is deprecated and present only for backward
compatibility.

[call [cmd comment] [arg text]]

Declares that the marked [arg text] is a comment.

[call [cmd sectref] [arg text]]

Declares that the marked [arg text] is a section reference.

[call [cmd syscmd] [arg text]]

Declares that the marked [arg text] is a system command.

[call [cmd method] [arg text]]

Declares that the marked [arg text] is a object method.

[call [cmd option] [arg text]]

Declares that the marked [arg text] is a option.

[call [cmd widget] [arg text]]

Declares that the marked [arg text] is a widget.

[call [cmd fun] [arg text]]

Declares that the marked [arg text] is a function.

[call [cmd type] [arg text]]

Declares that the marked [arg text] is a data type.

[call [cmd package] [arg text]]

Declares that the marked [arg text] is a package.

[call [cmd class] [arg text]]

Declares that the marked [arg text] is a class.

[call [cmd var] [arg text]]

Declares that the marked [arg text] is a variable.

[call [cmd file] [arg text]]

Declares that the marked [arg text] is a file .

[call [cmd uri] [arg text]]

Declares that the marked [arg text] is a uri.

[call [cmd term] [arg text]]

Declares that the marked [arg text] is a unspecific terminology.

[call [cmd const] [arg text]]

Declares that the marked [arg text] is a constant value.

[call [cmd nl]]

Vertical space to separate text without breaking it into a new
paragraph.

[call [cmd lb]]

Introduces a left bracket into the output.

[call [cmd rb]]

Introduces a right bracket into the output. The bracket commands are
necessary as plain brackets are used to denote the beginnings and
endings of the formatting commands.

[call [cmd example_begin]] 
Formats subsequent text as a code sample:
line breaks, spaces, and tabs are preserved and,
where appropriate, text is presented in a fixed-width font.

[call [cmd example_end]] 
End of a code sample block.

[call [cmd example] [arg text]] 

Formats [arg text] as a multi-line block of sample code.
[arg text] should be enclosed in braces.

[call [cmd list_begin] [arg what]]

Starts new list of type [arg what]. The allowed types (and their
associated item commands) are:

[list_begin definitions]
[lst_item [emph bullet]]
[cmd bullet]

[lst_item [emph enum]]
[cmd enum]

[lst_item [emph definitions]]
[cmd lst_item] and [cmd call]

[lst_item [emph arg]]
[cmd arg_def]

[lst_item [emph cmd]]
[cmd cmd_def]

[lst_item [emph opt]]
[cmd opt_def]

[lst_item [emph tkoption]]
[cmd tkoption_def]

[list_end]


[call [cmd list_end]]

Ends the list opened by the last [cmd list_begin].

[call [cmd bullet]]

Starts a new item in a bulletted list.

[call [cmd enum]]

Starts a new item in an enumerated list.

[call [cmd lst_item] [arg text]]

Starts a new item in a definition list. The argument is the term to be
defined.

[call [cmd call] [arg args]]

Starts a new item in a definition list, but the term defined by it is
a command and its arguments.

[call [cmd arg_def] [arg type] [arg name] [opt [arg mode]]]

Starts a new item in an argument list. Specifies the data-[arg type]
of the described argument, its [arg name] and possibly its
i/o-[arg mode].

[call [cmd opt_def] [arg name] [opt [arg arg]]]

Starts a new item in an option list. Specifies the [arg name] of the
option and possible (i.e. optional) [arg arg]uments.

[call [cmd cmd_def] [arg command]]

Starts a new item in a command list. Specifies the name of the
[arg command].

[call [cmd tkoption_def] [arg name] [arg dbname] [arg dbclass]]

Starts a new item in a widget option list.  Specifies the [arg name]
of the option, i.e.  the name used in scripts, name used by the option
database, and the class (type) of the option.

[call [cmd usage] [arg args]]

Defines a term to be used in the table of contents or synopsis section,
depending on the format. This command is [emph silent], as it doesn't
add any text to the output as a direct result of the call. It merely
defines data to appear in another section.

[list_end]

[section EXAMPLE]

The tcl sources of this manpage can serve as an example for all of the
markup described by it. Almost every possible construct (with the
exception of [cmd require]) is used here.

[see_also doctoc_fmt docidx_fmt doctools_api doctools]
[keywords markup {generic markup} manpage TMML HTML nroff LaTeX]
[manpage_end]
