This document is an informal introduction to version 1 of the
docidx markup language based on a multitude of examples. After
reading this a writer should be ready to understand the two parts
of the formal specification, i.e. the docidx language syntax
specification and the docidx language command
reference.

While the docidx markup language is quite
similar to the doctools markup language, in the
broadest terms possible, there is one key difference. An index
consists essentially only of markup commands, with no plain text
interspersed between them, except for whitespace.

Each markup command is a Tcl command surrounded by a matching
pair of [ and ]. Inside
of these delimiters the usual rules for a Tcl command apply with
regard to word quotation, nested commands, continuation lines, etc.
I.e.

In the above example the command key is used
to declare the keyword phrases we wish to be part of the index.

However a truly useful index does not only list the keyword
phrases, but will also contain references to documents associated
with the keywords. Here is a made-up index for all the manpages in
the module base64:

In the above example the command manpage is used to insert references
to documents, using symbolic file names, with each command
belonging to the last key command coming before
it.

The other command to insert references is url. In contrast to manpage it uses
explicit (possibly format-specific) urls to describe the location
of the referenced document. As such this command is intended for
the creation of references to external documents which could not be
handled in any other way.

In all previous examples we fudged a bit regarding the markup
actually allowed to be used before the index_begin command opening the document.

Instead of only whitespace the two templating commands include and vset are also allowed, to
enable the writer to either set and/or import configuration
settings relevant to the table of contents. I.e. it is possible to
write

The only restriction include has to obey is
that the contents of the included file must be valid at the place
of the inclusion. I.e. a file included before index_begin may contain only the templating commands vset and include, a file
included after a key may contain only manape or url references, and
other keys, etc.

Beyond the 6 commands shown so far we have two more available.
However their function is not the marking up of index structure,
but the insertion of characters, namely [ and
]. These commands, lb and
rb respectively, are required because our use of
[ and ] to bracket markup commands makes it impossible to directly
use [ and ] within the text.

Our example of their use are the sources of the last sentence in
the previous paragraph, with some highlighting added.

...
These commands, [cmd lb] and [cmd lb] respectively, are required
because our use of [lb] and [rb] to bracket markup commands makes it
impossible to directly use [lb] and [rb] within the text.
...

Now that this document has been digested the reader, assumed to
be a writer of documentation should be
fortified enough to be able to understand the formal docidx language
syntax specification as well. From here on out the docidx language
command reference will also serve as the detailed
specification and cheat sheet for all available commands and their
syntax.

To be able to validate a document while writing it, it is also
recommended to familiarize oneself with Tclapps' ultra-configurable
dtp.

On the other hand, docidx is perfectly suited for the automatic
generation from doctools documents, and this is the route Tcllib's
easy and simple dtplite goes, creating an
index for a set of documents behind the scenes, without the writer
having to do so on their own.

This document, and the package it describes, will undoubtedly
contain bugs and other problems. Please report such in the category
doctools of the Tcllib Trackers. Please
also report any ideas for enhancements you may have for either
package and/or documentation.