Manual Pages for UNIX Darwin command on man doctoc

Manual Pages for UNIX Darwin command on man doctoc_fmt

doctocfmt(n) Documentation tools doctocfmt(n)

NAME

doctocfmt - Specification of simple tcl markup for table of contents

SYNOPSIS

vvsseett varname value vvsseett varname iinncclluuddee filename ccoommmmeenntt text llbb rrbb ttooccbbeeggiinn text title ttoocceenndd ddiivviissiioonnssttaarrtt text ddiivviissiioonneenndd iitteemm file label desc

DESCRIPTION

This manpage specifies a documentation format for tables of contents.

It is intended to complement both the ddooccttoooollss format for writing man-

pages and the ddoocciiddxx format for writing indices. See ddooccttoooollssffmmtt and ddoocciiddxxffmmtt for the specification of these two formats This format is called ddooccttoocc. It provides all the necessary commands to write a table of contents for a group of manpages. It is simpler than TMML, but convertible into it. Like for the ddooccttoooollss and ddoocciiddxx formats a package is provided implementing a generic framework for the conversion of ddooccttoocc to a number of different output formats, like HTML, TMML, nroff, LaTeX, etc. The package is called ddooccttoooollss::::ttoocc, its documentation can be found in ddooccttoocc. People wishing to write a formatting engine for the conversion of ddooccttoocc into a new output format have to read ddooccttooccaappii. This manpage will explain the interface between the generic package and such engines. OOVVEERRVVIIEEWW ddooccttoocc 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 ddooccttoocc 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. ttooccbbeeggiinn text title This command starts a table of contents. It has to be the very first markup command in a ddooccttoocc 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 listed in the table of contents. Often this is the name of the package (or extension) the manpages belong to. The title argument provides the title for the whole table of contents. The table of contents has to contain at least either one toc element (iitteemm) or one division. ttoocceenndd This command closes a table of contents. Nothing is allowed to follow it. ddiivviissiioonnssttaarrtt text This command and its counterpart ddiivviissiioonneenndd can be used to give the table of contents additional structure.

Each division starts with ddiivviissiioonnssttaarrtt, is ended by ddiivvii-

ssiioonneenndd and has a title provided through the argument title.

The contents of a division are like for the whole table of con-

tents, i.e. a series of either toc elements or divisions. The latter means that divisions can be nested. The division has to contain at least either one toc element (iitteemm) or one division. ddiivviissiioonneenndd This command closes a toc division. See ddiivviissiioonnssttaarrtt above for the detailed explanation. iitteemm file label desc

This command describes an individual toc element. The file argu-

ment refers to the file containing the actual manpage, and the desc provides a short descriptive text of that manpage. The argument label can be used by engines supporting hyperlinks to give the link a nice text (instead of the symbolic filename).

To preserve convertibility of this format to various output for-

mats the filename argument is considered 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 sym-

bolic to actual names given to it. NNOOTTEESS [1] The commands for the ddooccttoocc format are closely modeled on the TMML tags used for describing collections of manpages. [2] Using an appropriate formatting engine and some glue code it is possible to automatically generate a document in ddooccttoocc format from a collection of manpages in ddooccttoooollss format. EEXXAAMMPPLLEE As an example a table of contents for all manpages belonging to this module (doctools) of package ttcclllliibb. [tocbegin tcllib/doctools {Documentation tools}] [divisionstart {Basic format}] [item dtformat.man {doctools format specification}] [item dtformatter.man {doctools engine interface}] [item doctools.man {Package to handle doctools input and engines}] [divisionend] [divisionstart {Table of Contents}] [item dtocformat.man {doctoc format specification}] [item dtocformatter.man {doctoc engine interface}] [item doctoc.man {Package to handle doctoc input and engines}] [divisionend] [divisionstart {Indices}] [item dtidxformat.man {docindex format specification}] [item dtidxformatter.man {docindex engine interface}] [item docindex.man {Package to handle docindex input and engines}] [divisionend] [tocend]