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 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 \\
33 label {file description}] ...
34 BASIC STRUCTURE
37 The most simple document which can be written in doctoc is
38 [toc_begin GROUPTITLE TITLE]
40 [toc_end]
41 This also shows us that all doctoc documents consist of only one part
43 where we will list items and divisions.
44 The user does face a choice here however. The table of contents can
46 consist of either a series of items, or of a series of divisions. It is
47 not possible to mix these.
48 We will discuss these two possibilities in the next sections.
50 ITEMS
52 Use the command item to put an item into a table of contents. This is
53 essentially a reference to a section, subsection, etc. in the document,
54 or set of documents, the table of contents is for. The command takes
55 three arguments, a symbolic name for the file the item is for and two
56 text to label the item and describe the referenced section.
57 Symbolic names are used to preserve the convertibility of this format
59 to any output format. The actual name of any file will be inserted by
60 the chosen formatting engine when converting the input, based on a map‐
61 ping from symbolic to actual names given to the engine.
62 Here a made up example for a table of contents of this document:
64 [toc_begin Doctoc {Language Introduction}]
66 [item 1 DESCRIPTION]
67 [item 1.1 {Basic structure}]
68 [item 1.2 Items]
69 [item 1.3 Divisions]
70 [item 2 {FURTHER READING}]
71 [toc_end]
72 DIVISIONS
75 One thing of notice in the last example in the previous section is that
76 the referenced sections actually had a nested structure, something
77 which was expressed in the item labels, by using a common prefix for
78 all the sections nested under section 1.
79 This kind of structure can be made more explicit in the doctoc language
81 by using divisions. Instead of using a series of plain items we use a
82 series of divisions for the major references, and then place the nested
83 items inside of these.
84 Of course, instead of the nested items we can again use divisions and
86 thus nest arbitrarily deep.
87 A division is marked by two commands instead of one, one to start it,
89 the other to close the last opened division. They are:
90 division_start
92 This command opens a new division. It takes one or two argu‐
93 ments, the title of the division, and the symbolic name of the
94 file it refers to. The latter is optional. If the symbolic
95 filename is present then the section title should link to the
96 referenced document, if links are supported by the output for‐
97 mat.
98 division_end
100 This command closes the last opened and not yet closed division.
101 Using this we can recast the last example like this
103 [toc_begin Doctoc {Language Introduction}]
105 [division_start DESCRIPTION]
106 [item 1 {Basic structure}]
107 [item 2 Items]
108 [item 3 Divisions]
109 [division_end]
110 [division_start {FURTHER READING}]
111 [division_end]
112 [toc_end]
113 Or, to demonstrate deeper nesting
116 [toc_begin Doctoc {Language Introduction}]
118 [division_start DESCRIPTION]
119 [division_start {Basic structure}]
120 [item 1 Do]
121 [item 2 Re]
122 [division_end]
123 [division_start Items]
124 [item a Fi]
125 [item b Fo]
126 [item c Fa]
127 [division_end]
128 [division_start Divisions]
129 [item 1 Sub]
130 [item 1 Zero]
131 [division_end]
132 [division_end]
133 [division_start {FURTHER READING}]
134 [division_end]
135 [toc_end]
136 ADVANCED STRUCTURE
139 In all previous examples we fudged a bit regarding the markup actually
140 allowed to be used before the toc_begin command opening the document.
141 Instead of only whitespace the two templating commands include and vset
143 are also allowed, to enable the writer to either set and/or import con‐
144 figuration settings relevant to the table of contents. I.e. it is pos‐
145 sible to write
146 [include FILE]
148 [vset VAR VALUE]
149 [toc_begin GROUPTITLE TITLE]
150 [toc_end]
151 Even more important, these two commands are allowed anywhere where a
153 markup command is allowed, without regard for any other structure.
154 [toc_begin GROUPTITLE TITLE]
156 [include FILE]
157 [vset VAR VALUE]
158 [toc_end]
159 The only restriction include has to obey is that the contents of the
161 included file must be valid at the place of the inclusion. I.e. a file
162 included before toc_begin may contain only the templating commands vset
163 and include, a file included in a division may contain only items or
164 divisions commands, etc.
165 ESCAPES
167 Beyond the 6 commands shown so far we have two more available. However
168 their function is not the marking up of toc structure, but the inser‐
169 tion of characters, namely [ and ]. These commands, lb and rb respec‐
170 tively, are required because our use of [ and ] to bracket markup com‐
171 mands makes it impossible to directly use [ and ] within the text.
172 Our example of their use are the sources of the last sentence in the
174 previous paragraph, with some highlighting added.
175 ...
177 These commands, [cmd lb] and [cmd lb] respectively, are required
178 because our use of [lb] and [rb] to bracket markup commands makes it
179 impossible to directly use [lb] and [rb] within the text.
180 ...
181
184 Now that this document has been digested the reader, assumed to be a
185 writer of documentation should be fortified enough to be able to under‐
186 stand the formal doctoc language syntax specification as well. From
187 here on out the doctoc language command reference will also serve as
188 the detailed specification and cheat sheet for all available commands
189 and their syntax.
190 To be able to validate a document while writing it, it is also recom‐
192 mended to familiarize oneself with Tclapps' ultra-configurable dtp.
193 On the other hand, doctoc is perfectly suited for the automatic genera‐
195 tion from doctools documents, and this is the route Tcllib's easy and
196 simple dtplite goes, creating a table of contents for a set of docu‐
197 ments behind the scenes, without the writer having to do so on their
198 own.
199
201 This document, will undoubtedly contain bugs and other problems.
202 Please report such in the category doctools of the Tcllib SF Trackers
203 [http://sourceforge.net/tracker/?group_id=12883]. Please also report
204 any ideas for enhancements you may have.
205
207 doctoc_intro, doctoc_lang_cmdref, doctoc_lang_syntax
208
210 doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup,
211 semantic markup
212
214 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
215doctools 1.0 doctoc_lang_intro(n)