Manual Pages for UNIX Darwin command on man docidx

Manual Pages for UNIX Darwin command on man docidx_fmt

docidxfmt(n) Documentation tools docidxfmt(n)

NAME

docidxfmt - Specification of simple tcl markup for an index

SYNOPSIS

vvsseett varname value vvsseett varname iinncclluuddee filename ccoommmmeenntt text llbb rrbb iinnddeexxbbeeggiinn text title iinnddeexxeenndd kkeeyy text mmaannppaaggee file label uurrll url label

DESCRIPTION

This manpage specifies a documentation format for indices. It is intended to complement both the ddooccttoooollss format for writing manpages and the ddooccttoocc format for writing tables of contents. See ddooccttoooollssffmmtt and ddooccttooccffmmtt for the specification of these two formats. This format is called ddoocciiddxx. It provides all the necessary commands to write an index for a group of manpages. Like for the ddooccttoooollss and ddooccttoocc formats a package is provided implementing a generic framework for the conversion of ddoocciiddxx to a number of different output formats,

like HTML, TMML, nroff, LaTeX, etc. The package is called ddoocc-

ttoooollss::::iiddxx, its documentation can be found in ddoocciiddxx. People wishing to write a formatting engine for the conversion of ddoocciiddxx into a new output format have to read ddoocciiddxxaappii. This manpage will explain the interface between the generic package and such engines. OOVVEERRVVIIEEWW ddoocciiddxx 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 (FFOORRMMAATTTTIINNGG CCOOMMMMAANNDDSS). FFOORRMMAATTTTIINNGG CCOOMMMMAANNDDSS First a number of generic commands useable anywhere in a ddoocciiddxx file. vvsseett varname value Sets the formatter variable varname to the specified value. Returns the empty string. vvsseett varname

Returns the value associated with the formatter variable var-

name. iinncclluuddee filename Instructs the system to insert the expanded contents of the file named filename in its own place. ccoommmmeenntt 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. llbb Introduces a left bracket into the output.

rrbb Introduces a right bracket into the output. And now the rele-

vant markup commands. iinnddeexxbbeeggiinn text title This command starts an index. It has to be the very first markup command in a ddoocciiddxx file. Plain text is not allowed to come before this command. Only the generic commands (see above: vvsseett, iinncclluuddee, ccoommmmeenntt) 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 kkeeyy. iinnddeexxeenndd This command closes an index. Nothing is allowed to follow it. kkeeyy 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 mmaannppaaggee or uurrll. mmaannppaaggee file label This command describes an individual index element. Each such element belongs to the last occurence of a kkeeyy 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. uurrll 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 mmaannppaaggee 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. NNOOTTEESS [1] Using an appropriate formatting engine and some glue code it is possible to automatically generate a document in ddoocciiddxx format from a collection of manpages in ddooccttoooollss format. EEXXAAMMPPLLEE

As an example an index for all manpages belonging to this module (doc-

tools) of package ttcclllliibb. [indexbegin 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] [indexend]