doctoc_fmt(n) 1.0 doctools "Documentation tools"
doctoc_fmt - Specification of simple tcl markup for table of contents
This manpage specifies a documentation format for tables of
contents. It is intended to complement both the doctools
format for writing manpages and the docidx format for writing
indices. See doctools_fmt and docidx_fmt for the
specification of these two formats
This format is called doctoc.
It provides all the necessary commands to write a table of contents
for a group of manpages. It is simpler than TMML, but convertible into
it.
Like for the doctools and docidx formats a package
is provided implementing a generic framework for the conversion of
doctoc to a number of different output formats, like HTML,
TMML, nroff, LaTeX, etc.
The package is called doctools::toc, its documentation can
be found in doctoc.
People wishing to write a formatting engine for the conversion of
doctoc into a new output format have to read
doctoc_api. This manpage will explain the interface between
the generic package and such engines.
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 this format plain text is not allowed, except for whitespace, which
can be used to separate the formatting commands described in the next
section (FORMATTING COMMANDS).
First a number of generic commands useable anywhere in a
doctoc file.
- 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
varname.
- include filename
-
Instructs the system to insert the expanded contents of the file named
filename in its own place.
- comment text
-
Declares that the marked text is a comment.
Commands to insert special plain text. These bracket commands are
necessary as plain brackets are used to denote the beginnings and
endings of the formatting commands and thus cannot be used as normal
characters anymore.
- lb
-
Introduces a left bracket into the output.
- rb
-
Introduces a right bracket into the output.
And now the relevant markup commands.
- toc_begin text title
-
This command starts a table of contents. It has to be the very first
markup command in a doctoc file. Plain text is not
allowed to come before this command. Only the generic commands (see
above: vset, include, comment) can be used before
it.
The text argument provides a label for the whole group of
manpages listed in the table of contents. Often this is the name of
the package (or extension) the manpages belong to.
The title argument provides the title for the whole table of
contents.
The table of contents has to contain at least either one toc element
(item) or one division.
- toc_end
-
This command closes a table of contents. Nothing is allowed to follow
it.
- division_start text
-
This command and its counterpart division_end can be used to give
the table of contents additional structure.
Each division starts with division_start, is ended by division_end
and has a title provided through the argument title. The
contents of a division are like for the whole table of contents,
i.e. a series of either toc elements or divisions. The latter means
that divisions can be nested.
The division has to contain at least either one toc element
(item) or one division.
- division_end
-
This command closes a toc division. See division_start above for
the detailed explanation.
- item file label desc
-
This command describes an individual toc element. The file
argument refers to the file containing the actual manpage, and the
desc provides a short descriptive text of that manpage. The
argument label can be used by engines supporting hyperlinks to
give the link a nice text (instead of the symbolic filename).
To preserve convertibility of this format to various output formats
the filename argument is considered a symbolic name. The actual name
of the file will be inserted by the formatting engine used to convert
the input, based on a mapping from symbolic to actual names given to
it.
-
The commands for the doctoc format are closely modeled on the
TMML tags used for describing collections of manpages.
-
Using an appropriate formatting engine and some glue code it is
possible to automatically generate a document in doctoc
format from a collection of manpages in doctools format.
As an example a table of contents for all manpages belonging to this
module (doctools) of package tcllib.
| |
[toc_begin tcllib/doctools {Documentation tools}]
[division_start {Basic format}]
[item dtformat.man {doctools format specification}]
[item dtformatter.man {doctools engine interface}]
[item doctools.man {Package to handle doctools input and engines}]
[division_end]
[division_start {Table of Contents}]
[item dtocformat.man {doctoc format specification}]
[item dtocformatter.man {doctoc engine interface}]
[item doctoc.man {Package to handle doctoc input and engines}]
[division_end]
[division_start {Indices}]
[item dtidxformat.man {docindex format specification}]
[item dtidxformatter.man {docindex engine interface}]
[item docindex.man {Package to handle docindex input and engines}]
[division_end]
[toc_end]
|
docidx_fmt, doctoc, doctoc_api, doctools_fmt
HTML, LaTeX, TMML, generic markup, markup, nroff, table of contents, toc
Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>