format(n) Documentation tools format(n)
NAME
format - Specification of simple tcl markup for manpages
SYNOPSIS
manpage_begin command section version
manpage_end
moddesc desc
titledesc desc
description
require pkg ?version?
section name
para
see_also args
keywords args
arg text
cmd text
opt text
emph text
strong text
comment text
sectref text
syscmd text
method text
option text
widget text
fun text
type text
package text
class text
var text
file text
uri text
term text
const text
nl
lb
rb
example_begin
example_end
example text
list_begin what
list_end
bullet
enum
lst_item text
call args
arg_def type name ?mode?
opt_def name ?arg?
cmd_def command
tkoption_def name dbname dbclass
usage args
DESCRIPTION
This manpage specifies
[1] The overall format of manpages using this markup, and
[2] the tcl commands used as the markup
The manpage format described here is simpler than TMML, but convertible into it (and other formats, like HTML and nroff).
The tcl sources of this manpage can serve as an example for all of the markup described by it. Every possible construct (with the exception
of require) is used here.
OVERVIEW
o The main commands are manpage_begin, manpage_end, moddesc, titledesc, and description. Four of these five are required for a man-
page. The optional command is titledesc. The first two are the first and last commands in a manpage. Neither text nor other commands
may precede manpage_begin nor follow manpage_end. The command description separates header and body of the manpage and may not be
omitted.
The remaining commands (moddesc and titledesc) provide one-line descriptions of module and specific title respectively.
o The only text allowed between manpage_begin and description is the command require. Other commands or normal text are not permitted.
require is used to list the packages the described command(s) depend(s) on for its operation. This list can be empty.
o After description text and all other commands are allowed. The text can be separated into highlevel blocks using named sections.
Each block can be further divided into paragraphs via para.
o The commands see_also and keywords define whole sections named SEE ALSO and KEYWORDS. They can occur everywhere in the manpage but
making them the last section is the usual thing to do. They can be omitted.
o There are five commands available to markup words, arg, cmd, opt, emph and strong. The first three are used to mark words as command
arguments, as command names and as optional. The other two are visual markup to emphasize words in two different ways. The term
words is used in a loose sense here, i.e application of the commands to a sequence of words is entierely possible, if they are prop-
erly quoted.
o Another set of commands is available to construct (possibly nested) lists. These are list_begin, list_end, lst_item, bullet, enum,
call, arg_def, opt_def, cmd_def, and tkoption_def. The first two of these begin and end a list respectively.
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 Commands.
The other commands start list items and each can be used only inside a list of their type. In other words, bullet is allowed in bul-
leted lists but nowhere else, enum in enumerated lists and lst_item and 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.
The last list command, 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.
o The command usage is similar to call in that it adds the syntax to the table of contents (synopsis) if supported by the output for-
mat. Unlike call, this command doens'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 call elsehere in the document, or where additional usage information is desired (eg: to document a "package require" com-
mand).
Commands
manpage_begin command section 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, the version of the module containing the command, the name of the module itself and
two descriptions, one short for the command and one a bit longer for the module. Both have to fit on one line.
manpage_end
This command closes a manpage. Nothing is allowed to follow it.
moddesc desc
This command is required and comes after manpage_begin, but before either require or description. Its argument provides a one-line
description of the module described by the manpage.
titledesc desc
This command is optional and comes after manpage_begin, but before either require or 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 moddesc
instead.
description
This command separates the header part of the manpage from the main body. Only require, moddesc, or titledesc may precede it.
require pkg ?version?
May occur only between manpage_begin and description. Is used to list the packages which are required for the described command to
be operational.
section name
Used to structure the body of the manpage into named sections. This command is not allowed inside of a list or example. It implic-
itly closes the last paragraph before the command and also implicitly opens the first paragraph of the new section.
para Used to structure sections into paragraphs. Must not be used inside of a list or example.
see_also args
Creates a section SEE ALSO containing the arguments as cross-references. Must not be used inside of a list or example.
keywords args
Creates a section KEYWORDS containing the arguments as words indexing the manpage. Must not be used inside of a list or example.
arg text
Declares that the marked text is the name of a command argument.
cmd text
Declares that the marked text is the name of a command.
opt text
Declares that the marked text is something optional. Most often used in conjunction with arg to denote optional command arguments.
emph text
One way to emphasize text in a general manner.
strong text
Another way to emphasize text in a general manner.
comment text
Declares that the marked text is a comment.
sectref text
Declares that the marked text is a section reference.
syscmd text
Declares that the marked text is a system command.
method text
Declares that the marked text is a object method.
option text
Declares that the marked text is a option.
widget text
Declares that the marked text is a widget.
fun text
Declares that the marked text is a function.
type text
Declares that the marked text is a data type.
package text
Declares that the marked text is a package.
class text
Declares that the marked text is a class.
var text
Declares that the marked text is a variable.
file text
Declares that the marked text is a file .
uri text
Declares that the marked text is a uri.
term text
Declares that the marked text is a unspecific terminology.
const text
Declares that the marked text is a constant value.
nl Vertical space to separate text without breaking it into a new paragraph.
lb Introduces a left bracket into the output.
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.
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.
example_end
End of a code sample block.
example text
Formats text as a multi-line block of sample code. text should be enclosed in braces.
list_begin what
Starts new list of type what. The allowed types (and their associated item commands) are:
bullet bullet
enum enum
definitions
lst_item and call
arg arg_def
cmd cmd_def
opt opt_def
tkoption
tkoption_def
list_end
Ends the list opened by the last list_begin.
bullet Starts a new item in a bulleted list.
enum Starts a new item in an enumerated list.
lst_item text
Starts a new item in a definition list. The argument is the term to be defined.
call args
Starts a new item in a definition list, but the term defined by it is a command and its arguments.
arg_def type name ?mode?
Starts a new item in an argument list. Specifies the data-type of the described argument, its name and possibly its i/o-mode.
opt_def name ?arg?
Starts a new item in an option list. Specifies the name of the option and possible (i.e. optional) arguments.
cmd_def command
Starts a new item in a command list. Specifies the name of the command.
tkoption_def name dbname dbclass
Starts a new item in a widget option list. Specifies the name of the option, i.e. the name used in scripts, name used by the
option database, and the class (type) of the option.
usage args
Defines a term to be used in the table of contents or synopsis section, depending on the format. This command is 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.
SEE ALSO
expander(n), formatter(n), mpexpand(n)
KEYWORDS
manpage, TMML, HTML, nroff, conversion, markup
doctools 1.0 format(n)