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

NAME

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

SYNOPSIS

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

DESCRIPTION

22       This  package  implements  the doctools table of contents export plugin
23       for the generation of wiki markup.
24
25       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
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::toc::export and the export  man‐
32       ager objects it provides.
33

API

35       The  API  provided  by  this package satisfies the specification of the
36       doctoc export plugin API version 2.
37
38       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

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 indenting.
51

CONFIGURATION

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

TOC SERIALIZATION FORMAT

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
71       We distinguish between regular and canonical serializations.   While  a
72       table of contents may have more than one regular serialization only ex‐
73       actly one of them will be canonical.
74
75       regular serialization
76
77              [1]    The serialization of any table of contents  is  a  nested
78                     Tcl dictionary.
79
80              [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
84              [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
88                     title  The  value is a string containing the title of the
89                            table of contents.
90
91                     label  The value is a string containing a label  for  the
92                            table of contents.
93
94                     items  The  value  is  a Tcl list holding the elements of
95                            the table, in the order they are to be shown.
96
97                            Each element is a Tcl list holding the type of the
98                            item,  and  its description, in this order. An al‐
99                            ternative description would be that it  is  a  Tcl
100                            dictionary  holding  a  single key, the item type,
101                            mapped to the item description.
102
103                            The two legal item types  and  their  descriptions
104                            are
105
106                            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
116                                   id     The value is a string containing the
117                                          id  of  the document associated with
118                                          the entry.
119
120                                   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
127                                   desc   The  value  is a string containing a
128                                          longer description for this entry.
129
130                            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
140                                   id     The value is a string containing the
141                                          id of the document  associated  with
142                                          the  whole  group.  This  key is op‐
143                                          tional.
144
145                                   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
152                                   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
164       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
170              [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

BUGS, IDEAS, FEEDBACK

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
181       When proposing code changes, please provide unified diffs, i.e the out‐
182       put of diff -u.
183
184       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

KEYWORDS

190       doctools, export, serialization, table of contents, toc, wiki
191

CATEGORY

193       Text formatter plugin
194
196       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
197
198
199
200
201tcllib                                0.1       doctools::toc::export::wiki(n)
Impressum