docidxfmt(n) Documentation tools docidxfmt(n)
NAME
docidxfmt - Specification of simple tcl markup for an index
SYNOPSIS
vset varname value
vset varname
include filename
comment text
lb
rb
indexbegin text title
indexend
key text
manpage file label
url url label
DESCRIPTION
This manpage specifies a documentation format for indices. It is
intended to complement both the doctools format for writing manpages
and the doctoc format for writing tables of contents. See doctoolsfmt
and doctocfmt for the specification of these two formats.
This format is called docidx. It provides all the necessary commands
to write an index for a group of manpages. Like for the doctools and
doctoc formats a package is provided implementing a generic framework
for the conversion of docidx to a number of different output formats,
like HTML, TML, nroff, LaTeX, etc. The package is called doc-
tools::::idx, its documentation can be found in docidx. People wishing
to write a formatting engine for the conversion of docidx into a new
output format have to read docidxapi. This manpage will explain the
interface between the generic package and such engines.
OVERVIEW
docidx 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 docidx 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.
indexbegin text title
This command starts an index. It has to be the very first markup
command in a docidx 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 the index refers to. Often this is the name of the package
(or extension) the manpages belong to.
The title argument provides the title for the index.
Each index has to contain at least one key.
indexend
This command closes an index. Nothing is allowed to follow it.
key text
This commands starts the list of manpages and other entities
which refer to the keyword named by the argument text.
Each key section has to contain at least one index element,
either manpage or url.
manpage file label
This command describes an individual index element. Each such
element belongs to the last occurence of a key command coming
before the index.
The file argument refers to the file containing the actual man-
page refering to that key. The second argument is used to label
the reference.
To preserve convertibility of this format to various output for-
mats the filename argument file is considered to contain a sym-
bolic 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.
url url label
This is the second command to describe an index element. The
association to the key it belongs to is done in the same way as
for the manpage command. The first however is not the symbolic
name of the file refering to that key, but an url describing the
exact location of the document indexed here.
NOTES
[1] Using an appropriate formatting engine and some glue code it is
possible to automatically generate a document in docidx format
from a collection of manpages in doctools format.
EXAMPLE
As an example an index for all manpages belonging to this module (doc-
tools) of package tcllib.
[indexbegin tcllib/doctools {Documentation tools}]
[key HTML]
[manpage didxengine]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtformatter]
[manpage dtocengine]
[manpage dtocformat]
[manpage mpexpand]
[key TML]
[manpage didxengine]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtformatter]
[manpage dtocengine]
[manpage dtocformat]
[manpage mpexpand]
[key conversion]
[manpage didxengine]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtformatter]
[manpage dtocengine]
[manpage dtocformat]
[manpage mpexpand]
[key documentation]
[manpage doctools]
[manpage dtformatter]
[key index]
[manpage didxengine]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtocformat]
[key interface]
[manpage didxengine]
[manpage dtformatter]
[manpage dtocengine]
[key manpage]
[manpage didxengine]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtformatter]
[manpage dtocengine]
[manpage dtocformat]
[manpage mpexpand]
[key markup]
[manpage didxengine]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtformatter]
[manpage dtocengine]
[manpage dtocformat]
[manpage mpexpand]
[key nroff]
[manpage didxengine]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtformatter]
[manpage dtocengine]
[manpage dtocformat]
[manpage mpexpand]
[key {table of contents}]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtocengine]
[manpage dtocformat]
[key toc]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtocengine]
[manpage dtocformat]
[indexend]
SEE ALSO
docidx, docidxapi, doctocfmt, doctoolsfmt
KEYWORDS
HTML, LaTeX, TML, generic markup, index, keywords, markup, nroff
COPYRIGHT
Copyright (c) 2003 Andreas Kupries
doctools 1.0 docidxfmt(n)
|
