docidx_fmt(n) 1.0 doctools "Documentation tools"

NAME

docidx_fmt - Specification of simple tcl markup for an index

SYNOPSIS

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.

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 (FORMATTING COMMANDS).

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.

NOTES

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 (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]

KEYWORDS

HTML, LaTeX, TMML, generic markup, index, keywords, markup, nroff