1doctools::idx::export::wiki(n)Documentation toolsdoctools::idx::export::wiki(n)
2______________________________________________________________________________
6
8 doctools::idx::export::wiki - wiki export plugin
9
11 package require Tcl 8.4
12 package require doctools::idx::export::wiki ?0.2?
14 package require doctools::text
16 export serial configuration
18______________________________________________________________________________
20
22 This package implements the doctools keyword index export plugin for
23 the generation of wiki markup.
24 This is an internal package of doctools, for use by the higher level
26 management packages handling keyword indices, especially doc‐
27 tools::idx::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::idx::export and the export man‐
32 ager objects it provides.
33
35 The API provided by this package satisfies the specification of the
36 docidx export plugin API version 2.
37 export serial configuration
39 This command takes the canonical serialization of a keyword
40 index, as specified in section Keyword index serialization for‐
41 mat, and contained in serial, the configuration, a dictionary,
42 and generates wiki markup encoding the index. The created
43 string is then 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 either a table or indented list of the keywords and their refer‐
51 ences.
52
54 The wiki export plugin recognizes the following configuration variables
55 and changes its behaviour as they specify.
56 dictionary map
58 This standard configuration variable contains a dictionary map‐
59 ping from the symbolic files names in manpage references to the
60 actual filenames and/or urls to be used in the output.
61 Url references and symbolic file names without a mapping are
63 used unchanged.
64 enum style
66 This variable recognizes two values as legal, list (default),
67 and table. Depending on the value the plugin generates either a
68 list- or table-based wiki page for the index.
69 Note that this plugin ignores the standard configuration variables
71 user, file and format, and their values.
72
74 Here we specify the format used by the doctools v2 packages to serial‐
75 ize keyword indices as immutable values for transport, comparison, etc.
76 We distinguish between regular and canonical serializations. While a
78 keyword index may have more than one regular serialization only exactly
79 one of them will be canonical.
80 regular serialization
82 [1] An index serialization is a nested Tcl dictionary.
84 [2] This dictionary holds a single key, doctools::idx, and
86 its value. This value holds the contents of the index.
87 [3] The contents of the index are a Tcl dictionary holding
89 the title of the index, a label, and the keywords and
90 references. The relevant keys and their values are
91 title The value is a string containing the title of the
93 index.
94 label The value is a string containing a label for the
96 index.
97 keywords
99 The value is a Tcl dictionary, using the keywords
100 known to the index as keys. The associated values
101 are lists containing the identifiers of the refer‐
102 ences associated with that particular keyword.
103 Any reference identifier used in these lists has
105 to exist as a key in the references dictionary,
106 see the next item for its definition.
107 references
109 The value is a Tcl dictionary, using the identi‐
110 fiers for the references known to the index as
111 keys. The associated values are 2-element lists
112 containing the type and label of the reference, in
113 this order.
114 Any key here has to be associated with at least
116 one keyword, i.e. occur in at least one of the
117 reference lists which are the values in the key‐
118 words dictionary, see previous item for its defi‐
119 nition.
120 [4] The type of a reference can be one of two values,
122 manpage
124 The identifier of the reference is interpreted as
125 symbolic file name, referring to one of the docu‐
126 ments the index was made for.
127 url The identifier of the reference is interpreted as
129 an url, referring to some external location, like
130 a website, etc.
131 canonical serialization
133 The canonical serialization of a keyword index has the format as
134 specified in the previous item, and then additionally satisfies
135 the constraints below, which make it unique among all the possi‐
136 ble serializations of the keyword index.
137 [1] The keys found in all the nested Tcl dictionaries are
139 sorted in ascending dictionary order, as generated by
140 Tcl's builtin command lsort -increasing -dict.
141 [2] The references listed for each keyword of the index, if
143 any, are listed in ascending dictionary order of their
144 labels, as generated by Tcl's builtin command lsort
145 -increasing -dict.
146
148 This document, and the package it describes, will undoubtedly contain
149 bugs and other problems. Please report such in the category doctools
150 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
151 also report any ideas for enhancements you may have for either package
152 and/or documentation.
153 When proposing code changes, please provide unified diffs, i.e the out‐
155 put of diff -u.
156 Note further that attachments are strongly preferred over inlined
158 patches. Attachments can be made by going to the Edit form of the
159 ticket immediately after its creation, and then using the left-most
160 button in the secondary navigation bar.
161
163 doctools, export, index, serialization, wiki
164
166 Text formatter plugin
167
169 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
170tcllib 0.2 doctools::idx::export::wiki(n)