1doctoc_lang_intro(n) Documentation tools doctoc_lang_intro(n)
2______________________________________________________________________________
6
8 doctoc_lang_intro - doctoc language introduction
9
11 This document is an informal introduction to version 1.1 of the doctoc
12 markup language based on a multitude of examples. After reading this a
13 writer should be ready to understand the two parts of the formal speci‐
14 fication, i.e. the doctoc language syntax specification and the doctoc
15 language command reference.
16 FUNDAMENTALS
18 While the doctoc markup language is quite similar to the doctools
19 markup language, in the broadest terms possible, there is one key dif‐
20 ference. A table of contents consists essentially only of markup com‐
21 mands, with no plain text interspersed between them, except for white‐
22 space.
23 Each markup command is a Tcl command surrounded by a matching pair of [
25 and ]. Inside of these delimiters the usual rules for a Tcl command
26 apply with regard to word quotation, nested commands, continuation
27 lines, etc. I.e.
28 ... [division_start {Appendix 1}] ...
30 ... [item thefile \\
34 label {file description}] ...
35 BASIC STRUCTURE
38 The most simple document which can be written in doctoc is
39 [toc_begin GROUPTITLE TITLE]
42 [toc_end]
43 This also shows us that all doctoc documents consist of only one part
45 where we will list items and divisions.
46 The user is free to mix these as she sees fit. This is a change from
48 version 1 of the language, which did not allow this mixing, but only
49 the use of either a series of items or a series of divisions.
50 We will discuss the commands for each of these two possibilities in the
52 next sections.
53 ITEMS
55 Use the command item to put an item into a table of contents. This is
56 essentially a reference to a section, subsection, etc. in the document,
57 or set of documents, the table of contents is for. The command takes
58 three arguments, a symbolic name for the file the item is for and two
59 text to label the item and describe the referenced section.
60 Symbolic names are used to preserve the convertibility of this format
62 to any output format. The actual name of any file will be inserted by
63 the chosen formatting engine when converting the input, based on a map‐
64 ping from symbolic to actual names given to the engine.
65 Here a made up example for a table of contents of this document:
67 [toc_begin Doctoc {Language Introduction}]
70 [item 1 DESCRIPTION]
71 [item 1.1 {Basic structure}]
72 [item 1.2 Items]
73 [item 1.3 Divisions]
74 [item 2 {FURTHER READING}]
75 [toc_end]
76 DIVISIONS
79 One thing of notice in the last example in the previous section is that
80 the referenced sections actually had a nested structure, something
81 which was expressed in the item labels, by using a common prefix for
82 all the sections nested under section 1.
83 This kind of structure can be made more explicit in the doctoc language
85 by using divisions. Instead of using a series of plain items we use a
86 series of divisions for the major references, and then place the nested
87 items inside of these.
88 Of course, instead of the nested items we can again use divisions and
90 thus nest arbitrarily deep.
91 A division is marked by two commands instead of one, one to start it,
93 the other to close the last opened division. They are:
94 division_start
96 This command opens a new division. It takes one or two argu‐
97 ments, the title of the division, and the symbolic name of the
98 file it refers to. The latter is optional. If the symbolic
99 filename is present then the section title should link to the
100 referenced document, if links are supported by the output for‐
101 mat.
102 division_end
104 This command closes the last opened and not yet closed division.
105 Using this we can recast the last example like this
107 [toc_begin Doctoc {Language Introduction}]
110 [division_start DESCRIPTION]
111 [item 1 {Basic structure}]
112 [item 2 Items]
113 [item 3 Divisions]
114 [division_end]
115 [division_start {FURTHER READING}]
116 [division_end]
117 [toc_end]
118 Or, to demonstrate deeper nesting
121 [toc_begin Doctoc {Language Introduction}]
124 [division_start DESCRIPTION]
125 [division_start {Basic structure}]
126 [item 1 Do]
127 [item 2 Re]
128 [division_end]
129 [division_start Items]
130 [item a Fi]
131 [item b Fo]
132 [item c Fa]
133 [division_end]
134 [division_start Divisions]
135 [item 1 Sub]
136 [item 1 Zero]
137 [division_end]
138 [division_end]
139 [division_start {FURTHER READING}]
140 [division_end]
141 [toc_end]
142 And do not forget, it is possible to freely mix items and divisions,
144 and to have empty divisions.
145 [toc_begin Doctoc {Language Introduction}]
148 [item 1 Do]
149 [division_start DESCRIPTION]
150 [division_start {Basic structure}]
151 [item 2 Re]
152 [division_end]
153 [item a Fi]
154 [division_start Items]
155 [item b Fo]
156 [item c Fa]
157 [division_end]
158 [division_start Divisions]
159 [division_end]
160 [division_end]
161 [division_start {FURTHER READING}]
162 [division_end]
163 [toc_end]
164 ADVANCED STRUCTURE
167 In all previous examples we fudged a bit regarding the markup actually
168 allowed to be used before the toc_begin command opening the document.
169 Instead of only whitespace the two templating commands include and vset
171 are also allowed, to enable the writer to either set and/or import con‐
172 figuration settings relevant to the table of contents. I.e. it is pos‐
173 sible to write
174 [include FILE]
177 [vset VAR VALUE]
178 [toc_begin GROUPTITLE TITLE]
179 ...
180 [toc_end]
181 Even more important, these two commands are allowed anywhere where a
183 markup command is allowed, without regard for any other structure.
184 [toc_begin GROUPTITLE TITLE]
187 [include FILE]
188 [vset VAR VALUE]
189 ...
190 [toc_end]
191 The only restriction include has to obey is that the contents of the
193 included file must be valid at the place of the inclusion. I.e. a file
194 included before toc_begin may contain only the templating commands vset
195 and include, a file included in a division may contain only items or
196 divisions commands, etc.
197 ESCAPES
199 Beyond the 6 commands shown so far we have two more available. However
200 their function is not the marking up of toc structure, but the inser‐
201 tion of characters, namely [ and ]. These commands, lb and rb respec‐
202 tively, are required because our use of [ and ] to bracket markup com‐
203 mands makes it impossible to directly use [ and ] within the text.
204 Our example of their use are the sources of the last sentence in the
206 previous paragraph, with some highlighting added.
207 ...
210 These commands, [cmd lb] and [cmd lb] respectively, are required
211 because our use of [lb] and [rb] to bracket markup commands makes it
212 impossible to directly use [lb] and [rb] within the text.
213 ...
214
217 Now that this document has been digested the reader, assumed to be a
218 writer of documentation should be fortified enough to be able to under‐
219 stand the formal doctoc language syntax specification as well. From
220 here on out the doctoc language command reference will also serve as
221 the detailed specification and cheat sheet for all available commands
222 and their syntax.
223 To be able to validate a document while writing it, it is also recom‐
225 mended to familiarize oneself with Tclapps' ultra-configurable dtp.
226 On the other hand, doctoc is perfectly suited for the automatic genera‐
228 tion from doctools documents, and this is the route Tcllib's easy and
229 simple dtplite goes, creating a table of contents for a set of docu‐
230 ments behind the scenes, without the writer having to do so on their
231 own.
232
234 This document, and the package it describes, will undoubtedly contain
235 bugs and other problems. Please report such in the category doctools
236 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
237 also report any ideas for enhancements you may have for either package
238 and/or documentation.
239 When proposing code changes, please provide unified diffs, i.e the out‐
241 put of diff -u.
242 Note further that attachments are strongly preferred over inlined
244 patches. Attachments can be made by going to the Edit form of the
245 ticket immediately after its creation, and then using the left-most
246 button in the secondary navigation bar.
247
249 doctoc_intro, doctoc_lang_cmdref, doctoc_lang_syntax
250
252 doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup,
253 semantic markup
254
256 Documentation tools
257
259 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
260tcllib 1.0 doctoc_lang_intro(n)