1doctools::toc::import::doctoc(nD)ocumentation toodlosctools::toc::import::doctoc(n)
2______________________________________________________________________________
6
8 doctools::toc::import::doctoc - doctoc import plugin
9
11 package require Tcl 8.4
12 package require doctools::toc::import::doctoc ?0.1?
14 package require doctools::toc::parse
16 package require doctools::toc::structure
18 package require doctools::msgcat
20 package require doctools::tcl::parse
22 package require fileutil
24 package require logger
26 package require snit
28 package require struct::list
30 package require struct::set
32 package require struct::stack
34 package require struct::tree
36 package require treeql
38 import string configuration
40______________________________________________________________________________
42
44 This package implements the doctools table of contents import plugin
45 for the parsing of doctoc markup.
46 This is an internal package of doctools, for use by the higher level
48 management packages handling tables of contents, especially doc‐
49 tools::toc::import, the import manager.
50 Using it from a regular interpreter is possible, however only with con‐
52 tortions, and is not recommended. The proper way to use this function‐
53 ality is through the package doctools::toc::import and the import man‐
54 ager objects it provides.
55
57 The API provided by this package satisfies the specification of the
58 doctoc import plugin API version 2.
59 import string configuration
61 This command takes the string and parses it as doctoc markup
62 encoding a table of contents, in the context of the specified
63 configuration (a dictionary). The result of the command is the
64 canonical serialization of that table of contents, in the form
65 specified in section ToC serialization format.
66
68 The doctoc format for tables of contents, also called the doctoc markup
69 language, is too large to be covered in single section. The interested
70 reader should start with the document
71 [1] doctoc language introduction
73 and then proceed from there to the formal specifications, i.e. the doc‐
75 uments
76 [1] doctoc language syntax and
78 [2] doctoc language command reference.
80 to get a thorough understanding of the language.
82
84 Here we specify the format used by the doctools v2 packages to serial‐
85 ize tables of contents as immutable values for transport, comparison,
86 etc.
87 We distinguish between regular and canonical serializations. While a
89 table of contents may have more than one regular serialization only
90 exactly one of them will be canonical.
91 regular serialization
93 [1] The serialization of any table of contents is a nested
95 Tcl dictionary.
96 [2] This dictionary holds a single key, doctools::toc, and
98 its value. This value holds the contents of the table of
99 contents.
100 [3] The contents of the table of contents are a Tcl dictio‐
102 nary holding the title of the table of contents, a label,
103 and its elements. The relevant keys and their values are
104 title The value is a string containing the title of the
106 table of contents.
107 label The value is a string containing a label for the
109 table of contents.
110 items The value is a Tcl list holding the elements of
112 the table, in the order they are to be shown.
113 Each element is a Tcl list holding the type of the
115 item, and its description, in this order. An
116 alternative description would be that it is a Tcl
117 dictionary holding a single key, the item type,
118 mapped to the item description.
119 The two legal item types and their descriptions
121 are
122 reference
124 This item describes a single entry in the
125 table of contents, referencing a single
126 document. To this end its value is a Tcl
127 dictionary containing an id for the refer‐
128 enced document, a label, and a longer tex‐
129 tual description which can be associated
130 with the entry. The relevant keys and
131 their values are
132 id The value is a string containing the
134 id of the document associated with
135 the entry.
136 label The value is a string containing a
138 label for this entry. This string
139 also identifies the entry, and no
140 two entries (references and divi‐
141 sions) in the containing list are
142 allowed to have the same label.
143 desc The value is a string containing a
145 longer description for this entry.
146 division
148 This item describes a group of entries in
149 the table of contents, inducing a hierarchy
150 of entries. To this end its value is a Tcl
151 dictionary containing a label for the
152 group, an optional id to a document for the
153 whole group, and the list of entries in the
154 group. The relevant keys and their values
155 are
156 id The value is a string containing the
158 id of the document associated with
159 the whole group. This key is
160 optional.
161 label The value is a string containing a
163 label for the group. This string
164 also identifies the entry, and no
165 two entries (references and divi‐
166 sions) in the containing list are
167 allowed to have the same label.
168 items The value is a Tcl list holding the
170 elements of the group, in the order
171 they are to be shown. This list has
172 the same structure as the value for
173 the keyword items used to describe
174 the whole table of contents, see
175 above. This closes the recusrive
176 definition of the structure, with
177 divisions holding the same type of
178 elements as the whole table of con‐
179 tents, including other divisions.
180 canonical serialization
182 The canonical serialization of a table of contents has the for‐
183 mat as specified in the previous item, and then additionally
184 satisfies the constraints below, which make it unique among all
185 the possible serializations of this table of contents.
186 [1] The keys found in all the nested Tcl dictionaries are
188 sorted in ascending dictionary order, as generated by
189 Tcl's builtin command lsort -increasing -dict.
190
192 This document, and the package it describes, will undoubtedly contain
193 bugs and other problems. Please report such in the category doctools
194 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
195 also report any ideas for enhancements you may have for either package
196 and/or documentation.
197 When proposing code changes, please provide unified diffs, i.e the out‐
199 put of diff -u.
200 Note further that attachments are strongly preferred over inlined
202 patches. Attachments can be made by going to the Edit form of the
203 ticket immediately after its creation, and then using the left-most
204 button in the secondary navigation bar.
205
207 deserialization, doctoc, doctools, import, table of contents, toc
208
210 Text formatter plugin
211
213 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
214tcllib 0.1 doctools::toc::import::doctoc(n)