	ActiveTcl User Guide

[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]

doctoc_fmt(n) 1.0 "Documentation tools"

NAME

doctoc_fmt - Specification of a simple Tcl Markup Language for Tables of Contents

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    FORMAT SPECIFICATION
        OVERVIEW
        GRAMMAR
        COMMANDS
    NOTES
    EXAMPLE
    SEE ALSO
    KEYWORDS
    COPYRIGHT

SYNOPSIS

comment text

include filename

vset varname value

vset varname

toc_begin text title

toc_end

division_start text ?symfile?

division_end

item file text desc

This document specifies version 1 of a text format for tables of contents. The name of this format is doctoc and it provides all the necessary commands to write a table of contents for a group of documents. It is intended to complement both the doctools format for writing documentation and the docidx format for writing keyword indices. The formal specifications for these two formats can be found in the companion documents doctools_fmt and docidx_fmt . A third companion document describes the package doctools::toc, which provides commands for the processing of text in doctoc format.

Like for the formats doctools and docidx a generic framework for the conversion of doctoc to any number of different output formats is provided. This framework is provided by the package doctools::toc.

Anyone who wishes to write a toc formatting engine which plugs into this framework has to read the document doctoc_api . This is the formal specification of the API between the framework and its engines.

FORMAT SPECIFICATION

OVERVIEW

While doctools is similar to LaTeX doctoc is only superficially so. Input written in this format consists of a series of markup commands, which may be separated by whitespace. Other text is not allowed. The best comparison would be to imagine a LaTeX document with all regular text removed.

The format used to mark commands 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.

GRAMMAR

The overall syntax of a table of contents is best captured in a formal context-free grammar. Our notation for the grammar is EBNF. Strings will stand for markup commands, however their arguments (if they have any) are not part of the grammar. Our grammar contains lexical elements as well.

First we specify the whitespace at the lexical level, which also includes comments.

    COMMENT  ::= "comment"
    WHITE    ::= { '\n' | '\t' | ' ' | '\r' | COMMENT }

Then we define rules for all the keywords. Here we introduce our knowledge that all commands can be separated by whitespace, and also that the inclusion of other files may happen essentially everywhere, like the definition of document variables. The content of any included file has to fit into the including file according to the location in the grammar the inclusion is at.

    BEGIN     ::= "toc_begin"      WHITE DEFUN
    END       ::= "toc_end"        WHITE
    DIV_START ::= "division_start" WHITE DEFUN
    DIV_END   ::= "division_end"   WHITE DEFUN
    ITEM      ::= "item"           WHITE DEFUN

    INCLUDE  ::= "include"         WHITE
    VSET     ::= "vset"            WHITE

    DEFUN    ::= { INCLUDE | VSET }

At last we can specify the whole table of contents.

    TOC      ::= DEFUN BEGIN CONTENTS END

    CONTENTS ::= (ITEMS | SECTIONS)
    ITEMS    ::= ITEM { ITEM }
    SECTIONS ::= SECTION { SECTION }
    SECTION  ::= DIV_START CONTENTS DIV_END

COMMANDS

Here we specify the commands used in the grammar. Some commands specified here were not used in the grammar at all. The usage of these commands is confined to the arguments of other commands.

comment text: This command declares that the argument text is a comment.
include filename: This command loads the contents of the file filename for processing at its own place.
vset varname value: This form of the command sets the document variable varname to the specified value. It does not generate output. It is this form the grammar is refering to.
vset varname: This form of the command returns the value associated with the document variable varname. This form is not used by the grammar and restricted to usage in the arguments of other commands.
lb: This command adds a left bracket to the output. Its usage is restricted to the arguments of other commands.
rb: This command adds a right bracket to the output. Its usage is restricted to the arguments of other commands.
toc_begin text title: This is the command to start a table of contents.

The text argument provides a label for the whole group of documents the index refers to. Often this is the name of the package (or extension) the documents belong to. The title argument provides the overall title text for the index.
toc_end: This is the command to close a table of contents.
division_start text ?symfile?: This command opens a section in the table of contents. Its counterpart is division_end. Together they allow a user to give a table of contents additional structure.

The title of the new section is provided by the argument text.

If the symbolic filename symfile is present then the section title should link to the referenced document, if links are supported by the output format.
division_end: This command closes a section. See division_start above for the detailed explanation.
item file text desc: This command adds an individual element to the table of contents. Each such element refers to a document. The document is specified through the symbolic name file. The text argument is used to label the reference, whereas the desc provides a short descriptive text of that document.

The symbolic names are used to preserve the convertibility of this format to any output format. The actual name of the file will be inserted by the chosen formatting engine when converting the input. This will be based on a mapping from symbolic to actual names given to the engine.

NOTES

It is possible to generate a table of contents in doctoc format automatically from a collection of documents in doctools format. All is needed is a special doctools formatting engine which extracts the relevant metadata and some glue code to convert this data to doctoc .

The application dtplite is an example for this.

EXAMPLE

The example is a table of contents for all manpages in the module base64 .

[toc_begin Base64 {Table Of Contents}]
    [item base64.man   base64   {Procedures to encode and decode base64}
    [item uuencode.man uuencode {encode/decoding a binary file}]
    [item yencode.man  yencode  {encode/decoding a binary file}]
[toc_end]

KEYWORDS

HTML , LaTeX , TMML , doctoc , documentation , generic markup , keywords , markup , nroff , table of contents , toc

doctoc_fmt(n) 1.0 "Documentation tools"

Copyright © 2004 for compilation: ActiveState