ActiveTcl User Guide
|
||
docidx_fmt - Specification of a simple Tcl Markup Language for Keyword Indices
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
FORMAT
SPECIFICATION
OVERVIEW
GRAMMAR
COMMANDS
NOTES
EXAMPLE
SEE ALSO
KEYWORDS
COPYRIGHT
|
This document specifies version 1 of a text format for keyword indices. The name of this format is docidx and it provides all the necessary commands to write a keyword index for a group of documents. It is intended to complement both the doctools format for writing documentation and the doctoc format for writing tables of contents. The formal specifications for these two formats can be found in the companion documents doctools_fmt and doctoc_fmt . A third companion document describes the package doctools::idx, which provides commands for the processing of text in docidx format.
Like for the formats doctools and doctoc a generic framework for the conversion of docidx to any number of different output formats is provided. This framework is provided by the package doctools::idx.
Anyone who wishes to write an index formatting engine which plugs into this framework has to read the document docidx_api . This is the formal specification of the API between the framework and its engines.
While doctools is similar to LaTeX docidx 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.
The overall syntax of a keyword index 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 ::= "index_begin" WHITE DEFUN END ::= "index_end" WHITE KEY ::= "key" WHITE DEFUN MANPAGE ::= "manpage" WHITE DEFUN URL ::= "url" WHITE DEFUN INCLUDE ::= "include" WHITE VSET ::= "vset" WHITE DEFUN ::= { INCLUDE | VSET } |
At last we can specify the whole index.
INDEX ::= DEFUN BEGIN CONTENT END CONTENT ::= KEYWORD { KEYWORD } KEYWORD ::= KEY REF { REF } REF ::= MANPAGE | URL |
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.
It is possible to generate a keyword index in docidx 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 docidx .
The application dtplite is an example for this.
The example is a keyword index for all manpages in the module base64 .
[index_begin tcllib/base64 {De- & Encoding}] [key base64] [manpage base64] [key encoding] [manpage base64] [manpage uuencode] [manpage yencode] [key uuencode] [manpage uuencode] [key yEnc] [manpage yencode] [key ydecode] [manpage yencode] [key yencode] [manpage yencode] [index_end] |
docidx_api , doctoc_fmt , doctools::idx , doctools_fmt
HTML , LaTeX , TMML , docidx , documentation , generic markup , index , keyword index , keywords , markup , nroff
Copyright © 2003-2004 Andreas Kupries
<andreas_kupries@users.sourceforge.net>