1 2[//000000001]: # (doctools::toc::export::doctoc \- 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::doctoc\(n\) 0\.2\.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::doctoc \- doctoc 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 - [\[doctoc\] notation of tables of contents](#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::doctoc ?0\.2\.1? 46 47[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) 48 49# <a name='description'></a>DESCRIPTION 50 51This package implements the doctools table of contents export plugin for the 52generation of doctoc markup\. 53 54This is an internal package of doctools, for use by the higher level management 55packages handling tables of contents, especially 56__[doctools::toc::export](toc\_export\.md)__, the export manager\. 57 58Using it from a regular interpreter is possible, however only with contortions, 59and is not recommended\. The proper way to use this functionality is through the 60package __[doctools::toc::export](toc\_export\.md)__ and the export 61manager objects it provides\. 62 63# <a name='section2'></a>API 64 65The API provided by this package satisfies the specification of the doctoc 66export plugin API version 2\. 67 68 - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* 69 70 This command takes the canonical serialization of a table of contents, as 71 specified in section [ToC serialization format](#section5), and 72 contained in *serial*, the *configuration*, a dictionary, and generates 73 doctoc markup encoding the table\. The created string is then returned as the 74 result of the command\. 75 76# <a name='section3'></a>\[doctoc\] notation of tables of contents 77 78The doctoc format for tables of contents, also called the *doctoc markup 79language*, is too large to be covered in single section\. The interested reader 80should start with the document 81 82 1. *[doctoc language introduction](\.\./doctools/doctoc\_lang\_intro\.md)* 83 84and then proceed from there to the formal specifications, i\.e\. the documents 85 86 1. *[doctoc language syntax](\.\./doctools/doctoc\_lang\_syntax\.md)* and 87 88 1. *[doctoc language command 89 reference](\.\./doctools/doctoc\_lang\_cmdref\.md)*\. 90 91to get a thorough understanding of the language\. 92 93# <a name='section4'></a>Configuration 94 95The doctoc export plugin recognizes the following configuration variables and 96changes its behaviour as they specify\. 97 98 - string *user* 99 100 This standard configuration variable contains the name of the user running 101 the process which invoked the export plugin\. The plugin puts this 102 information into the provenance comment at the beginning of the generated 103 document\. 104 105 - string *file* 106 107 This standard configuration variable contains the name of the file the table 108 of contents came from\. This variable may not be set or contain the empty 109 string\. The plugin puts this information, if defined, i\.e\. set and not the 110 empty string, into the provenance comment at the beginning of the generated 111 document\. 112 113 - boolean *newlines* 114 115 If this flag is set the plugin will break the generated doctoc code across 116 lines, with each markup command on a separate line\. 117 118 If this flag is not set \(the default\), the whole document will be written on 119 a single line, with minimum spacing between all elements\. 120 121 - boolean *indented* 122 123 If this flag is set the plugin will indent the markup commands according to 124 the structure of tables of contents\. To make this work this also implies 125 that __newlines__ is set\. This effect is independent of the value for 126 __aligned__ however\. 127 128 If this flag is not set \(the default\), the output is formatted as per the 129 value of __newlines__, and no indenting is done\. 130 131 - boolean *aligned* 132 133 If this flag is set the generator ensures that the arguments for the 134 __item__ commands in a division are aligned vertically for a nice table 135 effect\. To make this work this also implies that __newlines__ is set\. 136 This effect is independent of the value for __indented__ however\. 137 138 If this flag is not set \(the default\), the output is formatted as per the 139 values of __newlines__ and __indented__, and no alignment is done\. 140 141*Note* that this plugin ignores the standard configuration variables 142__format__, and __map__, and their values\. 143 144# <a name='section5'></a>ToC serialization format 145 146Here we specify the format used by the doctools v2 packages to serialize tables 147of contents as immutable values for transport, comparison, etc\. 148 149We distinguish between *regular* and *canonical* serializations\. While a 150table of contents may have more than one regular serialization only exactly one 151of them will be *canonical*\. 152 153 - regular serialization 154 155 1. The serialization of any table of contents is a nested Tcl dictionary\. 156 157 1. This dictionary holds a single key, __doctools::toc__, and its 158 value\. This value holds the contents of the table of contents\. 159 160 1. The contents of the table of contents are a Tcl dictionary holding the 161 title of the table of contents, a label, and its elements\. The relevant 162 keys and their values are 163 164 * __title__ 165 166 The value is a string containing the title of the table of 167 contents\. 168 169 * __label__ 170 171 The value is a string containing a label for the table of contents\. 172 173 * __items__ 174 175 The value is a Tcl list holding the elements of the table, in the 176 order they are to be shown\. 177 178 Each element is a Tcl list holding the type of the item, and its 179 description, in this order\. An alternative description would be 180 that it is a Tcl dictionary holding a single key, the item type, 181 mapped to the item description\. 182 183 The two legal item types and their descriptions are 184 185 + __reference__ 186 187 This item describes a single entry in the table of contents, 188 referencing a single document\. To this end its value is a Tcl 189 dictionary containing an id for the referenced document, a 190 label, and a longer textual description which can be associated 191 with the entry\. The relevant keys and their values are 192 193 - __id__ 194 195 The value is a string containing the id of the document 196 associated with the entry\. 197 198 - __label__ 199 200 The value is a string containing a label for this entry\. 201 This string also identifies the entry, and no two entries 202 \(references and divisions\) in the containing list are 203 allowed to have the same label\. 204 205 - __desc__ 206 207 The value is a string containing a longer description for 208 this entry\. 209 210 + __division__ 211 212 This item describes a group of entries in the table of 213 contents, inducing a hierarchy of entries\. To this end its 214 value is a Tcl dictionary containing a label for the group, an 215 optional id to a document for the whole group, and the list of 216 entries in the group\. The relevant keys and their values are 217 218 - __id__ 219 220 The value is a string containing the id of the document 221 associated with the whole group\. This key is optional\. 222 223 - __label__ 224 225 The value is a string containing a label for the group\. 226 This string also identifies the entry, and no two entries 227 \(references and divisions\) in the containing list are 228 allowed to have the same label\. 229 230 - __items__ 231 232 The value is a Tcl list holding the elements of the group, 233 in the order they are to be shown\. This list has the same 234 structure as the value for the keyword __items__ used 235 to describe the whole table of contents, see above\. This 236 closes the recusrive definition of the structure, with 237 divisions holding the same type of elements as the whole 238 table of contents, including other divisions\. 239 240 - canonical serialization 241 242 The canonical serialization of a table of contents has the format as 243 specified in the previous item, and then additionally satisfies the 244 constraints below, which make it unique among all the possible 245 serializations of this table of contents\. 246 247 1. The keys found in all the nested Tcl dictionaries are sorted in 248 ascending dictionary order, as generated by Tcl's builtin command 249 __lsort \-increasing \-dict__\. 250 251# <a name='section6'></a>Bugs, Ideas, Feedback 252 253This document, and the package it describes, will undoubtedly contain bugs and 254other problems\. Please report such in the category *doctools* of the [Tcllib 255Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas 256for enhancements you may have for either package and/or documentation\. 257 258When proposing code changes, please provide *unified diffs*, i\.e the output of 259__diff \-u__\. 260 261Note further that *attachments* are strongly preferred over inlined patches\. 262Attachments can be made by going to the __Edit__ form of the ticket 263immediately after its creation, and then using the left\-most button in the 264secondary navigation bar\. 265 266# <a name='keywords'></a>KEYWORDS 267 268[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), 269[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), 270[export](\.\./\.\./\.\./\.\./index\.md\#export), 271[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of 272contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), 273[toc](\.\./\.\./\.\./\.\./index\.md\#toc) 274 275# <a name='category'></a>CATEGORY 276 277Text formatter plugin 278 279# <a name='copyright'></a>COPYRIGHT 280 281Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> 282