1doctools::toc::export::doctoc(nD)ocumentation toodlosctools::toc::export::doctoc(n)
2______________________________________________________________________________
6
8 doctools::toc::export::doctoc - doctoc export plugin
9
11 package require Tcl 8.4
12 package require doctools::toc::export::doctoc ?0.1?
14 export serial configuration
16______________________________________________________________________________
18
20 This package implements the doctools table of contents export plugin
21 for the generation of doctoc markup.
22 This is an internal package of doctools, for use by the higher level
24 management packages handling tables of contents, especially doc‐
25 tools::toc::export, the export manager.
26 Using it from a regular interpreter is possible, however only with con‐
28 tortions, and is not recommended. The proper way to use this function‐
29 ality is through the package doctools::toc::export and the export man‐
30 ager objects it provides.
31
33 The API provided by this package satisfies the specification of the
34 doctoc export plugin API version 2.
35 export serial configuration
37 This command takes the canonical serialization of a table of
38 contents, as specified in section ToC serialization format, and
39 contained in serial, the configuration, a dictionary, and gener‐
40 ates doctoc markup encoding the table. The created string is
41 then returned as the result of the command.
42
44 The doctoc format for tables of contents, also called the doctoc markup
45 language, is too large to be covered in single section. The interested
46 reader should start with the document
47 [1] doctoc language introduction
49 and then proceed from there to the formal specifications, i.e. the doc‐
51 uments
52 [1] doctoc language syntax and
54 [2] doctoc language command reference.
56 to get a thorough understanding of the language.
58
60 The doctoc export plugin recognizes the following configuration vari‐
61 ables and changes its behaviour as they specify.
62 string user
64 This standard configuration variable contains the name of the
65 user running the process which invoked the export plugin. The
66 plugin puts this information into the provenance comment at the
67 beginning of the generated document.
68 string file
70 This standard configuration variable contains the name of the
71 file the table of contents came from. This variable may not be
72 set or contain the empty string. The plugin puts this informa‐
73 tion, if defined, i.e. set and not the empty string, into the
74 provenance comment at the beginning of the generated document.
75 boolean newlines
77 If this flag is set the plugin will break the generated doctoc
78 code across lines, with each markup command on a separate line.
79 If this flag is not set (the default), the whole document will
81 be written on a single line, with minimum spacing between all
82 elements.
83 boolean indented
85 If this flag is set the plugin will indent the markup commands
86 according to the structure of tables of contents. To make this
87 work this also implies that newlines is set. This effect is
88 independent of the value for aligned however.
89 If this flag is not set (the default), the output is formatted
91 as per the value of newlines, and no indenting is done.
92 boolean aligned
94 If this flag is set the generator ensures that the arguments for
95 the item commands in a division are aligned vertically for a
96 nice table effect. To make this work this also implies that new‐
97 lines is set. This effect is independent of the value for
98 indented however.
99 If this flag is not set (the default), the output is formatted
101 as per the values of newlines and indented, and no alignment is
102 done.
103 Note that this plugin ignores the standard configuration variables for‐
105 mat, and map, and their values.
106
108 Here we specify the format used by the doctools v2 packages to serial‐
109 ize tables of contents as immutable values for transport, comparison,
110 etc.
111 We distinguish between regular and canonical serializations. While a
113 table of contents may have more than one regular serialization only
114 exactly one of them will be canonical.
115 regular serialization
117 [1] The serialization of any table of contents is a nested
119 Tcl dictionary.
120 [2] This dictionary holds a single key, doctools::toc, and
122 its value. This value holds the contents of the table of
123 contents.
124 [3] The contents of the table of contents are a Tcl dictio‐
126 nary holding the title of the table of contents, a label,
127 and its elements. The relevant keys and their values are
128 title The value is a string containing the title of the
130 table of contents.
131 label The value is a string containing a label for the
133 table of contents.
134 items The value is a Tcl list holding the elements of
136 the table, in the order they are to be shown.
137 Each element is a Tcl list holding the type of the
139 item, and its description, in this order. An
140 alternative description would be that it is a Tcl
141 dictionary holding a single key, the item type,
142 mapped to the item description.
143 The two legal item types and their descriptions
145 are
146 reference
148 This item describes a single entry in the
149 table of contents, referencing a single
150 document. To this end its value is a Tcl
151 dictionary containing an id for the refer‐
152 enced document, a label, and a longer tex‐
153 tual description which can be associated
154 with the entry. The relevant keys and
155 their values are
156 id The value is a string containing the
158 id of the document associated with
159 the entry.
160 label The value is a string containing a
162 label for this entry. This string
163 also identifies the entry, and no
164 two entries (references and divi‐
165 sions) in the containing list are
166 allowed to have the same label.
167 desc The value is a string containing a
169 longer description for this entry.
170 division
172 This item describes a group of entries in
173 the table of contents, inducing a hierarchy
174 of entries. To this end its value is a Tcl
175 dictionary containing a label for the
176 group, an optional id to a document for the
177 whole group, and the list of entries in the
178 group. The relevant keys and their values
179 are
180 id The value is a string containing the
182 id of the document associated with
183 the whole group. This key is
184 optional.
185 label The value is a string containing a
187 label for the group. This string
188 also identifies the entry, and no
189 two entries (references and divi‐
190 sions) in the containing list are
191 allowed to have the same label.
192 items The value is a Tcl list holding the
194 elements of the group, in the order
195 they are to be shown. This list has
196 the same structure as the value for
197 the keyword items used to describe
198 the whole table of contents, see
199 above. This closes the recusrive
200 definition of the structure, with
201 divisions holding the same type of
202 elements as the whole table of con‐
203 tents, including other divisions.
204 canonical serialization
206 The canonical serialization of a table of contents has the for‐
207 mat as specified in the previous item, and then additionally
208 satisfies the constraints below, which make it unique among all
209 the possible serializations of this table of contents.
210 [1] The keys found in all the nested Tcl dictionaries are
212 sorted in ascending dictionary order, as generated by
213 Tcl's builtin command lsort -increasing -dict.
214
216 This document, and the package it describes, will undoubtedly contain
217 bugs and other problems. Please report such in the category doctools
218 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
219 also report any ideas for enhancements you may have for either package
220 and/or documentation.
221 When proposing code changes, please provide unified diffs, i.e the out‐
223 put of diff -u.
224 Note further that attachments are strongly preferred over inlined
226 patches. Attachments can be made by going to the Edit form of the
227 ticket immediately after its creation, and then using the left-most
228 button in the secondary navigation bar.
229
231 doctoc, doctools, export, serialization, table of contents, toc
232
234 Text formatter plugin
235
237 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
238tcllib 0.1 doctools::toc::export::doctoc(n)