1doctools::idx::export::docidx(nD)ocumentation toodlosctools::idx::export::docidx(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::idx::export::docidx - docidx export plugin
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::idx::export::docidx  ?0.2.1?
14
15       export serial configuration
16
17______________________________________________________________________________
18

DESCRIPTION

20       This  package  implements  the doctools keyword index export plugin for
21       the generation of docidx markup.
22
23       This is an internal package of doctools, for use by  the  higher  level
24       management   packages   handling   keyword   indices,  especially  doc‐
25       tools::idx::export, the export manager.
26
27       Using it from a regular interpreter is possible, however only with con‐
28       tortions, and is not recommended.  The proper way to use this function‐
29       ality is through the package doctools::idx::export and the export  man‐
30       ager objects it provides.
31

API

33       The API provided by this package satisfies the specification of the do‐
34       cidx export plugin API version 2.
35
36       export serial configuration
37              This command takes the canonical serialization of a keyword  in‐
38              dex, as specified in section Keyword index serialization format,
39              and contained in serial, the configuration,  a  dictionary,  and
40              generates  docidx markup encoding the index.  The created string
41              is then returned as the result of the command.
42

[DOCIDX] NOTATION OF KEYWORD INDICES

44       The docidx format for keyword indices, also called  the  docidx  markup
45       language, is too large to be covered in single section.  The interested
46       reader should start with the document
47
48       [1]    docidx language introduction
49
50       and then proceed from there to the formal specifications, i.e. the doc‐
51       uments
52
53       [1]    docidx language syntax and
54
55       [2]    docidx language command reference.
56
57       to get a thorough understanding of the language.
58

CONFIGURATION

60       The  docidx  export plugin recognizes the following configuration vari‐
61       ables and changes its behaviour as they specify.
62
63       string user
64              This standard configuration variable contains the  name  of  the
65              user  running  the process which invoked the export plugin.  The
66              plugin puts this information into the provenance comment at  the
67              beginning of the generated document.
68
69       string file
70              This  standard  configuration  variable contains the name of the
71              file the index came from. This variable may not be set  or  con‐
72              tain the empty string.  The plugin puts this information, if de‐
73              fined, i.e. set and not the empty string,  into  the  provenance
74              comment at the beginning of the generated document.
75
76       boolean newlines
77              If  this  flag is set the plugin will break the generated docidx
78              code across lines, with each markup command on a separate line.
79
80              If this flag is not set (the default), the whole  document  will
81              be  written  on  a single line, with minimum spacing between all
82              elements.
83
84       boolean indented
85              If this flag is set the plugin will indent the  markup  commands
86              according  to  the  structure of indices. To make this work this
87              also implies that newlines is set. This effect is independent of
88              the value for aligned however.
89
90              If  this  flag is not set (the default), the output is formatted
91              as per the values of newlines and aligned, and no  indenting  is
92              done.
93
94       boolean aligned
95              If this flag is set the generator ensures that the arguments for
96              the manpage and url commands in a keyword  section  are  aligned
97              vertically  for a nice table effect. To make this work this also
98              implies that newlines is set. This effect is independent of  the
99              value for indented however.
100
101              If  this  flag is not set (the default), the output is formatted
102              as per the values of newlines and indented, and no alignment  is
103              done.
104
105       Note that this plugin ignores the standard configuration variables for‐
106       mat, and map, and their values.
107

KEYWORD INDEX SERIALIZATION FORMAT

109       Here we specify the format used by the doctools v2 packages to  serial‐
110       ize keyword indices as immutable values for transport, comparison, etc.
111
112       We  distinguish  between  regular and canonical serializations. While a
113       keyword index may have more than one regular serialization only exactly
114       one of them will be canonical.
115
116       regular serialization
117
118              [1]    An index serialization is a nested Tcl dictionary.
119
120              [2]    This  dictionary  holds  a single key, doctools::idx, and
121                     its value. This value holds the contents of the index.
122
123              [3]    The contents of the index are a  Tcl  dictionary  holding
124                     the  title  of  the  index, a label, and the keywords and
125                     references. The relevant keys and their values are
126
127                     title  The value is a string containing the title of  the
128                            index.
129
130                     label  The  value  is a string containing a label for the
131                            index.
132
133                     keywords
134                            The value is a Tcl dictionary, using the  keywords
135                            known  to the index as keys. The associated values
136                            are lists containing the identifiers of the refer‐
137                            ences associated with that particular keyword.
138
139                            Any  reference  identifier used in these lists has
140                            to exist as a key in  the  references  dictionary,
141                            see the next item for its definition.
142
143                     references
144                            The  value  is a Tcl dictionary, using the identi‐
145                            fiers for the references known  to  the  index  as
146                            keys.  The  associated  values are 2-element lists
147                            containing the type and label of the reference, in
148                            this order.
149
150                            Any  key  here  has to be associated with at least
151                            one keyword, i.e. occur in at  least  one  of  the
152                            reference  lists  which are the values in the key‐
153                            words dictionary, see previous item for its  defi‐
154                            nition.
155
156              [4]    The type of a reference can be one of two values,
157
158                     manpage
159                            The  identifier of the reference is interpreted as
160                            symbolic file name, referring to one of the  docu‐
161                            ments the index was made for.
162
163                     url    The  identifier of the reference is interpreted as
164                            an url, referring to some external location,  like
165                            a website, etc.
166
167       canonical serialization
168              The canonical serialization of a keyword index has the format as
169              specified in the previous item, and then additionally  satisfies
170              the constraints below, which make it unique among all the possi‐
171              ble serializations of the keyword index.
172
173              [1]    The keys found in all the  nested  Tcl  dictionaries  are
174                     sorted  in  ascending  dictionary  order, as generated by
175                     Tcl's builtin command lsort -increasing -dict.
176
177              [2]    The references listed for each keyword of the  index,  if
178                     any,  are  listed  in ascending dictionary order of their
179                     labels, as generated by Tcl's builtin command lsort  -in‐
180                     creasing -dict.
181

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

198       docidx, doctools, export, index, serialization
199

CATEGORY

201       Text formatter plugin
202
204       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
205
206
207
208
209tcllib                               0.2.1    doctools::idx::export::docidx(n)
Impressum