1doctools::idx::export::wiki(n)Documentation toolsdoctools::idx::export::wiki(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::idx::export::wiki - wiki export plugin
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::idx::export::wiki  ?0.2?
14
15       package require doctools::text
16
17       export serial configuration
18
19______________________________________________________________________________
20

DESCRIPTION

22       This  package  implements  the doctools keyword index export plugin for
23       the generation of wiki markup.
24
25       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
29       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

API

35       The API provided by this package satisfies the specification of the do‐
36       cidx export plugin API version 2.
37
38       export serial configuration
39              This command takes the canonical serialization of a keyword  in‐
40              dex, as specified in section Keyword index serialization format,
41              and contained in serial, the configuration,  a  dictionary,  and
42              generates wiki markup encoding the index.  The created string is
43              then returned as the result of the command.
44

WIKI MARKUP

46       The basic syntax of the wiki markup generated by this  plugin  are  de‐
47       scribed at http://wiki.tcl.tk/14.
48
49       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

CONFIGURATION

54       The wiki export plugin recognizes the following configuration variables
55       and changes its behaviour as they specify.
56
57       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
62              Url references and symbolic file names  without  a  mapping  are
63              used unchanged.
64
65       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
70       Note  that  this  plugin  ignores  the standard configuration variables
71       user, file and format, and their values.
72

KEYWORD INDEX SERIALIZATION FORMAT

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
77       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
81       regular serialization
82
83              [1]    An index serialization is a nested Tcl dictionary.
84
85              [2]    This  dictionary  holds  a single key, doctools::idx, and
86                     its value. This value holds the contents of the index.
87
88              [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
92                     title  The value is a string containing the title of  the
93                            index.
94
95                     label  The  value  is a string containing a label for the
96                            index.
97
98                     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
104                            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
108                     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
115                            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
121              [4]    The type of a reference can be one of two values,
122
123                     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
128                     url    The  identifier of the reference is interpreted as
129                            an url, referring to some external location,  like
130                            a website, etc.
131
132       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
138              [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
142              [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  -in‐
145                     creasing -dict.
146

BUGS, IDEAS, FEEDBACK

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
154       When proposing code changes, please provide unified diffs, i.e the out‐
155       put of diff -u.
156
157       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

KEYWORDS

163       doctools, export, index, serialization, wiki
164

CATEGORY

166       Text formatter plugin
167
169       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
170
171
172
173
174tcllib                                0.2       doctools::idx::export::wiki(n)
Impressum