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

NAME

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

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::idx::export::html  ?0.2?
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 keyword index export plugin for
27       the generation of HTML markup.
28
29       This is an internal package of doctools, for use by  the  higher  level
30       management   packages   handling   keyword   indices,  especially  doc‐
31       tools::idx::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::idx::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       docidx export plugin API version 2.
41
42       export serial configuration
43              This command takes the  canonical  serialization  of  a  keyword
44              index,  as specified in section Keyword index serialization for‐
45              mat, and contained in serial, the configuration,  a  dictionary,
46              and  generates  HTML  markup  encoding  the  index.  The created
47              string is then 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  index came from. This variable may not be set or con‐
62              tain the empty string.  The plugin  puts  this  information,  if
63              defined,  i.e. set and not the empty string, into the provenance
64              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 files names in manpage references to the
69              actual filenames and/or urls to be used in the output.
70
71              Url references and symbolic file names  without  a  mapping  are
72              used unchanged.
73
74       boolean newlines
75              If  this  flag  is  set the plugin will break the generated html
76              code across lines, with each markup command on a separate line.
77
78              If this flag is not set (the default), the whole  document  will
79              be  written  on  a single line, with minimum spacing between all
80              elements.
81
82       boolean indented
83              If this flag is set the plugin will indent the  markup  commands
84              according  to  the  structure of indices. To make this work this
85              also implies that newlines is set.
86
87              If this flag is not set (the default), the output  is  formatted
88              as per the value of newlines, and no indenting is done.
89
90       string meta
91              This  variable  is  meant  to  hold a fragment of HTML (default:
92              empty).  The fragment it contains will be inserted into the gen‐
93              erated  output in the <head> section of the document, just after
94              the <title> tag.
95
96       string header
97              This variable is meant to hold  a  fragment  of  HTML  (default:
98              empty).  The fragment it contains will be inserted into the gen‐
99              erated output just after the <h1> title tag in the body  of  the
100              document, in the class.header <div>'ision.
101
102       string footer
103              This  variable  is  meant  to  hold a fragment of HTML (default:
104              empty). The fragment it contains will be inserted into the  gen‐
105              erated  output  just before the </body> tag, in the class.footer
106              <div>'ision.
107
108       dictionary kwid
109              The value of this variable (default: empty) maps keywords to the
110              identifiers  to  use as their anchor names. Each keyword FOO not
111              found in the dictionary uses KW-FOO as anchor, i.e. itself  pre‐
112              fixed with the string KW-.
113
114       string sepline
115              The  value of this variable is the string to use for the separa‐
116              tor comments inserted into the output when the outpout is broken
117              across  lines and/or indented. The default string consists of 60
118              dashes.
119
120       integer kwidth
121              This variable holds the size of the keyword column in  the  main
122              table  generated by the plugin, in percent of the total width of
123              the table. This is an integer number in the range of  1  to  99.
124              Choosing  a  value outside of that range causes the generator to
125              switch back to the defauly setting, 35 percent.
126
127       string dot
128              This variable contains a  HTML  fragment  inserted  between  the
129              entries  of  the  navigation  bar, and the references associated
130              with each keyword.  The default is the HTML entity  &#183;  i.e.
131              the bullet character, also known as the "Greek middle dot", i.e.
132              the unicode character 00B7.
133
134       string class.main
135              This variable contains the class name for the main <div>'ivision
136              of the generated document. The default is doctools.
137
138       string class.header
139              This variable contains the class name for the header <div>'ision
140              of the generated document.  The  default  is  idx-header.   This
141              division contains the document title, the user specified header,
142              if any, a visible separator line, and  the  navigation  bar  for
143              quick access to each keyword section.
144
145       string class.title
146              This variable contains the class name for the <h1> tag enclosing
147              the document title. The default is idx-title.
148
149       string class.navsep
150              This variable contains the class name for the <hr> separators in
151              the  header  and  footer sections of the generated document. The
152              default is idx-navsep.
153
154       string class.navbar
155              This  variable  contains  the  class  name  for  the  navigation
156              <div>'ision  enclosing the navigation bar of the generated docu‐
157              ment. The default is idx-kwnav.
158
159       string class.contents
160              This variable contains the class name for  the  <table>  holding
161              the keywords and their references in the generated document. The
162              default is idx-contents.
163
164       string class.leader
165              This variable contains the class name for the anchor  names  the
166              plugin  inserts  into  the keyword table when switching from one
167              section to the next (Each section holds all keywords with a par‐
168              ticular first character). The default is idx-leader.
169
170       string class.row0
171              This  variable  contains  the  class name used to label the even
172              rows (<tr>) of the keyword table. The default is idx-even.
173
174       string class.row1
175              This variable contains the class name used to label the odd rows
176              (<tr>) of the keyword table. The default is idx-odd.
177
178       string class.keyword
179              This  variable contains the class name used to label the keyword
180              cells/column (<td>) in the keyword table of  the  document.  The
181              default is idx-keyword.
182
183       string class.refs
184              This  variable  contains the class name used to label the refer‐
185              ence cells/column (<td>) in the keyword table of  the  document.
186              The default is idx-refs.
187
188       string class.footer
189              This variable contains the class name for the footer <div>'ision
190              of the generated document. The default is idx-footer. This divi‐
191              sion  contains  a  browser-visible  separator  line and the user
192              specified footer, if any.
193
194       Note that this plugin ignores the standard configuration variable  for‐
195       mat, and its value.
196

KEYWORD INDEX SERIALIZATION FORMAT

198       Here  we specify the format used by the doctools v2 packages to serial‐
199       ize keyword indices as immutable values for transport, comparison, etc.
200
201       We distinguish between regular and canonical  serializations.  While  a
202       keyword index may have more than one regular serialization only exactly
203       one of them will be canonical.
204
205       regular serialization
206
207              [1]    An index serialization is a nested Tcl dictionary.
208
209              [2]    This dictionary holds a single  key,  doctools::idx,  and
210                     its value. This value holds the contents of the index.
211
212              [3]    The  contents  of  the index are a Tcl dictionary holding
213                     the title of the index, a label,  and  the  keywords  and
214                     references. The relevant keys and their values are
215
216                     title  The  value is a string containing the title of the
217                            index.
218
219                     label  The value is a string containing a label  for  the
220                            index.
221
222                     keywords
223                            The  value is a Tcl dictionary, using the keywords
224                            known to the index as keys. The associated  values
225                            are lists containing the identifiers of the refer‐
226                            ences associated with that particular keyword.
227
228                            Any reference identifier used in these  lists  has
229                            to  exist  as  a key in the references dictionary,
230                            see the next item for its definition.
231
232                     references
233                            The value is a Tcl dictionary, using  the  identi‐
234                            fiers  for  the  references  known to the index as
235                            keys. The associated values  are  2-element  lists
236                            containing the type and label of the reference, in
237                            this order.
238
239                            Any key here has to be associated  with  at  least
240                            one  keyword,  i.e.  occur  in at least one of the
241                            reference lists which are the values in  the  key‐
242                            words  dictionary, see previous item for its defi‐
243                            nition.
244
245              [4]    The type of a reference can be one of two values,
246
247                     manpage
248                            The identifier of the reference is interpreted  as
249                            symbolic  file name, referring to one of the docu‐
250                            ments the index was made for.
251
252                     url    The identifier of the reference is interpreted  as
253                            an  url, referring to some external location, like
254                            a website, etc.
255
256       canonical serialization
257              The canonical serialization of a keyword index has the format as
258              specified  in the previous item, and then additionally satisfies
259              the constraints below, which make it unique among all the possi‐
260              ble serializations of the keyword index.
261
262              [1]    The  keys  found  in  all the nested Tcl dictionaries are
263                     sorted in ascending dictionary  order,  as  generated  by
264                     Tcl's builtin command lsort -increasing -dict.
265
266              [2]    The  references  listed for each keyword of the index, if
267                     any, are listed in ascending dictionary  order  of  their
268                     labels,  as  generated  by  Tcl's  builtin  command lsort
269                     -increasing -dict.
270

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

287       HTML, doctools, export, index, serialization
288

CATEGORY

290       Text formatter plugin
291
293       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
294
295
296
297
298tcllib                                0.2       doctools::idx::export::html(n)
Impressum