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

NAME

8       doctools::idx::export - Exporting keyword indices
9

SYNOPSIS

11       package require doctools::idx::export  ?0.2?
12
13       package require Tcl  8.4
14
15       package require doctools::config
16
17       package require doctools::idx::structure
18
19       package require snit
20
21       package require pluginmgr
22
23       ::doctools::idx::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       keyword indices to other formats, i.e. their conversion to, for example
48       docidx, HTML, etc.
49
50       This  is  one  of  the  three  public pillars the management of keyword
51       indices resides on. The other two pillars are
52
53       [1]    Importing keyword indices, and
54
55       [2]    Holding keyword indices
56
57       For information about the Concepts of keyword indices, and their parts,
58       see  the  same-named section.  For information about the data structure
59       which is the major input to the manager objects provided by this  pack‐
60       age see the section Keyword index 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_IDX_EXPORT_PLUGINS,
66
67       [2]    the environment variable DOCTOOLS_IDX_PLUGINS,
68
69       [3]    the environment variable DOCTOOLS_PLUGINS,
70
71       [4]    the path "~/.doctools/idx/export/plugin"
72
73       [5]    the path "~/.doctools/idx/plugin"
74
75       [6]    the path "~/.doctools/plugin"
76
77       [7]    the path "~/.doctools/idx/export/plugins"
78
79       [8]    the path "~/.doctools/idx/plugins"
80
81       [9]    the path "~/.doctools/plugins"
82
83       [10]   the     registry     entry      "HKEY_CURRENT_USER\SOFTWARE\DOC‐
84              TOOLS\IDX\EXPORT\PLUGINS"
85
86       [11]   the      registry     entry     "HKEY_CURRENT_USER\SOFTWARE\DOC‐
87              TOOLS\IDX\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       docidx See docidx 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 keyword index consists of a (possibly empty) set of keywords.
116
117       [2]    Each keyword in the set is identified by its name.
118
119       [3]    Each keyword has a (possibly empty) set of references.
120
121       [4]    A reference can be associated with more than one keyword.
122
123       [5]    A reference not associated with at least one keyword is not pos‐
124              sible however.
125
126       [6]    Each reference is identified by its target, specified as  either
127              an  url or symbolic filename, depending on the type of reference
128              (url, or manpage).
129
130       [7]    The type of a reference (url, or manpage) depends  only  on  the
131              reference itself, and not the keywords it is associated with.
132
133       [8]    In  addition to a type each reference has a descriptive label as
134              well. This label depends only on the reference itself,  and  not
135              the keywords it is associated with.
136
137       A few notes
138
139       [1]    Manpage references are intended to be used for references to the
140              documents the index is made for. Their target is a symbolic file
141              name  identifying  the  document, and export plugins may replace
142              symbolic with actual file names, if specified.
143
144       [2]    Url references are intended on the othre hand are inteded to  be
145              used  for links to anything else, like websites. Their target is
146              an url.
147
148       [3]    While url and manpage references share  a  namespace  for  their
149              identifiers, this should be no problem, given that manpage iden‐
150              tifiers are symbolic filenames and as  such  they  should  never
151              look like urls, the identifiers for url references.
152

API

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

EXPORT PLUGIN API V2 REFERENCE

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

KEYWORD INDEX SERIALIZATION FORMAT

296       Here we specify the format used by the doctools v2 packages to  serial‐
297       ize keyword indices as immutable values for transport, comparison, etc.
298
299       We  distinguish  between  regular and canonical serializations. While a
300       keyword index may have more than one regular serialization only exactly
301       one of them will be canonical.
302
303       regular serialization
304
305              [1]    An index serialization is a nested Tcl dictionary.
306
307              [2]    This  dictionary  holds  a single key, doctools::idx, and
308                     its value. This value holds the contents of the index.
309
310              [3]    The contents of the index are a  Tcl  dictionary  holding
311                     the  title  of  the  index, a label, and the keywords and
312                     references. The relevant keys and their values are
313
314                     title  The value is a string containing the title of  the
315                            index.
316
317                     label  The  value  is a string containing a label for the
318                            index.
319
320                     keywords
321                            The value is a Tcl dictionary, using the  keywords
322                            known  to the index as keys. The associated values
323                            are lists containing the identifiers of the refer‐
324                            ences associated with that particular keyword.
325
326                            Any  reference  identifier used in these lists has
327                            to exist as a key in  the  references  dictionary,
328                            see the next item for its definition.
329
330                     references
331                            The  value  is a Tcl dictionary, using the identi‐
332                            fiers for the references known  to  the  index  as
333                            keys.  The  associated  values are 2-element lists
334                            containing the type and label of the reference, in
335                            this order.
336
337                            Any  key  here  has to be associated with at least
338                            one keyword, i.e. occur in at  least  one  of  the
339                            reference  lists  which are the values in the key‐
340                            words dictionary, see previous item for its  defi‐
341                            nition.
342
343              [4]    The type of a reference can be one of two values,
344
345                     manpage
346                            The  identifier of the reference is interpreted as
347                            symbolic file name, referring to one of the  docu‐
348                            ments the index was made for.
349
350                     url    The  identifier of the reference is interpreted as
351                            an url, referring to some external location,  like
352                            a website, etc.
353
354       canonical serialization
355              The canonical serialization of a keyword index has the format as
356              specified in the previous item, and then additionally  satisfies
357              the constraints below, which make it unique among all the possi‐
358              ble serializations of the keyword index.
359
360              [1]    The keys found in all the  nested  Tcl  dictionaries  are
361                     sorted  in  ascending  dictionary  order, as generated by
362                     Tcl's builtin command lsort -increasing -dict.
363
364              [2]    The references listed for each keyword of the  index,  if
365                     any,  are  listed  in ascending dictionary order of their
366                     labels, as  generated  by  Tcl's  builtin  command  lsort
367                     -increasing -dict.
368

BUGS, IDEAS, FEEDBACK

370       This  document,  and the package it describes, will undoubtedly contain
371       bugs and other problems.  Please report such in the  category  doctools
372       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
373       also report any ideas for enhancements you may have for either  package
374       and/or documentation.
375
376       When proposing code changes, please provide unified diffs, i.e the out‐
377       put of diff -u.
378
379       Note further that  attachments  are  strongly  preferred  over  inlined
380       patches.  Attachments  can  be  made  by  going to the Edit form of the
381       ticket immediately after its creation, and  then  using  the  left-most
382       button in the secondary navigation bar.
383

KEYWORDS

385       HTML,  conversion,  docidx,  documentation, export, formatting, genera‐
386       tion, index, json, keyword index, manpage, markup, nroff, plugin,  ref‐
387       erence, tcler's wiki, text, url, wiki
388

CATEGORY

390       Documentation tools
391
393       Copyright (c) 2009-2018 Andreas Kupries <andreas_kupries@users.sourceforge.net>
394
395
396
397
398tcllib                                0.2             doctools::idx::export(n)
Impressum