1doctools::toc::export::wiki(n)Documentation toolsdoctools::toc::export::wiki(n)
2______________________________________________________________________________
6
8 doctools::toc::export::wiki - wiki export plugin
9
11 package require Tcl 8.4
12 package require doctools::toc::export::wiki ?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 wiki 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 wiki markup encoding the table. The created string is then
43 returned as the result of the command.
44
46 The basic syntax of the wiki markup generated by this plugin are
47 described at http://wiki.tcl.tk/14.
48 The plugin goes beyond the classic markup to generate proper headers
50 and indenting.
51
53 The wiki export plugin recognizes the following configuration variables
54 and changes its behaviour as they specify.
55 dictionary map
57 This standard configuration variable contains a dictionary map‐
58 ping from the (symbolic) document ids in reference entries to
59 the actual filenames and/or urls to be used in the output.
60 Document ids without a mapping are used unchanged.
62 Note that this plugin ignores the standard configuration variables
64 user, file and format, and their values.
65
67 Here we specify the format used by the doctools v2 packages to serial‐
68 ize tables of contents as immutable values for transport, comparison,
69 etc.
70 We distinguish between regular and canonical serializations. While a
72 table of contents may have more than one regular serialization only
73 exactly one of them will be canonical.
74 regular serialization
76 [1] The serialization of any table of contents is a nested
78 Tcl dictionary.
79 [2] This dictionary holds a single key, doctools::toc, and
81 its value. This value holds the contents of the table of
82 contents.
83 [3] The contents of the table of contents are a Tcl dictio‐
85 nary holding the title of the table of contents, a label,
86 and its elements. The relevant keys and their values are
87 title The value is a string containing the title of the
89 table of contents.
90 label The value is a string containing a label for the
92 table of contents.
93 items The value is a Tcl list holding the elements of
95 the table, in the order they are to be shown.
96 Each element is a Tcl list holding the type of the
98 item, and its description, in this order. An
99 alternative description would be that it is a Tcl
100 dictionary holding a single key, the item type,
101 mapped to the item description.
102 The two legal item types and their descriptions
104 are
105 reference
107 This item describes a single entry in the
108 table of contents, referencing a single
109 document. To this end its value is a Tcl
110 dictionary containing an id for the refer‐
111 enced document, a label, and a longer tex‐
112 tual description which can be associated
113 with the entry. The relevant keys and
114 their values are
115 id The value is a string containing the
117 id of the document associated with
118 the entry.
119 label The value is a string containing a
121 label for this entry. This string
122 also identifies the entry, and no
123 two entries (references and divi‐
124 sions) in the containing list are
125 allowed to have the same label.
126 desc The value is a string containing a
128 longer description for this entry.
129 division
131 This item describes a group of entries in
132 the table of contents, inducing a hierarchy
133 of entries. To this end its value is a Tcl
134 dictionary containing a label for the
135 group, an optional id to a document for the
136 whole group, and the list of entries in the
137 group. The relevant keys and their values
138 are
139 id The value is a string containing the
141 id of the document associated with
142 the whole group. This key is
143 optional.
144 label The value is a string containing a
146 label for the group. This string
147 also identifies the entry, and no
148 two entries (references and divi‐
149 sions) in the containing list are
150 allowed to have the same label.
151 items The value is a Tcl list holding the
153 elements of the group, in the order
154 they are to be shown. This list has
155 the same structure as the value for
156 the keyword items used to describe
157 the whole table of contents, see
158 above. This closes the recusrive
159 definition of the structure, with
160 divisions holding the same type of
161 elements as the whole table of con‐
162 tents, including other divisions.
163 canonical serialization
165 The canonical serialization of a table of contents has the for‐
166 mat as specified in the previous item, and then additionally
167 satisfies the constraints below, which make it unique among all
168 the possible serializations of this table of contents.
169 [1] The keys found in all the nested Tcl dictionaries are
171 sorted in ascending dictionary order, as generated by
172 Tcl's builtin command lsort -increasing -dict.
173
175 This document, and the package it describes, will undoubtedly contain
176 bugs and other problems. Please report such in the category doctools
177 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
178 also report any ideas for enhancements you may have for either package
179 and/or documentation.
180 When proposing code changes, please provide unified diffs, i.e the out‐
182 put of diff -u.
183 Note further that attachments are strongly preferred over inlined
185 patches. Attachments can be made by going to the Edit form of the
186 ticket immediately after its creation, and then using the left-most
187 button in the secondary navigation bar.
188
190 doctools, export, serialization, table of contents, toc, wiki
191
193 Text formatter plugin
194
196 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
197tcllib 0.1 doctools::toc::export::wiki(n)