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