1doctools::toc::export::text(n)Documentation toolsdoctools::toc::export::text(n)
2______________________________________________________________________________
6
8 doctools::toc::export::text - plain text export plugin
9
11 package require Tcl 8.4
12 package require doctools::toc::export::text ?0.1?
14 package require doctools::text
16 export serial configuration
18______________________________________________________________________________
20
22 This package implements the doctools table of contents export plugin
23 for the generation of plain text markup.
24 This is an internal package of doctools, for use by the higher level
26 management packages handling tables of contents, especially doc‐
27 tools::toc::export, the export manager.
28 Using it from a regular interpreter is possible, however only with con‐
30 tortions, and is not recommended. The proper way to use this function‐
31 ality is through the package doctools::toc::export and the export man‐
32 ager objects it provides.
33
35 The API provided by this package satisfies the specification of the
36 doctoc export plugin API version 2.
37 export serial configuration
39 This command takes the canonical serialization of a table of
40 contents, as specified in section ToC serialization format, and
41 contained in serial, the configuration, a dictionary, and gener‐
42 ates plain text markup encoding the table. The created string
43 is then returned as the result of the command.
44
46 The text export plugin recognizes the following configuration variables
47 and changes its behaviour as they specify.
48 dictionary map
50 This standard configuration variable contains a dictionary map‐
51 ping from the (symbolic) document ids in reference entries to
52 the actual filenames and/or urls to be used in the output.
53 Document ids without a mapping are used unchanged.
55 Note that this plugin ignores the standard configuration variables
57 user, file, and format, and their values.
58
60 Here we specify the format used by the doctools v2 packages to serial‐
61 ize tables of contents as immutable values for transport, comparison,
62 etc.
63 We distinguish between regular and canonical serializations. While a
65 table of contents may have more than one regular serialization only
66 exactly one of them will be canonical.
67 regular serialization
69 [1] The serialization of any table of contents is a nested
71 Tcl dictionary.
72 [2] This dictionary holds a single key, doctools::toc, and
74 its value. This value holds the contents of the table of
75 contents.
76 [3] The contents of the table of contents are a Tcl dictio‐
78 nary holding the title of the table of contents, a label,
79 and its elements. The relevant keys and their values are
80 title The value is a string containing the title of the
82 table of contents.
83 label The value is a string containing a label for the
85 table of contents.
86 items The value is a Tcl list holding the elements of
88 the table, in the order they are to be shown.
89 Each element is a Tcl list holding the type of the
91 item, and its description, in this order. An
92 alternative description would be that it is a Tcl
93 dictionary holding a single key, the item type,
94 mapped to the item description.
95 The two legal item types and their descriptions
97 are
98 reference
100 This item describes a single entry in the
101 table of contents, referencing a single
102 document. To this end its value is a Tcl
103 dictionary containing an id for the refer‐
104 enced document, a label, and a longer tex‐
105 tual description which can be associated
106 with the entry. The relevant keys and
107 their values are
108 id The value is a string containing the
110 id of the document associated with
111 the entry.
112 label The value is a string containing a
114 label for this entry. This string
115 also identifies the entry, and no
116 two entries (references and divi‐
117 sions) in the containing list are
118 allowed to have the same label.
119 desc The value is a string containing a
121 longer description for this entry.
122 division
124 This item describes a group of entries in
125 the table of contents, inducing a hierarchy
126 of entries. To this end its value is a Tcl
127 dictionary containing a label for the
128 group, an optional id to a document for the
129 whole group, and the list of entries in the
130 group. The relevant keys and their values
131 are
132 id The value is a string containing the
134 id of the document associated with
135 the whole group. This key is
136 optional.
137 label The value is a string containing a
139 label for the group. This string
140 also identifies the entry, and no
141 two entries (references and divi‐
142 sions) in the containing list are
143 allowed to have the same label.
144 items The value is a Tcl list holding the
146 elements of the group, in the order
147 they are to be shown. This list has
148 the same structure as the value for
149 the keyword items used to describe
150 the whole table of contents, see
151 above. This closes the recusrive
152 definition of the structure, with
153 divisions holding the same type of
154 elements as the whole table of con‐
155 tents, including other divisions.
156 canonical serialization
158 The canonical serialization of a table of contents has the for‐
159 mat as specified in the previous item, and then additionally
160 satisfies the constraints below, which make it unique among all
161 the possible serializations of this table of contents.
162 [1] The keys found in all the nested Tcl dictionaries are
164 sorted in ascending dictionary order, as generated by
165 Tcl's builtin command lsort -increasing -dict.
166
168 This document, and the package it describes, will undoubtedly contain
169 bugs and other problems. Please report such in the category doctools
170 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
171 also report any ideas for enhancements you may have for either package
172 and/or documentation.
173 When proposing code changes, please provide unified diffs, i.e the out‐
175 put of diff -u.
176 Note further that attachments are strongly preferred over inlined
178 patches. Attachments can be made by going to the Edit form of the
179 ticket immediately after its creation, and then using the left-most
180 button in the secondary navigation bar.
181
183 doctools, export, plain text, serialization, table of contents, toc
184
186 Text formatter plugin
187
189 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
190tcllib 0.1 doctools::toc::export::text(n)