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

NAME

8       doctools::toc::export::text - plain text export plugin
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::toc::export::text  ?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 plain text 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  plain  text markup encoding the table.  The created string
43              is then returned as the result of the command.
44

CONFIGURATION

46       The text export plugin recognizes the following configuration variables
47       and changes its behaviour as they specify.
48
49       dictionary map
50              This  standard configuration variable contains a dictionary map‐
51              ping from the (symbolic) document ids in  reference  entries  to
52              the actual filenames and/or urls to be used in the output.
53
54              Document ids without a mapping are used unchanged.
55
56       Note  that  this  plugin  ignores  the standard configuration variables
57       user, file, and format, and their values.
58

TOC SERIALIZATION FORMAT

60       Here we specify the format used by the doctools v2 packages to  serial‐
61       ize  tables  of contents as immutable values for transport, comparison,
62       etc.
63
64       We distinguish between regular and canonical serializations.   While  a
65       table of contents may have more than one regular serialization only ex‐
66       actly one of them will be canonical.
67
68       regular serialization
69
70              [1]    The serialization of any table of contents  is  a  nested
71                     Tcl dictionary.
72
73              [2]    This  dictionary  holds  a single key, doctools::toc, and
74                     its value. This value holds the contents of the table  of
75                     contents.
76
77              [3]    The  contents  of the table of contents are a Tcl dictio‐
78                     nary holding the title of the table of contents, a label,
79                     and its elements. The relevant keys and their values are
80
81                     title  The  value is a string containing the title of the
82                            table of contents.
83
84                     label  The value is a string containing a label  for  the
85                            table of contents.
86
87                     items  The  value  is  a Tcl list holding the elements of
88                            the table, in the order they are to be shown.
89
90                            Each element is a Tcl list holding the type of the
91                            item,  and  its description, in this order. An al‐
92                            ternative description would be that it  is  a  Tcl
93                            dictionary  holding  a  single key, the item type,
94                            mapped to the item description.
95
96                            The two legal item types  and  their  descriptions
97                            are
98
99                            reference
100                                   This  item  describes a single entry in the
101                                   table of  contents,  referencing  a  single
102                                   document.   To  this end its value is a Tcl
103                                   dictionary containing an id for the  refer‐
104                                   enced  document, a label, and a longer tex‐
105                                   tual description which  can  be  associated
106                                   with  the  entry.   The  relevant  keys and
107                                   their values are
108
109                                   id     The value is a string containing the
110                                          id  of  the document associated with
111                                          the entry.
112
113                                   label  The value is a string  containing  a
114                                          label  for  this  entry. This string
115                                          also identifies the  entry,  and  no
116                                          two  entries  (references  and divi‐
117                                          sions) in the  containing  list  are
118                                          allowed to have the same label.
119
120                                   desc   The  value  is a string containing a
121                                          longer description for this entry.
122
123                            division
124                                   This item describes a group of  entries  in
125                                   the table of contents, inducing a hierarchy
126                                   of entries.  To this end its value is a Tcl
127                                   dictionary   containing  a  label  for  the
128                                   group, an optional id to a document for the
129                                   whole group, and the list of entries in the
130                                   group.  The relevant keys and their  values
131                                   are
132
133                                   id     The value is a string containing the
134                                          id of the document  associated  with
135                                          the  whole  group.  This  key is op‐
136                                          tional.
137
138                                   label  The value is a string  containing  a
139                                          label  for  the  group.  This string
140                                          also identifies the  entry,  and  no
141                                          two  entries  (references  and divi‐
142                                          sions) in the  containing  list  are
143                                          allowed to have the same label.
144
145                                   items  The  value is a Tcl list holding the
146                                          elements of the group, in the  order
147                                          they are to be shown.  This list has
148                                          the same structure as the value  for
149                                          the  keyword  items used to describe
150                                          the whole  table  of  contents,  see
151                                          above.  This  closes  the  recusrive
152                                          definition of  the  structure,  with
153                                          divisions  holding  the same type of
154                                          elements as the whole table of  con‐
155                                          tents, including other divisions.
156
157       canonical serialization
158              The  canonical serialization of a table of contents has the for‐
159              mat as specified in the previous  item,  and  then  additionally
160              satisfies  the constraints below, which make it unique among all
161              the possible serializations of this table of contents.
162
163              [1]    The keys found in all the  nested  Tcl  dictionaries  are
164                     sorted  in  ascending  dictionary  order, as generated by
165                     Tcl's builtin command lsort -increasing -dict.
166

BUGS, IDEAS, FEEDBACK

168       This document, and the package it describes, will  undoubtedly  contain
169       bugs  and  other problems.  Please report such in the category doctools
170       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
171       also  report any ideas for enhancements you may have for either package
172       and/or documentation.
173
174       When proposing code changes, please provide unified diffs, i.e the out‐
175       put of diff -u.
176
177       Note  further  that  attachments  are  strongly  preferred over inlined
178       patches. Attachments can be made by going  to  the  Edit  form  of  the
179       ticket  immediately  after  its  creation, and then using the left-most
180       button in the secondary navigation bar.
181

KEYWORDS

183       doctools, export, plain text, serialization, table of contents, toc
184

CATEGORY

186       Text formatter plugin
187
189       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
190
191
192
193
194tcllib                                0.1       doctools::toc::export::text(n)
Impressum