1doctools::toc::parse(n)       Documentation tools      doctools::toc::parse(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::toc::parse - Parsing text in doctoc format
9

SYNOPSIS

11       package require doctools::toc::parse  ?0.1?
12
13       package require Tcl  8.4
14
15       package require doctools::toc::structure
16
17       package require doctools::msgcat
18
19       package require doctools::tcl::parse
20
21       package require fileutil
22
23       package require logger
24
25       package require snit
26
27       package require struct::list
28
29       package require struct::stack
30
31       ::doctools::toc::parse text text
32
33       ::doctools::toc::parse file path
34
35       ::doctools::toc::parse includes
36
37       ::doctools::toc::parse include add path
38
39       ::doctools::toc::parse include remove path
40
41       ::doctools::toc::parse include clear
42
43       ::doctools::toc::parse vars
44
45       ::doctools::toc::parse var set name value
46
47       ::doctools::toc::parse var unset name
48
49       ::doctools::toc::parse var clear ?pattern?
50
51______________________________________________________________________________
52

DESCRIPTION

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
59       This is an internal package of doctools, for use by  the  higher  level
60       packages handling doctoc documents.
61

API

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
70              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
75       ::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
79       ::doctools::toc::parse includes
80              This  method  returns the current list of search paths used when
81              looking for include files.
82
83       ::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
89       ::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
95       ::doctools::toc::parse include clear
96              This method clears the list of search paths for include files.
97
98       ::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
103       ::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
109       ::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
114       ::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
120              The pattern matching is done with string match, and the  default
121              pattern used when none is specified, is *.
122

PARSE ERRORS

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
128       However,  the errorCode attached to the message is machine-readable and
129       has the following format:
130
131       [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
135       [2]    Each error element will be a list  containing  six  strings  de‐
136              scribing an error in detail. The strings will be
137
138              [1]    The  path  of the file the error occurred in. This may be
139                     empty.
140
141              [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
146              [3]    The  line  the  first  character  after  the error is on.
147                     Lines are counted from one.
148
149              [4]    The column the first character after  the  error  is  at.
150                     Columns are counted from zero.
151
152              [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
158              [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

[DOCTOC] NOTATION OF TABLES OF CONTENTS

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
168       [1]    doctoc language introduction
169
170       and then proceed from there to the formal specifications, i.e. the doc‐
171       uments
172
173       [1]    doctoc language syntax and
174
175       [2]    doctoc language command reference.
176
177       to get a thorough understanding of the language.
178

TOC SERIALIZATION FORMAT

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
184       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
188       regular serialization
189
190              [1]    The  serialization  of  any table of contents is a nested
191                     Tcl dictionary.
192
193              [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
197              [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
201                     title  The value is a string containing the title of  the
202                            table of contents.
203
204                     label  The  value  is a string containing a label for the
205                            table of contents.
206
207                     items  The value is a Tcl list holding  the  elements  of
208                            the table, in the order they are to be shown.
209
210                            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
216                            The  two  legal  item types and their descriptions
217                            are
218
219                            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
229                                   id     The value is a string containing the
230                                          id of the document  associated  with
231                                          the entry.
232
233                                   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
240                                   desc   The value is a string  containing  a
241                                          longer description for this entry.
242
243                            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
253                                   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
258                                   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
265                                   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
277       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
283              [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

BUGS, IDEAS, FEEDBACK

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
294       When proposing code changes, please provide unified diffs, i.e the out‐
295       put of diff -u.
296
297       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

KEYWORDS

303       doctoc, doctools, lexer, parser
304

CATEGORY

306       Documentation tools
307
309       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
310
311
312
313
314tcllib                                 1               doctools::toc::parse(n)
Impressum