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

NAME

8       doctools::toc::export - Exporting tables of contents
9

SYNOPSIS

11       package require doctools::toc::export  ?0.2?
12
13       package require Tcl  8.4
14
15       package require doctools::config
16
17       package require doctools::toc::structure
18
19       package require snit
20
21       package require pluginmgr
22
23       ::doctools::toc::export objectName
24
25       objectName method ?arg arg ...?
26
27       objectName destroy
28
29       objectName export serial serial ?format?
30
31       objectName export object object ?format?
32
33       objectName config names
34
35       objectName config get
36
37       objectName config set name ?value?
38
39       objectName config unset pattern...
40
41       export serial configuration
42
43______________________________________________________________________________
44

DESCRIPTION

46       This  package  provides a class to manage the plugins for the export of
47       tables of contents to other formats,  i.e.  their  conversion  to,  for
48       example doctoc, HTML, etc.
49
50       This  is  one  of  the three public pillars the management of tables of
51       contents resides on. The other two pillars are
52
53       [1]    Importing tables of contents, and
54
55       [2]    Holding tables of contents
56
57       For information about the Concepts of tables  of  contents,  and  their
58       parts,  see  the  same-named  section.   For information about the data
59       structure which is the major input to the manager objects  provided  by
60       this package see the section ToC serialization format.
61
62       The  plugin  system of our class is based on the package pluginmgr, and
63       configured to look for plugins using
64
65       [1]    the environment variable DOCTOOLS_TOC_EXPORT_PLUGINS,
66
67       [2]    the environment variable DOCTOOLS_TOC_PLUGINS,
68
69       [3]    the environment variable DOCTOOLS_PLUGINS,
70
71       [4]    the path "~/.doctools/toc/export/plugin"
72
73       [5]    the path "~/.doctools/toc/plugin"
74
75       [6]    the path "~/.doctools/plugin"
76
77       [7]    the path "~/.doctools/toc/export/plugins"
78
79       [8]    the path "~/.doctools/toc/plugins"
80
81       [9]    the path "~/.doctools/plugins"
82
83       [10]   the     registry     entry      "HKEY_CURRENT_USER\SOFTWARE\DOC‐
84              TOOLS\TOC\EXPORT\PLUGINS"
85
86       [11]   the      registry     entry     "HKEY_CURRENT_USER\SOFTWARE\DOC‐
87              TOOLS\TOC\PLUGINS"
88
89       [12]   the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
90
91       The last three are used only when the package is run on a machine using
92       Windows(tm) operating system.
93
94       The  whole  system  is  delivered  with  six predefined export plugins,
95       namely
96
97       doctoc See doctoc export plugin for details.
98
99       html   See html export plugin for details.
100
101       json   See json export plugin for details.
102
103       nroff  See nroff export plugin for details.
104
105       text   See text export plugin for details.
106
107       wiki   See wiki export plugin for details.
108
109       Readers wishing to write their own export plugin for some format,  i.e.
110       plugin  writers  reading  and  understanding the section containing the
111       Export plugin API v2 reference is an absolute necessity, as  it  speci‐
112       fies the interaction between this package and its plugins in detail.
113

CONCEPTS

115       [1]    A  table of contents consists of a (possibly empty) list of ele‐
116              ments.
117
118       [2]    Each element in the list is identified by its label.
119
120       [3]    Each element is either a reference, or a division.
121
122       [4]    Each reference has an associated document, identified by a  sym‐
123              bolic id, and a textual description.
124
125       [5]    Each  division  may have an associated document, identified by a
126              symbolic id.
127
128       [6]    Each division consists consists of a (possibly  empty)  list  of
129              elements,  with each element following the rules as specified in
130              item 2 and above.
131
132       A few notes
133
134       [1]    The above rules span up a tree of elements, with  references  as
135              the  leaf nodes, and divisions as the inner nodes, and each ele‐
136              ment representing an entry in the whole table of contents.
137
138       [2]    The identifying labels of any element E are unique within  their
139              division  (or  toc),  and the full label of any element E is the
140              list of labels for all nodes on the unique path from the root of
141              the tree to E, including E.
142

API

144   PACKAGE COMMANDS
145       ::doctools::toc::export objectName
146              This command creates a new export manager object with an associ‐
147              ated Tcl command whose name is objectName. This  object  command
148              is  explained  in full detail in the sections Object command and
149              Object methods. The object command will  be  created  under  the
150              current  namespace if the objectName is not fully qualified, and
151              in the specified namespace otherwise.
152
153   OBJECT COMMAND
154       All objects created by the  ::doctools::toc::export  command  have  the
155       following general form:
156
157       objectName method ?arg arg ...?
158              The  method method and its arg'uments determine the exact behav‐
159              ior of the command.  See section Object methods for the detailed
160              specifications.
161
162   OBJECT METHODS
163       objectName destroy
164              This method destroys the object it is invoked for.
165
166       objectName export serial serial ?format?
167              This method takes the canonical serialization of a table of con‐
168              tents stored in serial and converts it to the specified  format,
169              using the export plugin for the format. An error is thrown if no
170              plugin could be found for the format.  The string  generated  by
171              the conversion process is returned as the result of this method.
172
173              If no format is specified the method defaults to doctoc.
174
175              The  specification  of  what a canonical serialization is can be
176              found in the section ToC serialization format.
177
178              The plugin has to conform to the interface specified in  section
179              Export plugin API v2 reference.
180
181       objectName export object object ?format?
182              This  method  is  a  convenient wrapper around the export serial
183              method described by the previous item.  It expects  that  object
184              is an object command supporting a serialize method returning the
185              canonical serialization of a table of contents. It invokes  that
186              method,  feeds  the  result  into  export serial and returns the
187              resulting string as its own result.
188
189       objectName config names
190              This method returns a list containing the names of all  configu‐
191              ration variables currently known to the object.
192
193       objectName config get
194              This method returns a dictionary containing the names and values
195              of all configuration variables currently known to the object.
196
197       objectName config set name ?value?
198              This method sets the configuration variable name to  the  speci‐
199              fied value and returns the new value of the variable.
200
201              If  no  value  is specified it simply returns the current value,
202              without changing it.
203
204              Note that while the user can set  the  predefined  configuration
205              variables  user  and  format doing so will have no effect, these
206              values will be internally overridden  when  invoking  an  import
207              plugin.
208
209       objectName config unset pattern...
210              This  method  unsets  all  configuration  variables matching the
211              specified glob patterns. If no  pattern  is  specified  it  will
212              unset all currently defined configuration variables.
213

EXPORT PLUGIN API V2 REFERENCE

215       Plugins are what this package uses to manage the support for any output
216       format beyond the ToC serialization format. Here we specify the API the
217       objects created by this package use to interact with their plugins.
218
219       A plugin for this package has to follow the rules listed below:
220
221       [1]    A plugin is a package.
222
223       [2]    The   name   of   a   plugin   package   has   the   form   doc‐
224              tools::toc::export::FOO, where FOO is the name of the format the
225              plugin  will generate output for. This name is also the argument
226              to provide to the  various  export  methods  of  export  manager
227              objects  to  get  a  string encoding a table of contents in that
228              format.
229
230       [3]    The    plugin    can    expect    that    the    package    doc‐
231              tools::toc::export::plugin  is present, as indicator that it was
232              invoked from a genuine plugin manager.
233
234       [4]    A plugin has to provide one command, with  the  signature  shown
235              below.
236
237              export serial configuration
238                     Whenever an export manager of doctools::toc has to gener‐
239                     ate output for a table of contents it  will  invoke  this
240                     command.
241
242                     string serial
243                            This  argument  will contain the canonical serial‐
244                            ization of the table of contents for which to gen‐
245                            erate  the  output.   The  specification of what a
246                            canonical serialization is can  be  found  in  the
247                            section ToC serialization format.
248
249                     dictionary configuration
250                            This  argument will contain the current configura‐
251                            tion to apply to the generation, as  a  dictionary
252                            mapping from variable names to values.
253
254                            The  following configuration variables have a pre‐
255                            defined meaning all plugins have to obey, although
256                            they  can ignore this information at their discre‐
257                            tion. Any other other configuration variables rec‐
258                            ognized  by a plugin will be described in the man‐
259                            page for that plugin.
260
261                            user   This variable is expected  to  contain  the
262                                   name  of the user owning the process invok‐
263                                   ing the plugin.
264
265                            format This variable is expected  to  contain  the
266                                   name of the format whose plugin is invoked.
267
268                            file   This  variable,  if  defined by the user of
269                                   the table object is expected to contain the
270                                   name of the input file for which the plugin
271                                   is generating its output for.
272
273                            map    This variable, if defined by  the  user  of
274                                   the  table  object is expected to contain a
275                                   dictionary mapping from  symbolic  document
276                                   ids  used  in  the  table entries to actual
277                                   paths (or urls). A plugin has to be able to
278                                   handle  the  possibility that a document id
279                                   is without entry in this mapping.
280
281       [5]    A single usage cycle of a plugin consists of the invokations  of
282              the command export. This call has to leave the plugin in a state
283              where another usage cycle can be run without problems.
284

TOC SERIALIZATION FORMAT

286       Here we specify the format used by the doctools v2 packages to  serial‐
287       ize  tables  of contents as immutable values for transport, comparison,
288       etc.
289
290       We distinguish between regular and canonical serializations.   While  a
291       table  of  contents  may  have more than one regular serialization only
292       exactly one of them will be canonical.
293
294       regular serialization
295
296              [1]    The serialization of any table of contents  is  a  nested
297                     Tcl dictionary.
298
299              [2]    This  dictionary  holds  a single key, doctools::toc, and
300                     its value. This value holds the contents of the table  of
301                     contents.
302
303              [3]    The  contents  of the table of contents are a Tcl dictio‐
304                     nary holding the title of the table of contents, a label,
305                     and its elements. The relevant keys and their values are
306
307                     title  The  value is a string containing the title of the
308                            table of contents.
309
310                     label  The value is a string containing a label  for  the
311                            table of contents.
312
313                     items  The  value  is  a Tcl list holding the elements of
314                            the table, in the order they are to be shown.
315
316                            Each element is a Tcl list holding the type of the
317                            item,  and  its  description,  in  this  order. An
318                            alternative description would be that it is a  Tcl
319                            dictionary  holding  a  single key, the item type,
320                            mapped to the item description.
321
322                            The two legal item types  and  their  descriptions
323                            are
324
325                            reference
326                                   This  item  describes a single entry in the
327                                   table of  contents,  referencing  a  single
328                                   document.   To  this end its value is a Tcl
329                                   dictionary containing an id for the  refer‐
330                                   enced  document, a label, and a longer tex‐
331                                   tual description which  can  be  associated
332                                   with  the  entry.   The  relevant  keys and
333                                   their values are
334
335                                   id     The value is a string containing the
336                                          id  of  the document associated with
337                                          the entry.
338
339                                   label  The value is a string  containing  a
340                                          label  for  this  entry. This string
341                                          also identifies the  entry,  and  no
342                                          two  entries  (references  and divi‐
343                                          sions) in the  containing  list  are
344                                          allowed to have the same label.
345
346                                   desc   The  value  is a string containing a
347                                          longer description for this entry.
348
349                            division
350                                   This item describes a group of  entries  in
351                                   the table of contents, inducing a hierarchy
352                                   of entries.  To this end its value is a Tcl
353                                   dictionary   containing  a  label  for  the
354                                   group, an optional id to a document for the
355                                   whole group, and the list of entries in the
356                                   group.  The relevant keys and their  values
357                                   are
358
359                                   id     The value is a string containing the
360                                          id of the document  associated  with
361                                          the   whole   group.   This  key  is
362                                          optional.
363
364                                   label  The value is a string  containing  a
365                                          label  for  the  group.  This string
366                                          also identifies the  entry,  and  no
367                                          two  entries  (references  and divi‐
368                                          sions) in the  containing  list  are
369                                          allowed to have the same label.
370
371                                   items  The  value is a Tcl list holding the
372                                          elements of the group, in the  order
373                                          they are to be shown.  This list has
374                                          the same structure as the value  for
375                                          the  keyword  items used to describe
376                                          the whole  table  of  contents,  see
377                                          above.  This  closes  the  recusrive
378                                          definition of  the  structure,  with
379                                          divisions  holding  the same type of
380                                          elements as the whole table of  con‐
381                                          tents, including other divisions.
382
383       canonical serialization
384              The  canonical serialization of a table of contents has the for‐
385              mat as specified in the previous  item,  and  then  additionally
386              satisfies  the constraints below, which make it unique among all
387              the possible serializations of this table of contents.
388
389              [1]    The keys found in all the  nested  Tcl  dictionaries  are
390                     sorted  in  ascending  dictionary  order, as generated by
391                     Tcl's builtin command lsort -increasing -dict.
392

BUGS, IDEAS, FEEDBACK

394       This document, and the package it describes, will  undoubtedly  contain
395       bugs  and  other problems.  Please report such in the category doctools
396       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
397       also  report any ideas for enhancements you may have for either package
398       and/or documentation.
399
400       When proposing code changes, please provide unified diffs, i.e the out‐
401       put of diff -u.
402
403       Note  further  that  attachments  are  strongly  preferred over inlined
404       patches. Attachments can be made by going  to  the  Edit  form  of  the
405       ticket  immediately  after  its  creation, and then using the left-most
406       button in the secondary navigation bar.
407

KEYWORDS

409       HTML, conversion, doctoc, documentation,  export,  formatting,  genera‐
410       tion,  json, manpage, markup, nroff, plugin, reference, table, table of
411       contents, tcler's wiki, text, url, wiki
412

CATEGORY

414       Documentation tools
415
417       Copyright (c) 2009-2018 Andreas Kupries <andreas_kupries@users.sourceforge.net>
418
419
420
421
422tcllib                                0.2             doctools::toc::export(n)
Impressum