1 2[//000000001]: # (doctools::toc::export::wiki \- Documentation tools) 3[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') 4[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) 5[//000000004]: # (doctools::toc::export::wiki\(n\) 0\.1 tcllib "Documentation tools") 6 7<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a 8href="../../../toc.md">Table Of Contents</a> | <a 9href="../../../../index.md">Keyword Index</a> | <a 10href="../../../../toc0.md">Categories</a> | <a 11href="../../../../toc1.md">Modules</a> | <a 12href="../../../../toc2.md">Applications</a> ] <hr> 13 14# NAME 15 16doctools::toc::export::wiki \- wiki export plugin 17 18# <a name='toc'></a>Table Of Contents 19 20 - [Table Of Contents](#toc) 21 22 - [Synopsis](#synopsis) 23 24 - [Description](#section1) 25 26 - [API](#section2) 27 28 - [Wiki markup](#section3) 29 30 - [Configuration](#section4) 31 32 - [ToC serialization format](#section5) 33 34 - [Bugs, Ideas, Feedback](#section6) 35 36 - [Keywords](#keywords) 37 38 - [Category](#category) 39 40 - [Copyright](#copyright) 41 42# <a name='synopsis'></a>SYNOPSIS 43 44package require Tcl 8\.4 45package require doctools::toc::export::wiki ?0\.1? 46package require doctools::text 47 48[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) 49 50# <a name='description'></a>DESCRIPTION 51 52This package implements the doctools table of contents export plugin for the 53generation of wiki markup\. 54 55This is an internal package of doctools, for use by the higher level management 56packages handling tables of contents, especially 57__[doctools::toc::export](toc\_export\.md)__, the export manager\. 58 59Using it from a regular interpreter is possible, however only with contortions, 60and is not recommended\. The proper way to use this functionality is through the 61package __[doctools::toc::export](toc\_export\.md)__ and the export 62manager objects it provides\. 63 64# <a name='section2'></a>API 65 66The API provided by this package satisfies the specification of the doctoc 67export plugin API version 2\. 68 69 - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* 70 71 This command takes the canonical serialization of a table of contents, as 72 specified in section [ToC serialization format](#section5), and 73 contained in *serial*, the *configuration*, a dictionary, and generates 74 wiki markup encoding the table\. The created string is then returned as the 75 result of the command\. 76 77# <a name='section3'></a>Wiki markup 78 79The basic syntax of the wiki markup generated by this plugin are described at 80[http://wiki\.tcl\.tk/14](http://wiki\.tcl\.tk/14)\. 81 82The plugin goes beyond the classic markup to generate proper headers and 83indenting\. 84 85# <a name='section4'></a>Configuration 86 87The wiki export plugin recognizes the following configuration variables and 88changes its behaviour as they specify\. 89 90 - dictionary *map* 91 92 This standard configuration variable contains a dictionary mapping from the 93 \(symbolic\) document ids in reference entries to the actual filenames and/or 94 urls to be used in the output\. 95 96 Document ids without a mapping are used unchanged\. 97 98*Note* that this plugin ignores the standard configuration variables 99__user__, __file__ and __format__, and their values\. 100 101# <a name='section5'></a>ToC serialization format 102 103Here we specify the format used by the doctools v2 packages to serialize tables 104of contents as immutable values for transport, comparison, etc\. 105 106We distinguish between *regular* and *canonical* serializations\. While a 107table of contents may have more than one regular serialization only exactly one 108of them will be *canonical*\. 109 110 - regular serialization 111 112 1. The serialization of any table of contents is a nested Tcl dictionary\. 113 114 1. This dictionary holds a single key, __doctools::toc__, and its 115 value\. This value holds the contents of the table of contents\. 116 117 1. The contents of the table of contents are a Tcl dictionary holding the 118 title of the table of contents, a label, and its elements\. The relevant 119 keys and their values are 120 121 * __title__ 122 123 The value is a string containing the title of the table of 124 contents\. 125 126 * __label__ 127 128 The value is a string containing a label for the table of contents\. 129 130 * __items__ 131 132 The value is a Tcl list holding the elements of the table, in the 133 order they are to be shown\. 134 135 Each element is a Tcl list holding the type of the item, and its 136 description, in this order\. An alternative description would be 137 that it is a Tcl dictionary holding a single key, the item type, 138 mapped to the item description\. 139 140 The two legal item types and their descriptions are 141 142 + __reference__ 143 144 This item describes a single entry in the table of contents, 145 referencing a single document\. To this end its value is a Tcl 146 dictionary containing an id for the referenced document, a 147 label, and a longer textual description which can be associated 148 with the entry\. The relevant keys and their values are 149 150 - __id__ 151 152 The value is a string containing the id of the document 153 associated with the entry\. 154 155 - __label__ 156 157 The value is a string containing a label for this entry\. 158 This string also identifies the entry, and no two entries 159 \(references and divisions\) in the containing list are 160 allowed to have the same label\. 161 162 - __desc__ 163 164 The value is a string containing a longer description for 165 this entry\. 166 167 + __division__ 168 169 This item describes a group of entries in the table of 170 contents, inducing a hierarchy of entries\. To this end its 171 value is a Tcl dictionary containing a label for the group, an 172 optional id to a document for the whole group, and the list of 173 entries in the group\. The relevant keys and their values are 174 175 - __id__ 176 177 The value is a string containing the id of the document 178 associated with the whole group\. This key is optional\. 179 180 - __label__ 181 182 The value is a string containing a label for the group\. 183 This string also identifies the entry, and no two entries 184 \(references and divisions\) in the containing list are 185 allowed to have the same label\. 186 187 - __items__ 188 189 The value is a Tcl list holding the elements of the group, 190 in the order they are to be shown\. This list has the same 191 structure as the value for the keyword __items__ used 192 to describe the whole table of contents, see above\. This 193 closes the recusrive definition of the structure, with 194 divisions holding the same type of elements as the whole 195 table of contents, including other divisions\. 196 197 - canonical serialization 198 199 The canonical serialization of a table of contents has the format as 200 specified in the previous item, and then additionally satisfies the 201 constraints below, which make it unique among all the possible 202 serializations of this table of contents\. 203 204 1. The keys found in all the nested Tcl dictionaries are sorted in 205 ascending dictionary order, as generated by Tcl's builtin command 206 __lsort \-increasing \-dict__\. 207 208# <a name='section6'></a>Bugs, Ideas, Feedback 209 210This document, and the package it describes, will undoubtedly contain bugs and 211other problems\. Please report such in the category *doctools* of the [Tcllib 212Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas 213for enhancements you may have for either package and/or documentation\. 214 215When proposing code changes, please provide *unified diffs*, i\.e the output of 216__diff \-u__\. 217 218Note further that *attachments* are strongly preferred over inlined patches\. 219Attachments can be made by going to the __Edit__ form of the ticket 220immediately after its creation, and then using the left\-most button in the 221secondary navigation bar\. 222 223# <a name='keywords'></a>KEYWORDS 224 225[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), 226[export](\.\./\.\./\.\./\.\./index\.md\#export), 227[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of 228contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), 229[toc](\.\./\.\./\.\./\.\./index\.md\#toc), [wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) 230 231# <a name='category'></a>CATEGORY 232 233Text formatter plugin 234 235# <a name='copyright'></a>COPYRIGHT 236 237Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> 238