|
ActiveTcl User Guide
|
|
|
format(n) 1.0 doctools "Documentation tools"
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
- The overall format of manpages using this markup, and
- 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
- The main commands are manpage_begin, manpage_end, 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
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.
- 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.
- 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.
- 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.
- 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 entirely possible, if they
are properly quoted.
- 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 bulletted 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.
- 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
- 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
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.
- 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 bulletted 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