|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
doctools_fmt(n) 1.0 "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>