doctoolsfmt(n) Documentation tools doctoolsfmt(n)
NAME
doctoolsfmt - Specification of simple tcl markup for manpages
SYNOPSIS
vset varname value
vset varname
include filename
manpagebegin command section version
manpageend
moddesc desc
titledesc desc
copyright text
description
require pkg ?version?
section name
para
seealso 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
examplebegin
exampleend
example text
listbegin what
listend
bullet
enum
lstitem text
call args
argdef type name ?mode?
optdef name ?arg?
cmddef command
tkoptiondef name dbname dbclass
usage args
DESCRIPTION
This manpage specifies a documentation format for manpages. It is
intended to complement both the doctoc format for writing tables of
contents and the docidx format for writing indices. See doctocfmt and
docidxfmt for the specification of these two formats.
This format is called doctools. It provides all the necessary commands
to write manpages. Like for the doctoc and docidx formats a package is
provided implementing a generic framework for the conversion of doc-
tools to a number of different output formats, like HTML, TML, nroff,
LaTeX, etc. The package is called doctools, its documentation can be
found in doctools. People wishing to write a formatting engine for the
conversion of doctools into a new output format have to read doc-
toolsapi. This manpage will explain the interface between the generic
package and such engines.
OVERVIEW
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 [ and ] is a command, possibly with arguments. Note that both
brackets have to be on the same line for a command to be recognized.
In contrast to both doctoc and docidx this format does allow plain text
beyond white space. This plain text will be the contents of the
described manpage.
FORMATING COMANDS
]o The main commands are manpagebegin, manpageend, moddesc,
titledesc, and description. Four of these five are required for
a manpage. The optional command is titledesc. The first two are
the first and last commands in a manpage. Neither text nor other
commands may precede manpagebegin nor follow manpageend. 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 manpagebegin and description is
the command require. Other commands or normal text are not per-
mitted. require is used to list the packages the described com-
mand(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 sec-
tions. Each block can be further divided into paragraphs via
para.
]o The commands seealso and keywords define whole sections named
SE 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. The term 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. Note that usage of strong is discouraged as this command
is deprecated and only present for backwards compatibility
]o Another set of commands is available to construct (possibly
nested) lists. These are listbegin, listend, lstitem, bullet,
enum, call, argdef, optdef, cmddef, and tkoptiondef. 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 bulletted lists but nowhere else, enum in enumerated lists
and lstitem and call are for definition lists. These two com-
mands 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 sup-
ported by the output format in question. nroff and HTML for
example do. A format focused on logical markup, like TML, 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
format. Unlike 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 call elsewhere in the document, or where
additional usage information is desired (e.g.: to document a
"package require" command).
Commands
vset varname value
Sets the formatter variable varname to the specified value.
Returns the empty string.
vset varname
Returns the value associated with the formatter variable var-
name.
include filename
Reads the file named filename, runs it through the expansion
process and returns the expanded result.
manpagebegin 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, and the ver-
sion of the module containing the command. All have to fit on
one line.
manpageend
This command closes a manpage. Nothing is allowed to follow it.
moddesc desc
This command is required and comes after manpagebegin, 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 manpagebegin, 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.
copyright text
This command is optional and comes after manpagebegin, but
before either require or description. Its argument declares the
copyright assignment for the manpage. When invoked more than
once the assignments are accumulated.
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.
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 manpagebegin 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
implicitly 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.
seealso 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 exam-
ple.
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 argu-
ments.
emph text
Emphasize the text.
strong text
Emphasize the text. Same as emph. Usage is discouraged. The com-
mand is deprecated and present only for backward compatibility.
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 begin-
nings and endings of the formatting commands.
examplebegin
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.
exampleend
End of a code sample block.
example text
Formats text as a multi-line block of sample code. text should
be enclosed in braces.
listbegin what
Starts new list of type what. The allowed types (and their asso-
ciated item commands) are:
bullet bullet
enum enum
definitions
lstitem and call
arg argdef
cmd cmddef
opt optdef
tkoption
tkoptiondef
listend
Ends the list opened by the last listbegin.
bullet Starts a new item in a bulletted list.
enum Starts a new item in an enumerated list.
lstitem 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.
argdef 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.
optdef name ?arg?
Starts a new item in an option list. Specifies the name of the
option and possible (i.e. optional) arguments.
cmddef command
Starts a new item in a command list. Specifies the name of the
command.
tkoptiondef 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.
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 require) is used here.
SEE ALSO
docidxfmt, doctocfmt, doctools, doctoolsapi
KEYWORDS
HTML, LaTeX, TML, generic markup, manpage, markup, nroff
COPYRIGHT
Copyright (c) 2002 Andreas Kupries
Copyright (c) 2003 Andreas Kupries
doctools 1.0 doctoolsfmt(n)
|
