1doctoc_lang_intro(n)          Documentation tools         doctoc_lang_intro(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctoc_lang_intro - doctoc language introduction
9

DESCRIPTION

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
17   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
24       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
29                  ... [division_start {Appendix 1}] ...
30
31
32
33                ... [item thefile \\
34                        label {file description}] ...
35
36
37   BASIC STRUCTURE
38       The most simple document which can be written in doctoc is
39
40
41                  [toc_begin GROUPTITLE TITLE]
42                  [toc_end]
43
44       This also shows us that all doctoc documents consist of only  one  part
45       where we will list items and divisions.
46
47       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
51       We will discuss the commands for each of these two possibilities in the
52       next sections.
53
54   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
61       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
66       Here a made up example for a table of contents of this document:
67
68
69              [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
77
78   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
84       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
89       Of  course,  instead of the nested items we can again use divisions and
90       thus nest arbitrarily deep.
91
92       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
95       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
103       division_end
104              This command closes the last opened and not yet closed division.
105
106       Using this we can recast the last example like this
107
108
109              [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
119
120       Or, to demonstrate deeper nesting
121
122
123              [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
143       And do not forget, it is possible to freely mix  items  and  divisions,
144       and to have empty divisions.
145
146
147              [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
165
166   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
170       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
175
176              [include FILE]
177              [vset VAR VALUE]
178              [toc_begin GROUPTITLE TITLE]
179              ...
180              [toc_end]
181
182       Even  more  important,  these two commands are allowed anywhere where a
183       markup command is allowed, without regard for any other structure.
184
185
186              [toc_begin GROUPTITLE TITLE]
187              [include FILE]
188              [vset VAR VALUE]
189              ...
190              [toc_end]
191
192       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
198   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
205       Our example of their use are the sources of the last  sentence  in  the
206       previous paragraph, with some highlighting added.
207
208
209                ...
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
215

FURTHER READING

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
224       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
227       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

BUGS, IDEAS, FEEDBACK

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
240       When proposing code changes, please provide unified diffs, i.e the out‐
241       put of diff -u.
242
243       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

SEE ALSO

249       doctoc_intro, doctoc_lang_cmdref, doctoc_lang_syntax
250

KEYWORDS

252       doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup,
253       semantic markup
254

CATEGORY

256       Documentation tools
257
259       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
260
261
262
263
264tcllib                                1.0                 doctoc_lang_intro(n)
Impressum