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

NAME

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

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::toc::import::doctoc  ?0.1?
14
15       package require doctools::toc::parse
16
17       package require doctools::toc::structure
18
19       package require doctools::msgcat
20
21       package require doctools::tcl::parse
22
23       package require fileutil
24
25       package require logger
26
27       package require snit
28
29       package require struct::list
30
31       package require struct::set
32
33       package require struct::stack
34
35       package require struct::tree
36
37       package require treeql
38
39       import string configuration
40
41______________________________________________________________________________
42

DESCRIPTION

44       This  package  implements  the doctools table of contents import plugin
45       for the parsing of doctoc markup.
46
47       This is an internal package of doctools, for use by  the  higher  level
48       management  packages  handling  tables  of  contents,  especially  doc‐
49       tools::toc::import, the import manager.
50
51       Using it from a regular interpreter is possible, however only with con‐
52       tortions, and is not recommended.  The proper way to use this function‐
53       ality is through the package doctools::toc::import and the import  man‐
54       ager objects it provides.
55

API

57       The  API  provided  by  this package satisfies the specification of the
58       doctoc import plugin API version 2.
59
60       import string configuration
61              This command takes the string and parses  it  as  doctoc  markup
62              encoding  a  table  of contents, in the context of the specified
63              configuration (a dictionary). The result of the command  is  the
64              canonical  serialization  of that table of contents, in the form
65              specified in section ToC serialization format.
66

[DOCTOC] NOTATION OF TABLES OF CONTENTS

68       The doctoc format for tables of contents, also called the doctoc markup
69       language, is too large to be covered in single section.  The interested
70       reader should start with the document
71
72       [1]    doctoc language introduction
73
74       and then proceed from there to the formal specifications, i.e. the doc‐
75       uments
76
77       [1]    doctoc language syntax and
78
79       [2]    doctoc language command reference.
80
81       to get a thorough understanding of the language.
82

TOC SERIALIZATION FORMAT

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

BUGS, IDEAS, FEEDBACK

192       This  document,  and the package it describes, will undoubtedly contain
193       bugs and other problems.  Please report such in the  category  doctools
194       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
195       also report any ideas for enhancements you may have for either  package
196       and/or documentation.
197
198       When proposing code changes, please provide unified diffs, i.e the out‐
199       put of diff -u.
200
201       Note further that  attachments  are  strongly  preferred  over  inlined
202       patches.  Attachments  can  be  made  by  going to the Edit form of the
203       ticket immediately after its creation, and  then  using  the  left-most
204       button in the secondary navigation bar.
205

KEYWORDS

207       deserialization, doctoc, doctools, import, table of contents, toc
208

CATEGORY

210       Text formatter plugin
211
213       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
214
215
216
217
218tcllib                                0.1     doctools::toc::import::doctoc(n)
Impressum