1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
|
<!DOCTYPE html><html><head>
<title>doctools::idx::import - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
--></style>
</head>
<!-- Generated from file 'idx_import.man' by tcllib/doctools with format 'html'
-->
<!-- Copyright &copy; 2009-2019 Andreas Kupries &lt;andreas_kupries@users.sourceforge.net&gt;
-->
<!-- doctools::idx::import.n
-->
<body><hr> [
<a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::import(n) 0.2.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::import - Importing keyword indices</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Concepts</a></li>
<li class="doctools_section"><a href="#section3">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Import plugin API v2 reference</a></li>
<li class="doctools_section"><a href="#section5">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::idx::import <span class="opt">?0.2.1?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">struct::map</b></li>
<li>package require <b class="pkgname">doctools::idx::structure</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">pluginmgr</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::idx::import</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">import text</b> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">import file</b> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">import object text</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">import object file</b> <i class="arg">object</i> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">config names</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">config get</b></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">includes</b></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">include add</b> <i class="arg">path</i></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">include remove</b> <i class="arg">path</i></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">include clear</b></a></li>
<li><a href="#16"><b class="cmd">IncludeFile</b> <i class="arg">currentfile</i> <i class="arg">path</i></a></li>
<li><a href="#17"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class to manage the plugins for the import of
keyword indices from other formats, i.e. their conversion from, for
example <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>, <i class="term"><a href="../../../../index.html#json">json</a></i>, etc.</p>
<p>This is one of the three public pillars the management of keyword
indices resides on. The other two pillars are</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="idx_export.html">Exporting keyword indices</a></i>, and</p></li>
<li><p><i class="term"><a href="idx_container.html">Holding keyword indices</a></i></p></li>
</ol>
<p>For information about the <span class="sectref"><a href="#section2">Concepts</a></span> of keyword indices, and
their parts, see the same-named section.
For information about the data structure which is the major output of
the manager objects provided by this package see the section
<span class="sectref"><a href="#section5">Keyword index serialization format</a></span>.</p>
<p>The plugin system of our class is based on the package
<b class="package"><a href="../pluginmgr/pluginmgr.html">pluginmgr</a></b>, and configured to look for plugins using</p>
<ol class="doctools_enumerated">
<li><p>the environment variable <b class="variable">DOCTOOLS_IDX_IMPORT_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_IDX_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_PLUGINS</b>,</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/import/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/import/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugins</b>"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\IMPORT\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"</p></li>
</ol>
<p>The last three are used only when the package is run on a machine
using Windows(tm) operating system.</p>
<p>The whole system is delivered with two predefined import plugins,
namely</p>
<dl class="doctools_definitions">
<dt>docidx</dt>
<dd><p>See <i class="term"><a href="import_docidx.html">docidx import plugin</a></i> for details.</p></dd>
<dt>json</dt>
<dd><p>See <i class="term">json import plugin</i> for details.</p></dd>
</dl>
<p>Readers wishing to write their own import plugin for some format, i.e.
<i class="term">plugin writer</i>s reading and understanding the section
containing the <span class="sectref"><a href="#section4">Import plugin API v2 reference</a></span> is an
absolute necessity, as it specifies the interaction between this
package and its plugins in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Concepts</a></h2>
<ol class="doctools_enumerated">
<li><p>A <i class="term"><a href="../../../../index.html#keyword_index">keyword index</a></i> consists of a (possibly empty) set of <i class="term"><a href="../../../../index.html#keywords">keywords</a></i>.</p></li>
<li><p>Each keyword in the set is identified by its name.</p></li>
<li><p>Each keyword has a (possibly empty) set of <i class="term">references</i>.</p></li>
<li><p>A reference can be associated with more than one keyword.</p></li>
<li><p>A reference not associated with at least one keyword is not possible
however.</p></li>
<li><p>Each reference is identified by its target, specified as either an url
or symbolic filename, depending on the type of reference (<b class="const">url</b>,
or <b class="const">manpage</b>).</p></li>
<li><p>The type of a reference (url, or manpage) depends only on the
reference itself, and not the keywords it is associated with.</p></li>
<li><p>In addition to a type each reference has a descriptive label as
well. This label depends only on the reference itself, and not the
keywords it is associated with.</p></li>
</ol>
<p>A few notes</p>
<ol class="doctools_enumerated">
<li><p>Manpage references are intended to be used for references to the
documents the index is made for. Their target is a symbolic file name
identifying the document, and export plugins may replace symbolic with
actual file names, if specified.</p></li>
<li><p>Url references are intended on the othre hand are inteded to be used
for links to anything else, like websites. Their target is an url.</p></li>
<li><p>While url and manpage references share a namespace for their
identifiers, this should be no problem, given that manpage identifiers
are symbolic filenames and as such they should never look like urls,
the identifiers for url references.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::idx::import</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new import manager object with an associated
Tcl command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command
is explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::doctools::idx::import</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">import text</b> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method takes the <i class="arg">text</i> and converts it from the specified
<i class="arg">format</i> to the canonical serialization of a keyword index using
the import plugin for the format. An error is thrown if no plugin
could be found for the format.
The serialization generated by the conversion process is returned as
the result of this method.</p>
<p>If no format is specified the method defaults to <b class="const">docidx</b>.</p>
<p>The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>.</p>
<p>The plugin has to conform to the interface specified in section
<span class="sectref"><a href="#section4">Import plugin API v2 reference</a></span>.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">import file</b> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">import text</b>
method described by the previous item.
It reads the contents of the specified file into memory, feeds the
result into <b class="method">import text</b> and returns the resulting
serialization as its own result.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">import object text</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">import text</b>
method described by the previous item.
It expects that <i class="arg">object</i> is an object command supporting a
<b class="method">deserialize</b> method expecting the canonical serialization of a
keyword index.
It imports the text using <b class="method">import text</b> and then feeds the
resulting serialization into the <i class="arg">object</i> via <b class="method">deserialize</b>.
This method returns the empty string as it result.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">import object file</b> <i class="arg">object</i> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method behaves like <b class="method">import object text</b>, except that it
reads the text to convert from the specified file instead of being
given it as argument.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">config names</b></a></dt>
<dd><p>This method returns a list containing the names of all configuration
variables currently known to the object.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">config get</b></a></dt>
<dd><p>This method returns a dictionary containing the names and values of
all configuration variables currently known to the object.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>This method sets the configuration variable <i class="arg">name</i> to the
specified <i class="arg">value</i> and returns the new value of the variable.</p>
<p>If no value is specified it simply returns the current value, without
changing it.</p>
<p>Note that while the user can set the predefined configuration
variables <b class="const">user</b> and <b class="const">format</b> doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></dt>
<dd><p>This method unsets all configuration variables matching the specified
glob <i class="arg">pattern</i>s. If no pattern is specified it will unset all
currently defined configuration variables.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">includes</b></a></dt>
<dd><p>This method returns a list containing the currently specified paths to
use to search for include files when processing input.
The order of paths in the list corresponds to the order in which they
are used, from first to last, and also corresponds to the order in
which they were added to the object.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">include add</b> <i class="arg">path</i></a></dt>
<dd><p>This methods adds the specified <i class="arg">path</i> to the list of paths to use
to search for include files when processing input. The path is added
to the end of the list, causing it to be searched after all previously
added paths. The result of the command is the empty string.</p>
<p>The method does nothing if the path is already known.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">include remove</b> <i class="arg">path</i></a></dt>
<dd><p>This methods removes the specified <i class="arg">path</i> from the list of paths
to use to search for include files when processing input. The result
of the command is the empty string.</p>
<p>The method does nothing if the path is not known.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">include clear</b></a></dt>
<dd><p>This method clears the list of paths to use to search for include
files when processing input. The result of the command is the empty
string.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Import plugin API v2 reference</a></h2>
<p>Plugins are what this package uses to manage the support for any input
format beyond the <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>. Here
we specify the API the objects created by this package use to interact
with their plugins.</p>
<p>A plugin for this package has to follow the rules listed below:</p>
<ol class="doctools_enumerated">
<li><p>A plugin is a package.</p></li>
<li><p>The name of a plugin package has the form
doctools::idx::import::<b class="variable">FOO</b>,
where <b class="variable">FOO</b> is the name of the format the plugin will
generate output for. This name is also the argument to provide
to the various <b class="method">import</b> methods of import manager
objects to get a string encoding a keyword index in that
format.</p></li>
<li><p>The plugin can expect that the package
<b class="package">doctools::idx::export::plugin</b> is present, as
indicator that it was invoked from a genuine plugin manager.</p></li>
<li><p>The plugin can expect that a command named <b class="cmd">IncludeFile</b> is
present, with the signature</p>
<dl class="doctools_definitions">
<dt><a name="16"><b class="cmd">IncludeFile</b> <i class="arg">currentfile</i> <i class="arg">path</i></a></dt>
<dd><p>This command has to be invoked by the plugin when it has to process an
included file, if the format has the concept of such. An example of
such a format would be <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>.</p>
<p>The plugin has to supply the following arguments</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">currentfile</i></dt>
<dd><p>The path of the file it is currently processing. This may be the empty
string if no such is known.</p></dd>
<dt>string <i class="arg">path</i></dt>
<dd><p>The path of the include file as specified in the include directive
being processed.</p></dd>
</dl>
<p>The result of the command will be a 5-element list containing</p>
<ol class="doctools_enumerated">
<li><p>A boolean flag indicating the success (<b class="const">True</b>) or failure
(<b class="const">False</b>) of the operation.</p></li>
<li><p>In case of success the contents of the included file, and the
empty string otherwise.</p></li>
<li><p>The resolved, i.e. absolute path of the included file, if
possible, or the unchanged <i class="arg">path</i> argument. This is for
display in an error message, or as the <i class="arg">currentfile</i>
argument of another call to <b class="cmd">IncludeFile</b> should this file
contain more files.</p></li>
<li><p>In case of success an empty string, and for failure a code
indicating the reason for it, one of</p>
<dl class="doctools_definitions">
<dt>notfound</dt>
<dd><p>The specified file could not be found.</p></dd>
<dt>notread</dt>
<dd><p>The specified file was found, but not be read into memory.</p></dd>
</dl>
</li>
<li><p>An empty string in case of success of a <b class="const">notfound</b>
failure, and an additional error message describing the reason
for a <b class="const">notread</b> error in more detail.</p></li>
</ol></dd>
</dl>
</li>
<li><p>A plugin has to provide one command, with the signature shown
below.</p>
<dl class="doctools_definitions">
<dt><a name="17"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i> <i class="arg">configuration</i></a></dt>
<dd><p>Whenever an import manager of <b class="package"><a href="idx_container.html">doctools::idx</a></b> has to parse
input for an index it will invoke this command.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">text</i></dt>
<dd><p>This argument will contain the text encoding the index per the format
the plugin is for.</p></dd>
<dt>dictionary <i class="arg">configuration</i></dt>
<dd><p>This argument will contain the current configuration to apply to the
parsing, as a dictionary mapping from variable names to values.</p>
<p>The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables recognized
by a plugin will be described in the manpage for that plugin.</p>
<dl class="doctools_definitions">
<dt>user</dt>
<dd><p>This variable is expected to contain the name of the user
owning the process invoking the plugin.</p></dd>
<dt>format</dt>
<dd><p>This variable is expected to contain the name of the
format whose plugin is invoked.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
<li><p>A single usage cycle of a plugin consists of the invokations of
the command <b class="cmd"><a href="../../../../index.html#import">import</a></b>. This call has to leave the plugin in
a state where another usage cycle can be run without problems.</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#json">json</a>, <a href="../../../../index.html#keyword_index">keyword index</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#reference">reference</a>, <a href="../../../../index.html#url">url</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net></p>
</div>
</div></body></html>
|
