doctools_fmt(3tcl) 1.0 doctools "Documentation tools"
doctools_fmt - Specification of a simple Tcl Markup Language for Manpages
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
FORMAT SPECIFICATION
OVERVIEW
GRAMMAR
COMMANDS
EXAMPLE
SEE ALSO
KEYWORDS
COPYRIGHT
This document specifies version 1 of a text format for man pages. The
name of this format is doctools and it provides all the
necessary commands to write a manpage.
It is complemented by both the doctoc format for writing tables
of contents and the docidx format for writing keyword indices.
The formal specifications for these two formats can be found in the
companion documents doctoc_fmt and docidx_fmt.
A third companion document describes the package doctools,
which provides commands for the processing of text in doctools
format.
Like for the formats doctoc and docidx a generic
framework for the conversion of doctools to any number of
different output formats is provided.
This framework is provided by the package doctools.
Anyone who wishes to write a toc formatting engine which plugs into
this framework has to read the document doctools_api. This is the
formal specification of the API between the framework and its engines.
doctools is similar to LaTeX. Input written in this format
consists primarily of text, with markup commands embedded into it. The
format used to mark commands 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 arbitrary text between markup commands. Only some places are
restricted to only white space.
The overall syntax of a manpage is best captured in a formal
context-free grammar. Our notation for the grammar is EBNF. Strings
will stand for markup commands, however their arguments (if they have
any) are not part of the grammar. Our grammar contains lexical
elements as well.
First we specify the whitespace and other text at the lexical level,
which also includes comments.
|
COMMENT ::= "comment"
WHITE ::= { '\n' | '\t' | ' ' | '\r' | COMMENT }
TEXT ::= { All characters except '[' }
|
Then we define rules for all the keywords. Here we introduce our
knowledge that some commands allow only whitespace after them.
|
BEGIN ::= "manpage_begin" WHITE
END ::= "manpage_end"
TITLE ::= "titledesc" WHITE
MODULE ::= "moddesc" WHITE
REQUIRE ::= "require" WHITE
COPYRIGHT ::= "copyright" WHITE
DESC ::= "description"
SECTION ::= "section"
SUBSEC ::= "subsection"
PARA ::= "para"
NL ::= "nl"
SEE_ALSO ::= "see_also"
KEYWORDS ::= "keywords"
ARG ::= "arg"
CMD ::= "cmd"
OPT ::= "opt"
EMPH ::= "emph"
STRONG ::= "strong"
SECTREF ::= "sectref"
USAGE ::= "usage"
SYSCMD ::= "syscmd"
METHOD ::= "method"
NAMESPACE ::= "namespace"
OPTION ::= "option"
WIDGET ::= "widget"
FUN ::= "fun"
TYPE ::= "type"
PACKAGE ::= "package"
CLASS ::= "class"
VAR ::= "var"
FILE ::= "file"
URI ::= "uri"
TERM ::= "term"
CONST ::= "const"
LB ::= "lb"
RB ::= "rb"
EX_BEGIN ::= "example_begin"
EX_END ::= "example_end"
EXAMPLE ::= "example"
LIST_BEGIN ::= "list_begin" WHITE
LIST_END ::= "list_end"
LIST_ITEM ::= "lst_item"
BULLET ::= "bullet"
ENUM ::= "enum"
CALL ::= "call"
ARGDEF ::= "arg_def"
OPTDEF ::= "opt_def"
CMDDEF ::= "cmd_def"
TKODEF ::= "tkoption_def"
INCLUDE ::= "include"
VSET ::= "vset"
DEFUN ::= { INCLUDE | VSET }
|
At last we can specify the whole manpage. Here we introduce our
knowledge that inclusion of other files may happen essentially
everywhere, like the definition of document variables and comments.
The content of any included file has to fit into the including file
according to the location in the grammar the inclusion is at.
|
MANPAGE ::= DEFUN BEGIN HEADER DESC BODY END
HEADER ::= { TITLE | MODULE | COPYRIGHT } { REQUIRE }
BODY ::= REGULAR_TEXT { SECTION SECBODY }
SECBODY ::= REGULAR_TEXT { SUBSEC SUBSECBODY }
SUBSECBODY ::= REGULAR_TEXT
REGULAR_TEXT ::= TEXT_CHUNK { PARA TEXT_CHUNK }
TEXT_CHUNK ::= { TEXT | DEFUN | XREF | MARKUP | COMMENT | A_LIST | AN_EXAMPLE }
A_LIST ::= LIST_BEGIN { ( LIST_ITEM | CALL ) LIST_TEXT } LIST_END
| LIST_BEGIN { BULLET LIST_TEXT } LIST_END
| LIST_BEGIN { ENUM LIST_TEXT } LIST_END
| LIST_BEGIN { ARGDEF LIST_TEXT } LIST_END
| LIST_BEGIN { OPTDEF LIST_TEXT } LIST_END
| LIST_BEGIN { CMDDEF LIST_TEXT } LIST_END
| LIST_BEGIN { TKODEF LIST_TEXT } LIST_END
LIST_TEXT ::= TEXT_CHUNK { NL TEXT_CHUNK }
AN_EXAMPLE ::= EXAMPLE | EX_BEGIN EXAMPLE_TEXT EX_END
EXAMPLE_TEXT ::= { TEXT | DEFUN | MARKUP }
MARKUP ::= { BRACKETS | SEMANTIC }
XREF ::= SEE_ALSO | KEYWORDS
BRACKETS ::= LB | RB
SEMANTIC ::= ARG | EMPH | CLASS | STRONG | OPTION
| CMD | TYPE | CONST | METHOD | SECTREF
| OPT | TERM | FUN | SYSCMD | PACKAGE
| VAR | FILE | USAGE | WIDGET | NAMESPACE
| URI
|
Here we specify the commands used in the grammar. Some commands
specified here were not used in the grammar at all. The usage of these
commands is confined to the arguments of other commands.
- comment text
-
The command declares that the argument text is a comment.
- include filename
-
This command loads the contents of the file filename for
processing at its own place.
- vset varname value
-
This form of the command sets the document variable varname to
the specified value. It does not generate output.
- vset varname
-
This form of the command returns the value associated with the
document variable varname.
- lb
-
This command adds a left bracket to the output. Note that the
bracket commands are necessary as plain brackets are used to begin and
end the formatting commands.
- rb
-
This command adds a right bracket to the output. Note that the
bracket commands are necessary as plain brackets are used to begin and
end the formatting commands.
- manpage_begin command section version
-
This is the command to start a manpage. The arguments are the name of
the command described by the manpage, the section of the
manpages this manpage resides in, and the version of the module
containing the command.
- manpage_end
-
This is the command to close a manpage.
- moddesc desc
-
This command is optional. When used it will register its argument
desc as a short description of the module the manpage resides
in.
- titledesc desc
-
This command is optional. When used it will register its argument
desc as the title of the manpage. When not used the information
from moddesc will be used for the title as well.
- copyright text
-
This command is optional. When used its argument text will
declare a copyright assignment for the manpage. When invoked more than
once the assignments are accumulated.
A doctools processor application (like dtplite) is allowed to
provide such information too, but a formatting engine has to give the
accumulated arguments of this command precedence over the data coming
from the application.
- description
-
This is the command to separate the header part of the manpage from
the main body.
- require pkg ?version?
-
This is the command to list the packages which are required by an
application or other library to import the described package and its
prerequisites.
- section name
-
This is the command to partition the body of the manpage into named
sections. Note that the command description at the beginning of
the manpage body implicitly starts a section named "DESCRIPTION". A
section command implicitly closes the last paragraph coming
before it and also implicitly opens the first paragraph of the new
section.
- subsection name
-
This is the command to partition the body of a section into
named sub-sections. A subsection command implicitly closes the last
paragraph coming before it and also implicitly opens the first
paragraph of the new section.
- para
-
This is the command to partition the text in a section or sub-section
into paragraphs. Each invokation closes the paragraph coming before it
and opens a new paragraph for the text coming after.
- see_also args
-
This is the command to define direct cross-references to other
documents. Each argument is a label identifying the referenced
document. If this command is used multiple times all the arguments
accumulate.
- keywords args
-
This is the command to define the keywords applying to this
document. Each argument is a single keyword. If this command is used
multiple times all the arguments accumulate.
- arg text
-
Declares that the argument text is the name of a command
argument.
- cmd text
-
Declares that the argument text is the name of a command.
- opt text
-
Declares that the argument text is something optional. Most
often used in conjunction with arg to denote optional command
arguments. Example:
|
[arg foo]
A regular argument.
[opt [arg foo]]
An optional argument.
|
- emph text
-
Emphasize the text.
- strong text
-
Emphasize the text. Same as emph. Usage of this command is
discouraged. The command is deprecated and present only for backward
compatibility.
- sectref text ?label?
-
Declares that the argument text is the name of a section
somewhere else in the document, and the current location should refer
to it.
Without an explicit label for the reference within the text the
section title text is used.
- syscmd text
-
Declares that the argument text is the name of a system command.
- method text
-
Declares that the argument text is the name of an object method.
- namespace text
-
Declares that the argument text is the name of a namespace.
- option text
-
Declares that the argument text is the name of an option.
- widget text
-
Declares that the argument text is the name of a widget.
- fun text
-
Declares that the argument text is the name of a function.
- type text
-
Declares that the argument text is the name of a data type.
- package text
-
Declares that the argument text is the name of a package.
- class text
-
Declares that the argument text is the name of a class.
- var text
-
Declares that the argument text is the name of a variable.
- file text
-
Declares that the argument text is a file .
- uri text ?text?
-
Declares that the argument text is an uri. The second argument,
if it is present, is the human-readable description of the uri. In
other words, the label for the link. Without a labeling text the uri
is used as its own label.
- term text
-
Declares that the argument text contains some unspecific
terminology.
- const text
-
Declares that the argument text is a constant value.
- nl
-
This command signals vertical space to separate blocks of text.
- example_begin
-
This command begins an example block. Subsequent text belongs to the
example. Line breaks, spaces, and tabs have to be preserved literally.
- example_end
-
This command closes the example block.
- example text
-
This command wraps its argument text into an example. In other
words, it is a simpler form of markup for the creation of an
example. It should be used if the example text does not need need
special markup.
- list_begin what
-
This command starts new list. The value of the argument what
determines what type of list is opened. This also defines what command
has to be used to start an item in the new list. 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
-
This command ends the list opened by the last list_begin.
- bullet
-
This command starts a new list item in a bulletted list. The previous
item is automatically closed.
- enum
-
This command starts a new list item in an enumerated list. The
previous item is automatically closed.
- lst_item text
-
This command starts a new list item in a definition list. The argument
is the term to be defined. The previous item is automatically closed.
- call args
-
This command starts a new list item in a definition list, but the term
defined by it is a command and its arguments. The previous item is
automatically closed. The first argument is the name of the described
command, and everything after that are descriptions of the command
arguments.
- arg_def type name ?mode?
-
This command starts a new list item in an argument list. The previous
item is automatically closed. Specifies the data-type of the
described argument, its name and its i/o-mode. The latter
is optional.
- opt_def name ?arg?
-
This command starts a new list item in an option list. The previous
item is automatically closed. Specifies the name of the option
and its arguments (arg). The latter is a list, and can be left
out.
- cmd_def command
-
This command starts a new list item in a command list. The previous
item is automatically closed. Specifies the name of the command.
- tkoption_def name dbname dbclass
-
This command starts a new list item in a widget option list. The
previous item is automatically closed.
Specifies the name of the option, i.e. the name used in scripts,
the name used by the option database (dbname), and the class
(type) of the option (dbclass).
- usage args
-
This command is like call, except that a formatting engine must
not generate output at the location of the command. In other words,
this command is silent. The data it defines may appear in a
different section of the output, for example a table of contents, or
synopsis, depending on the formatting engine and its output format.
The sources of this manpage can serve as an example for all of the
markup described by it. Almost every possible construct is used here.
docidx_fmt, doctoc_fmt, doctools, doctools_api
HTML, LaTeX, TMML, generic markup, manpage, markup, nroff
Copyright © 2002-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>