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

NAME

8       doctools::toc::export::html - HTML export plugin
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::toc::export::html  ?0.1?
14
15       package require doctools::text
16
17       package require doctools::html
18
19       package require doctools::html::cssdefaults
20
21       export serial configuration
22
23______________________________________________________________________________
24

DESCRIPTION

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

API

39       The  API  provided  by  this package satisfies the specification of the
40       doctoc export plugin API version 2.
41
42       export serial configuration
43              This command takes the canonical serialization  of  a  table  of
44              contents,  as specified in section ToC serialization format, and
45              contained in serial, the configuration, a dictionary, and gener‐
46              ates HTML markup encoding the table.  The created string is then
47              returned as the result of the command.
48

CONFIGURATION

50       The html export plugin recognizes the following configuration variables
51       and changes its behaviour as they specify.
52
53       string user
54              This  standard  configuration  variable contains the name of the
55              user running the process which invoked the export  plugin.   The
56              plugin  puts this information into the provenance comment at the
57              beginning of the generated document.
58
59       string file
60              This standard configuration variable contains the  name  of  the
61              file  the  table of contents came from. This variable may not be
62              set or contain the empty string.  The plugin puts this  informa‐
63              tion,  if  defined,  i.e. set and not the empty string, into the
64              provenance comment at the beginning of the generated document.
65
66       dictionary map
67              This standard configuration variable contains a dictionary  map‐
68              ping  from  the  (symbolic) document ids in reference entries to
69              the actual filenames and/or urls to be used in the output.
70
71              Document ids without a mapping are used unchanged.
72
73       boolean newlines
74              If this flag is set the plugin will  break  the  generated  html
75              code across lines, with each markup command on a separate line.
76
77              If  this  flag is not set (the default), the whole document will
78              be written on a single line, with minimum  spacing  between  all
79              elements.
80
81       boolean indented
82              If  this  flag is set the plugin will indent the markup commands
83              according to the structure of indices. To make  this  work  this
84              also implies that newlines is set.
85
86              If  this  flag is not set (the default), the output is formatted
87              as per the value of newlines, and no indenting is done.
88
89       string meta
90              This variable is meant to hold  a  fragment  of  HTML  (default:
91              empty).  The fragment it contains will be inserted into the gen‐
92              erated output in the <head> section of the document, just  after
93              the <title> tag.
94
95       string header
96              This  variable  is  meant  to  hold a fragment of HTML (default:
97              empty).  The fragment it contains will be inserted into the gen‐
98              erated  output  just after the <h1> title tag in the body of the
99              document, in the class.header <div>'ision.
100
101       string footer
102              This variable is meant to hold  a  fragment  of  HTML  (default:
103              empty).  The fragment it contains will be inserted into the gen‐
104              erated output just before the </body> tag, in  the  class.footer
105              <div>'ision.
106
107       dictionary rid
108              The  value  of this variable (default: empty) maps references to
109              the identifiers to use as their anchor names. Each reference FOO
110              not  found in the dictionary uses REF-FOO as anchor, i.e. itself
111              prefixed with the string REF-.
112
113       string sepline
114              The value of this variable is the string to use for the  separa‐
115              tor comments inserted into the output when the outpout is broken
116              across lines and/or indented. The default string consists of  60
117              dashes.
118
119       string class.main
120              This variable contains the class name for the main <div>'ivision
121              of the generated document. The default is doctools.
122
123       string class.header
124              This variable contains the class name for the header <div>'ision
125              of  the generated document. The default is toc-header.  This di‐
126              vision contains the document title, the user  specified  header,
127              if any, and a visible separator line.
128
129       string class.title
130              This variable contains the class name for the <h1> tag enclosing
131              the document title. The default is toc-title.
132
133       string class.navsep
134              This variable contains the class name for the <hr> separators in
135              the  header  and  footer sections of the generated document. The
136              default is toc-navsep.
137
138       string class.contents
139              This variable contains the class name for the XXXXX holding  the
140              keywords and their references in the generated document. The de‐
141              fault is toc-contents.
142
143       string class.ref
144              This variable contains the class name  for  the  table  elements
145              which are references to other documents. The default is toc-ref.
146
147       string class.div
148              This  variable  contains  the  class name for the table elements
149              which are divisions. The default is toc-div.
150
151       string class.footer
152              This variable contains the class name for the footer <div>'ision
153              of the generated document. The default is toc-footer. This divi‐
154              sion contains a browser-visible  separator  line  and  the  user
155              specified footer, if any.
156
157       Note  that this plugin ignores the standard configuration variable for‐
158       mat, and its value.
159

TOC SERIALIZATION FORMAT

161       Here we specify the format used by the doctools v2 packages to  serial‐
162       ize  tables  of contents as immutable values for transport, comparison,
163       etc.
164
165       We distinguish between regular and canonical serializations.   While  a
166       table of contents may have more than one regular serialization only ex‐
167       actly one of them will be canonical.
168
169       regular serialization
170
171              [1]    The serialization of any table of contents  is  a  nested
172                     Tcl dictionary.
173
174              [2]    This  dictionary  holds  a single key, doctools::toc, and
175                     its value. This value holds the contents of the table  of
176                     contents.
177
178              [3]    The  contents  of the table of contents are a Tcl dictio‐
179                     nary holding the title of the table of contents, a label,
180                     and its elements. The relevant keys and their values are
181
182                     title  The  value is a string containing the title of the
183                            table of contents.
184
185                     label  The value is a string containing a label  for  the
186                            table of contents.
187
188                     items  The  value  is  a Tcl list holding the elements of
189                            the table, in the order they are to be shown.
190
191                            Each element is a Tcl list holding the type of the
192                            item,  and  its description, in this order. An al‐
193                            ternative description would be that it  is  a  Tcl
194                            dictionary  holding  a  single key, the item type,
195                            mapped to the item description.
196
197                            The two legal item types  and  their  descriptions
198                            are
199
200                            reference
201                                   This  item  describes a single entry in the
202                                   table of  contents,  referencing  a  single
203                                   document.   To  this end its value is a Tcl
204                                   dictionary containing an id for the  refer‐
205                                   enced  document, a label, and a longer tex‐
206                                   tual description which  can  be  associated
207                                   with  the  entry.   The  relevant  keys and
208                                   their values are
209
210                                   id     The value is a string containing the
211                                          id  of  the document associated with
212                                          the entry.
213
214                                   label  The value is a string  containing  a
215                                          label  for  this  entry. This string
216                                          also identifies the  entry,  and  no
217                                          two  entries  (references  and divi‐
218                                          sions) in the  containing  list  are
219                                          allowed to have the same label.
220
221                                   desc   The  value  is a string containing a
222                                          longer description for this entry.
223
224                            division
225                                   This item describes a group of  entries  in
226                                   the table of contents, inducing a hierarchy
227                                   of entries.  To this end its value is a Tcl
228                                   dictionary   containing  a  label  for  the
229                                   group, an optional id to a document for the
230                                   whole group, and the list of entries in the
231                                   group.  The relevant keys and their  values
232                                   are
233
234                                   id     The value is a string containing the
235                                          id of the document  associated  with
236                                          the  whole  group.  This  key is op‐
237                                          tional.
238
239                                   label  The value is a string  containing  a
240                                          label  for  the  group.  This string
241                                          also identifies the  entry,  and  no
242                                          two  entries  (references  and divi‐
243                                          sions) in the  containing  list  are
244                                          allowed to have the same label.
245
246                                   items  The  value is a Tcl list holding the
247                                          elements of the group, in the  order
248                                          they are to be shown.  This list has
249                                          the same structure as the value  for
250                                          the  keyword  items used to describe
251                                          the whole  table  of  contents,  see
252                                          above.  This  closes  the  recusrive
253                                          definition of  the  structure,  with
254                                          divisions  holding  the same type of
255                                          elements as the whole table of  con‐
256                                          tents, including other divisions.
257
258       canonical serialization
259              The  canonical serialization of a table of contents has the for‐
260              mat as specified in the previous  item,  and  then  additionally
261              satisfies  the constraints below, which make it unique among all
262              the possible serializations of this table of contents.
263
264              [1]    The keys found in all the  nested  Tcl  dictionaries  are
265                     sorted  in  ascending  dictionary  order, as generated by
266                     Tcl's builtin command lsort -increasing -dict.
267

BUGS, IDEAS, FEEDBACK

269       This document, and the package it describes, will  undoubtedly  contain
270       bugs  and  other problems.  Please report such in the category doctools
271       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
272       also  report any ideas for enhancements you may have for either package
273       and/or documentation.
274
275       When proposing code changes, please provide unified diffs, i.e the out‐
276       put of diff -u.
277
278       Note  further  that  attachments  are  strongly  preferred over inlined
279       patches. Attachments can be made by going  to  the  Edit  form  of  the
280       ticket  immediately  after  its  creation, and then using the left-most
281       button in the secondary navigation bar.
282

KEYWORDS

284       HTML, doctools, export, serialization, table of contents, toc
285

CATEGORY

287       Text formatter plugin
288
290       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
291
292
293
294
295tcllib                                0.1       doctools::toc::export::html(n)
Impressum