1doctools::toc::parse(n) Documentation tools doctools::toc::parse(n)
2______________________________________________________________________________
6
8 doctools::toc::parse - Parsing text in doctoc format
9
11 package require doctools::toc::parse ?0.1?
12 package require Tcl 8.4
14 package require doctools::toc::structure
16 package require doctools::msgcat
18 package require doctools::tcl::parse
20 package require fileutil
22 package require logger
24 package require snit
26 package require struct::list
28 package require struct::stack
30 ::doctools::toc::parse text text
32 ::doctools::toc::parse file path
34 ::doctools::toc::parse includes
36 ::doctools::toc::parse include add path
38 ::doctools::toc::parse include remove path
40 ::doctools::toc::parse include clear
42 ::doctools::toc::parse vars
44 ::doctools::toc::parse var set name value
46 ::doctools::toc::parse var unset name
48 ::doctools::toc::parse var clear ?pattern?
50______________________________________________________________________________
52
54 This package provides commands to parse text written in the doctoc
55 markup language and convert it into the canonical serialization of the
56 table of contents encoded in the text. See the section ToC serializa‐
57 tion format for specification of their format.
58 This is an internal package of doctools, for use by the higher level
60 packages handling doctoc documents.
61
63 ::doctools::toc::parse text text
64 The command takes the string contained in text and parses it un‐
65 der the assumption that it contains a document written using the
66 doctoc markup language. An error is thrown if this assumption is
67 found to be false. The format of these errors is described in
68 section Parse errors.
69 When successful the command returns the canonical serialization
71 of the table of contents which was encoded in the text. See the
72 section ToC serialization format for specification of that for‐
73 mat.
74 ::doctools::toc::parse file path
76 The same as text, except that the text to parse is read from the
77 file specified by path.
78 ::doctools::toc::parse includes
80 This method returns the current list of search paths used when
81 looking for include files.
82 ::doctools::toc::parse include add path
84 This method adds the path to the list of paths searched when
85 looking for an include file. The call is ignored if the path is
86 already in the list of paths. The method returns the empty
87 string as its result.
88 ::doctools::toc::parse include remove path
90 This method removes the path from the list of paths searched
91 when looking for an include file. The call is ignored if the
92 path is not contained in the list of paths. The method returns
93 the empty string as its result.
94 ::doctools::toc::parse include clear
96 This method clears the list of search paths for include files.
97 ::doctools::toc::parse vars
99 This method returns a dictionary containing the current set of
100 predefined variables known to the vset markup command during
101 processing.
102 ::doctools::toc::parse var set name value
104 This method adds the variable name to the set of predefined
105 variables known to the vset markup command during processing,
106 and gives it the specified value. The method returns the empty
107 string as its result.
108 ::doctools::toc::parse var unset name
110 This method removes the variable name from the set of predefined
111 variables known to the vset markup command during processing.
112 The method returns the empty string as its result.
113 ::doctools::toc::parse var clear ?pattern?
115 This method removes all variables matching the pattern from the
116 set of predefined variables known to the vset markup command
117 during processing. The method returns the empty string as its
118 result.
119 The pattern matching is done with string match, and the default
121 pattern used when none is specified, is *.
122
124 The format of the parse error messages thrown when encountering viola‐
125 tions of the doctoc markup syntax is human readable and not intended
126 for processing by machines. As such it is not documented.
127 However, the errorCode attached to the message is machine-readable and
129 has the following format:
130 [1] The error code will be a list, each element describing a single
132 error found in the input. The list has at least one element,
133 possibly more.
134 [2] Each error element will be a list containing six strings de‐
136 scribing an error in detail. The strings will be
137 [1] The path of the file the error occurred in. This may be
139 empty.
140 [2] The range of the token the error was found at. This range
142 is a two-element list containing the offset of the first
143 and last character in the range, counted from the begin‐
144 ning of the input (file). Offsets are counted from zero.
145 [3] The line the first character after the error is on.
147 Lines are counted from one.
148 [4] The column the first character after the error is at.
150 Columns are counted from zero.
151 [5] The message code of the error. This value can be used as
153 argument to msgcat::mc to obtain a localized error mes‐
154 sage, assuming that the application had a suitable call
155 of doctools::msgcat::init to initialize the necessary
156 message catalogs (See package doctools::msgcat).
157 [6] A list of details for the error, like the markup command
159 involved. In the case of message code doctoc/include/syn‐
160 tax this value is the set of errors found in the included
161 file, using the format described here.
162
164 The doctoc format for tables of contents, also called the doctoc markup
165 language, is too large to be covered in single section. The interested
166 reader should start with the document
167 [1] doctoc language introduction
169 and then proceed from there to the formal specifications, i.e. the doc‐
171 uments
172 [1] doctoc language syntax and
174 [2] doctoc language command reference.
176 to get a thorough understanding of the language.
178
180 Here we specify the format used by the doctools v2 packages to serial‐
181 ize tables of contents as immutable values for transport, comparison,
182 etc.
183 We distinguish between regular and canonical serializations. While a
185 table of contents may have more than one regular serialization only ex‐
186 actly one of them will be canonical.
187 regular serialization
189 [1] The serialization of any table of contents is a nested
191 Tcl dictionary.
192 [2] This dictionary holds a single key, doctools::toc, and
194 its value. This value holds the contents of the table of
195 contents.
196 [3] The contents of the table of contents are a Tcl dictio‐
198 nary holding the title of the table of contents, a label,
199 and its elements. The relevant keys and their values are
200 title The value is a string containing the title of the
202 table of contents.
203 label The value is a string containing a label for the
205 table of contents.
206 items The value is a Tcl list holding the elements of
208 the table, in the order they are to be shown.
209 Each element is a Tcl list holding the type of the
211 item, and its description, in this order. An al‐
212 ternative description would be that it is a Tcl
213 dictionary holding a single key, the item type,
214 mapped to the item description.
215 The two legal item types and their descriptions
217 are
218 reference
220 This item describes a single entry in the
221 table of contents, referencing a single
222 document. To this end its value is a Tcl
223 dictionary containing an id for the refer‐
224 enced document, a label, and a longer tex‐
225 tual description which can be associated
226 with the entry. The relevant keys and
227 their values are
228 id The value is a string containing the
230 id of the document associated with
231 the entry.
232 label The value is a string containing a
234 label for this entry. This string
235 also identifies the entry, and no
236 two entries (references and divi‐
237 sions) in the containing list are
238 allowed to have the same label.
239 desc The value is a string containing a
241 longer description for this entry.
242 division
244 This item describes a group of entries in
245 the table of contents, inducing a hierarchy
246 of entries. To this end its value is a Tcl
247 dictionary containing a label for the
248 group, an optional id to a document for the
249 whole group, and the list of entries in the
250 group. The relevant keys and their values
251 are
252 id The value is a string containing the
254 id of the document associated with
255 the whole group. This key is op‐
256 tional.
257 label The value is a string containing a
259 label for the group. This string
260 also identifies the entry, and no
261 two entries (references and divi‐
262 sions) in the containing list are
263 allowed to have the same label.
264 items The value is a Tcl list holding the
266 elements of the group, in the order
267 they are to be shown. This list has
268 the same structure as the value for
269 the keyword items used to describe
270 the whole table of contents, see
271 above. This closes the recusrive
272 definition of the structure, with
273 divisions holding the same type of
274 elements as the whole table of con‐
275 tents, including other divisions.
276 canonical serialization
278 The canonical serialization of a table of contents has the for‐
279 mat as specified in the previous item, and then additionally
280 satisfies the constraints below, which make it unique among all
281 the possible serializations of this table of contents.
282 [1] The keys found in all the nested Tcl dictionaries are
284 sorted in ascending dictionary order, as generated by
285 Tcl's builtin command lsort -increasing -dict.
286
288 This document, and the package it describes, will undoubtedly contain
289 bugs and other problems. Please report such in the category doctools
290 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
291 also report any ideas for enhancements you may have for either package
292 and/or documentation.
293 When proposing code changes, please provide unified diffs, i.e the out‐
295 put of diff -u.
296 Note further that attachments are strongly preferred over inlined
298 patches. Attachments can be made by going to the Edit form of the
299 ticket immediately after its creation, and then using the left-most
300 button in the secondary navigation bar.
301
303 doctoc, doctools, lexer, parser
304
306 Documentation tools
307
309 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
310tcllib 1 doctools::toc::parse(n)