1docidx_fmt(n) Documentation tools docidx_fmt(n)
2______________________________________________________________________________
6
8 docidx_fmt - Specification of a simple Tcl Markup Language for Keyword
9 Indices
10
12 comment text
13 include filename
15 vset varname value
17 vset varname
19 lb
21 rb
23 index_begin text title
25 index_end
27 key text
29 manpage file text
31 url url label
33_________________________________________________________________
35
37 This document specifies version 1 of a text format for keyword indices.
38 The name of this format is docidx and it provides all the necessary
39 commands to write a keyword index for a group of documents. It is
40 intended to complement both the doctools format for writing documenta‐
41 tion and the doctoc format for writing tables of contents. The formal
42 specifications for these two formats can be found in the companion doc‐
43 uments doctools_fmt and doctoc_fmt. A third companion document
44 describes the package doctools::idx, which provides commands for the
45 processing of text in docidx format.
46 Like for the formats doctools and doctoc a generic framework for the
48 conversion of docidx to any number of different output formats is pro‐
49 vided. This framework is provided by the package doctools::idx.
50 Anyone who wishes to write an index formatting engine which plugs into
52 this framework has to read the document docidx_api. This is the formal
53 specification of the API between the framework and its engines.
54
56 OVERVIEW
57 While doctools is similar to LaTeX docidx is only superficially so.
58 Input written in this format consists of a series of markup commands,
59 which may be separated by whitespace. Other text is not allowed. The
60 best comparison would be to imagine a LaTeX document with all regular
61 text removed.
62 The format used to mark commands is different from LaTeX however. All
64 text between matching pairs of [ and ] is a command, possibly with
65 arguments. Note that both brackets have to be on the same line for a
66 command to be recognized.
67 GRAMMAR
69 The overall syntax of a keyword index is best captured in a formal con‐
70 text-free grammar. Our notation for the grammar is EBNF. Strings will
71 stand for markup commands, however their arguments (if they have any)
72 are not part of the grammar. Our grammar contains lexical elements as
73 well.
74 First we specify the whitespace at the lexical level, which also
76 includes comments.
77 COMMENT ::= "comment"
79 WHITE ::= { '\n' | '\t' | ' ' | '\r' | COMMENT }
80 Then we define rules for all the keywords. Here we introduce our knowl‐
83 edge that all commands can be separated by whitespace, and also that
84 the inclusion of other files may happen essentially everywhere, like
85 the definition of document variables. The content of any included file
86 has to fit into the including file according to the location in the
87 grammar the inclusion is at.
88 BEGIN ::= "index_begin" WHITE DEFUN
90 END ::= "index_end" WHITE
91 KEY ::= "key" WHITE DEFUN
92 MANPAGE ::= "manpage" WHITE DEFUN
93 URL ::= "url" WHITE DEFUN
94 INCLUDE ::= "include" WHITE
96 VSET ::= "vset" WHITE
97 DEFUN ::= { INCLUDE | VSET }
99 At last we can specify the whole index.
102 INDEX ::= DEFUN BEGIN CONTENT END
104 CONTENT ::= KEYWORD { KEYWORD }
106 KEYWORD ::= KEY REF { REF }
107 REF ::= MANPAGE | URL
108 COMMANDS
111 Here we specify the commands used in the grammar. Some commands speci‐
112 fied here were not used in the grammar at all. The usage of these com‐
113 mands is confined to the arguments of other commands.
114 comment text
116 This command declares that the argument text is a comment.
117 include filename
119 This command loads the contents of the file filename for pro‐
120 cessing at its own place.
121 vset varname value
123 This form of the command sets the document variable varname to
124 the specified value. It does not generate output. It is this
125 form the grammar is refering to.
126 vset varname
128 This form of the command returns the value associated with the
129 document variable varname. This form is not used by the grammar
130 and restricted to usage in the arguments of other commands.
131 lb This command adds a left bracket to the output. Its usage is
133 restricted to the arguments of other commands.
134 rb This command adds a right bracket to the output. Its usage is
136 restricted to the arguments of other commands.
137 index_begin text title
139 This is the command to start a keyword index. The text argument
140 provides a label for the whole group of documents the index
141 refers to. Often this is the name of the package (or extension)
142 the documents belong to. The title argument provides the over‐
143 all title text for the index.
144 index_end
146 This is the command to close a keyword index.
147 key text
149 This command adds the keyword text to the index.
150 manpage file text
152 This command adds an element to the index which refers to a doc‐
153 ument. The document is specified through the symbolic name
154 file. The text argument is used to label the reference.
155 The symbolic names are used to preserve the convertibility of
157 this format to any output format. The actual name of the file
158 will be inserted by the chosen formatting engine when converting
159 the input. This will be based on a mapping from symbolic to
160 actual names given to the engine.
161 url url label
163 This is the second command to add an element to the index. To
164 refer to a document it is not using a symbolic name however, but
165 a (possibly format-specific) url describing the exact location
166 of the document indexed here.
167
169 It is possible to generate a keyword index in docidx format automati‐
170 cally from a collection of documents in doctools format. All is needed
171 is a special doctools formatting engine which extracts the relevant
172 metadata and some glue code to convert this data to docidx.
173 The application dtplite is an example for this.
175
177 The example is a keyword index for all manpages in the module base64.
178 [index_begin tcllib/base64 {De- & Encoding}]
180 [key base64]
181 [manpage base64]
182 [key encoding]
183 [manpage base64]
184 [manpage uuencode]
185 [manpage yencode]
186 [key uuencode]
187 [manpage uuencode]
188 [key yEnc]
189 [manpage yencode]
190 [key ydecode]
191 [manpage yencode]
192 [key yencode]
193 [manpage yencode]
194 [index_end]
195
198 docidx_api, doctoc_fmt, doctools::idx, doctools_fmt
199
201 HTML, LaTeX, TMML, docidx, documentation, generic markup, index, key‐
202 word index, keywords, markup, nroff
203
205 Copyright (c) 2003-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
206doctools 1.0 docidx_fmt(n)