docidx_fmt -
Specification of simple tcl markup for an index
vset varname value
vset varname
include filename
comment text
lb
rb
index_begin text title
index_end
key text
manpage file label
url url label
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 doctools_fmt and doctoc_fmt 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,
TMML, nroff, LaTeX, etc.
The package is called doctools::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
docidx_api. This manpage will explain the interface between
the generic package and such engines.
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 (FORMATTING COMMANDS).
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
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.
-
index_begin 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
manpages 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.
-
index_end
-
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
manpage refering to that key. The second argument is used to label the
reference.
To preserve convertibility of this format to various output formats
the filename argument file is considered to contain 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.
-
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.
-
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.
As an example an index for all manpages belonging to this module
(doctools) of package
tcllib.
[index_begin tcllib/doctools {Documentation tools}]
[key HTML]
[manpage didxengine]
[manpage didxformat]
[manpage doctools]
[manpage dtformat]
[manpage dtformatter]
[manpage dtocengine]
[manpage dtocformat]
[manpage mpexpand]
[key TMML]
[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]
[index_end]
doctools_fmt, doctoc_fmt, docidx_api, docidx
markup, generic markup, index, keywords, TMML, HTML, nroff, LaTeX