1doctoc_fmt(n) Documentation tools doctoc_fmt(n)
2______________________________________________________________________________
6
8 doctoc_fmt - Specification of a simple Tcl Markup Language for Tables
9 of Contents
10
12 comment text
13 include filename
15 vset varname value
17 vset varname
19 lb
21 rb
23 toc_begin text title
25 toc_end
27 division_start text ?symfile?
29 division_end
31 item file text desc
33_________________________________________________________________
35
37 This document specifies version 1 of a text format for tables of con‐
38 tents. The name of this format is doctoc and it provides all the neces‐
39 sary commands to write a table of contents for a group of documents.
40 It is intended to complement both the doctools format for writing docu‐
41 mentation and the docidx format for writing keyword indices. The for‐
42 mal specifications for these two formats can be found in the companion
43 documents doctools_fmt and docidx_fmt. A third companion document
44 describes the package doctools::toc, which provides commands for the
45 processing of text in doctoc format.
46 Like for the formats doctools and docidx a generic framework for the
48 conversion of doctoc to any number of different output formats is pro‐
49 vided. This framework is provided by the package doctools::toc.
50 Anyone who wishes to write a toc formatting engine which plugs into
52 this framework has to read the document doctoc_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 doctoc 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 table of contents is best captured in a formal
70 context-free grammar. Our notation for the grammar is EBNF. Strings
71 will stand for markup commands, however their arguments (if they have
72 any) are not part of the grammar. Our grammar contains lexical elements
73 as 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 ::= "toc_begin" WHITE DEFUN
90 END ::= "toc_end" WHITE
91 DIV_START ::= "division_start" WHITE DEFUN
92 DIV_END ::= "division_end" WHITE DEFUN
93 ITEM ::= "item" WHITE DEFUN
94 INCLUDE ::= "include" WHITE
96 VSET ::= "vset" WHITE
97 DEFUN ::= { INCLUDE | VSET }
99 At last we can specify the whole table of contents.
102 TOC ::= DEFUN BEGIN CONTENTS END
104 CONTENTS ::= (ITEMS | SECTIONS)
106 ITEMS ::= ITEM { ITEM }
107 SECTIONS ::= SECTION { SECTION }
108 SECTION ::= DIV_START CONTENTS DIV_END
109 COMMANDS
112 Here we specify the commands used in the grammar. Some commands speci‐
113 fied here were not used in the grammar at all. The usage of these com‐
114 mands is confined to the arguments of other commands.
115 comment text
117 This command declares that the argument text is a comment.
118 include filename
120 This command loads the contents of the file filename for pro‐
121 cessing at its own place.
122 vset varname value
124 This form of the command sets the document variable varname to
125 the specified value. It does not generate output. It is this
126 form the grammar is refering to.
127 vset varname
129 This form of the command returns the value associated with the
130 document variable varname. This form is not used by the grammar
131 and restricted to usage in the arguments of other commands.
132 lb This command adds a left bracket to the output. Its usage is
134 restricted to the arguments of other commands.
135 rb This command adds a right bracket to the output. Its usage is
137 restricted to the arguments of other commands.
138 toc_begin text title
140 This is the command to start a table of contents.
141 The text argument provides a label for the whole group of docu‐
143 ments the index refers to. Often this is the name of the package
144 (or extension) the documents belong to. The title argument pro‐
145 vides the overall title text for the index.
146 toc_end
148 This is the command to close a table of contents.
149 division_start text ?symfile?
151 This command opens a section in the table of contents. Its
152 counterpart is division_end. Together they allow a user to give
153 a table of contents additional structure.
154 The title of the new section is provided by the argument text.
156 If the symbolic filename symfile is present then the section
158 title should link to the referenced document, if links are sup‐
159 ported by the output format.
160 division_end
162 This command closes a section. See division_start above for the
163 detailed explanation.
164 item file text desc
166 This command adds an individual element to the table of con‐
167 tents. Each such element refers to a document. The document is
168 specified through the symbolic name file. The text argument is
169 used to label the reference, whereas the desc provides a short
170 descriptive text of that document.
171 The symbolic names are used to preserve the convertibility of
173 this format to any output format. The actual name of the file
174 will be inserted by the chosen formatting engine when converting
175 the input. This will be based on a mapping from symbolic to
176 actual names given to the engine.
177
179 It is possible to generate a table of contents in doctoc format auto‐
180 matically from a collection of documents in doctools format. All is
181 needed is a special doctools formatting engine which extracts the rele‐
182 vant metadata and some glue code to convert this data to doctoc.
183 The application dtplite is an example for this.
185
187 The example is a table of contents for all manpages in the module
188 base64.
189 [toc_begin Base64 {Table Of Contents}]
191 [item base64.man base64 {Procedures to encode and decode base64}
192 [item uuencode.man uuencode {encode/decoding a binary file}]
193 [item yencode.man yencode {encode/decoding a binary file}]
194 [toc_end]
195
198 doctoc_api, doctoc_fmt, doctools::toc, doctools_fmt
199
201 HTML, LaTeX, TMML, doctoc, documentation, generic markup, keywords,
202 markup, nroff, table of contents, toc
203
205 Copyright (c) 2003-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
206doctools 1.0 doctoc_fmt(n)