1doctools::toc::export::doctoc(nD)ocumentation toodlosctools::toc::export::doctoc(n)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::toc::export::doctoc  ?0.2.1?
14
15       export serial configuration
16
17______________________________________________________________________________
18

DESCRIPTION

20       This  package  implements  the doctools table of contents export plugin
21       for the generation of doctoc markup.
22
23       This is an internal package of doctools, for use by  the  higher  level
24       management  packages  handling  tables  of  contents,  especially  doc‐
25       tools::toc::export, the export manager.
26
27       Using it from a regular interpreter is possible, however only with con‐
28       tortions, and is not recommended.  The proper way to use this function‐
29       ality is through the package doctools::toc::export and the export  man‐
30       ager objects it provides.
31

API

33       The  API  provided  by  this package satisfies the specification of the
34       doctoc export plugin API version 2.
35
36       export serial configuration
37              This command takes the canonical serialization  of  a  table  of
38              contents,  as specified in section ToC serialization format, and
39              contained in serial, the configuration, a dictionary, and gener‐
40              ates  doctoc  markup  encoding the table.  The created string is
41              then returned as the result of the command.
42

[DOCTOC] NOTATION OF TABLES OF CONTENTS

44       The doctoc format for tables of contents, also called the doctoc markup
45       language, is too large to be covered in single section.  The interested
46       reader should start with the document
47
48       [1]    doctoc language introduction
49
50       and then proceed from there to the formal specifications, i.e. the doc‐
51       uments
52
53       [1]    doctoc language syntax and
54
55       [2]    doctoc language command reference.
56
57       to get a thorough understanding of the language.
58

CONFIGURATION

60       The  doctoc  export plugin recognizes the following configuration vari‐
61       ables and changes its behaviour as they specify.
62
63       string user
64              This standard configuration variable contains the  name  of  the
65              user  running  the process which invoked the export plugin.  The
66              plugin puts this information into the provenance comment at  the
67              beginning of the generated document.
68
69       string file
70              This  standard  configuration  variable contains the name of the
71              file the table of contents came from. This variable may  not  be
72              set  or contain the empty string.  The plugin puts this informa‐
73              tion, if defined, i.e. set and not the empty  string,  into  the
74              provenance comment at the beginning of the generated document.
75
76       boolean newlines
77              If  this  flag is set the plugin will break the generated doctoc
78              code across lines, with each markup command on a separate line.
79
80              If this flag is not set (the default), the whole  document  will
81              be  written  on  a single line, with minimum spacing between all
82              elements.
83
84       boolean indented
85              If this flag is set the plugin will indent the  markup  commands
86              according  to  the structure of tables of contents. To make this
87              work this also implies that newlines is set. This effect is  in‐
88              dependent of the value for aligned however.
89
90              If  this  flag is not set (the default), the output is formatted
91              as per the value of newlines, and no indenting is done.
92
93       boolean aligned
94              If this flag is set the generator ensures that the arguments for
95              the  item  commands  in  a division are aligned vertically for a
96              nice table effect. To make this work this also implies that new‐
97              lines  is  set.  This effect is independent of the value for in‐
98              dented however.
99
100              If this flag is not set (the default), the output  is  formatted
101              as  per the values of newlines and indented, and no alignment is
102              done.
103
104       Note that this plugin ignores the standard configuration variables for‐
105       mat, and map, and their values.
106

TOC SERIALIZATION FORMAT

108       Here  we specify the format used by the doctools v2 packages to serial‐
109       ize tables of contents as immutable values for  transport,  comparison,
110       etc.
111
112       We  distinguish  between regular and canonical serializations.  While a
113       table of contents may have more than one regular serialization only ex‐
114       actly one of them will be canonical.
115
116       regular serialization
117
118              [1]    The  serialization  of  any table of contents is a nested
119                     Tcl dictionary.
120
121              [2]    This dictionary holds a single  key,  doctools::toc,  and
122                     its  value. This value holds the contents of the table of
123                     contents.
124
125              [3]    The contents of the table of contents are a  Tcl  dictio‐
126                     nary holding the title of the table of contents, a label,
127                     and its elements. The relevant keys and their values are
128
129                     title  The value is a string containing the title of  the
130                            table of contents.
131
132                     label  The  value  is a string containing a label for the
133                            table of contents.
134
135                     items  The value is a Tcl list holding  the  elements  of
136                            the table, in the order they are to be shown.
137
138                            Each element is a Tcl list holding the type of the
139                            item, and its description, in this order.  An  al‐
140                            ternative  description  would  be that it is a Tcl
141                            dictionary holding a single key,  the  item  type,
142                            mapped to the item description.
143
144                            The  two  legal  item types and their descriptions
145                            are
146
147                            reference
148                                   This item describes a single entry  in  the
149                                   table  of  contents,  referencing  a single
150                                   document.  To this end its value is  a  Tcl
151                                   dictionary  containing an id for the refer‐
152                                   enced document, a label, and a longer  tex‐
153                                   tual  description  which  can be associated
154                                   with the  entry.   The  relevant  keys  and
155                                   their values are
156
157                                   id     The value is a string containing the
158                                          id of the document  associated  with
159                                          the entry.
160
161                                   label  The  value  is a string containing a
162                                          label for this  entry.  This  string
163                                          also  identifies  the  entry, and no
164                                          two entries  (references  and  divi‐
165                                          sions)  in  the  containing list are
166                                          allowed to have the same label.
167
168                                   desc   The value is a string  containing  a
169                                          longer description for this entry.
170
171                            division
172                                   This  item  describes a group of entries in
173                                   the table of contents, inducing a hierarchy
174                                   of entries.  To this end its value is a Tcl
175                                   dictionary  containing  a  label  for   the
176                                   group, an optional id to a document for the
177                                   whole group, and the list of entries in the
178                                   group.   The relevant keys and their values
179                                   are
180
181                                   id     The value is a string containing the
182                                          id  of  the document associated with
183                                          the whole group.  This  key  is  op‐
184                                          tional.
185
186                                   label  The  value  is a string containing a
187                                          label for  the  group.  This  string
188                                          also  identifies  the  entry, and no
189                                          two entries  (references  and  divi‐
190                                          sions)  in  the  containing list are
191                                          allowed to have the same label.
192
193                                   items  The value is a Tcl list holding  the
194                                          elements  of the group, in the order
195                                          they are to be shown.  This list has
196                                          the  same structure as the value for
197                                          the keyword items used  to  describe
198                                          the  whole  table  of  contents, see
199                                          above.  This  closes  the  recusrive
200                                          definition  of  the  structure, with
201                                          divisions holding the same  type  of
202                                          elements  as the whole table of con‐
203                                          tents, including other divisions.
204
205       canonical serialization
206              The canonical serialization of a table of contents has the  for‐
207              mat  as  specified  in  the previous item, and then additionally
208              satisfies the constraints below, which make it unique among  all
209              the possible serializations of this table of contents.
210
211              [1]    The  keys  found  in  all the nested Tcl dictionaries are
212                     sorted in ascending dictionary  order,  as  generated  by
213                     Tcl's builtin command lsort -increasing -dict.
214

BUGS, IDEAS, FEEDBACK

216       This  document,  and the package it describes, will undoubtedly contain
217       bugs and other problems.  Please report such in the  category  doctools
218       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
219       also report any ideas for enhancements you may have for either  package
220       and/or documentation.
221
222       When proposing code changes, please provide unified diffs, i.e the out‐
223       put of diff -u.
224
225       Note further that  attachments  are  strongly  preferred  over  inlined
226       patches.  Attachments  can  be  made  by  going to the Edit form of the
227       ticket immediately after its creation, and  then  using  the  left-most
228       button in the secondary navigation bar.
229

KEYWORDS

231       doctoc, doctools, export, serialization, table of contents, toc
232

CATEGORY

234       Text formatter plugin
235
237       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
238
239
240
241
242tcllib                               0.2.1    doctools::toc::export::doctoc(n)
Impressum