doctocfmt(n) Documentation tools doctocfmt(n)
NAME
doctocfmt - Specification of simple tcl markup for table of contents
SYNOPSIS
vset varname value
vset varname
include filename
comment text
lb
rb
tocbegin text title
tocend
divisionstart text
divisionend
item file label desc
DESCRIPTION
This manpage specifies a documentation format for tables of contents.
It is intended to complement both the doctools format for writing man-
pages and the docidx format for writing indices. See doctoolsfmt and
docidxfmt 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 TML, 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, TML, 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 doctocapi. 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 this format plain text is not allowed, except for whitespace, which
can be used to separate the formatting commands described in the next
section (FORMATING COMANDS).
FORMATING COMANDS
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 var-
name.
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 char-
acters anymore.
lb Introduces a left bracket into the output.
rb Introduces a right bracket into the output. And now the rele-
vant markup commands.
tocbegin 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 man-
pages 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.
tocend
This command closes a table of contents. Nothing is allowed to
follow it.
divisionstart text
This command and its counterpart divisionend can be used to
give the table of contents additional structure.
Each division starts with divisionstart, is ended by divi-
sionend and has a title provided through the argument title.
The contents of a division are like for the whole table of con-
tents, 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.
divisionend
This command closes a toc division. See divisionstart above for
the detailed explanation.
item file label desc
This command describes an individual toc element. The file argu-
ment 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 for-
mats 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 sym-
bolic to actual names given to it.
NOTES
[1] The commands for the doctoc format are closely modeled on the
TML tags used for describing collections of manpages.
[2] 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.
EXAMPLE
As an example a table of contents for all manpages belonging to this
module (doctools) of package tcllib.
[tocbegin tcllib/doctools {Documentation tools}]
[divisionstart {Basic format}]
[item dtformat.man {doctools format specification}]
[item dtformatter.man {doctools engine interface}]
[item doctools.man {Package to handle doctools input and engines}]
[divisionend]
[divisionstart {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}]
[divisionend]
[divisionstart {Indices}]
[item dtidxformat.man {docindex format specification}]
[item dtidxformatter.man {docindex engine interface}]
[item docindex.man {Package to handle docindex input and engines}]
[divisionend]
[tocend]
SEE ALSO
docidxfmt, doctoc, doctocapi, doctoolsfmt
KEYWORDS
HTML, LaTeX, TML, generic markup, markup, nroff, table of contents,
toc
COPYRIGHT
Copyright (c) 2003 Andreas Kupries
doctools 1.0 doctocfmt(n)
|
