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

NAME

8       doctools::idx::export::text - plain text export plugin
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::idx::export::text  ?0.2?
14
15       package require doctools::text
16
17       export serial configuration
18
19______________________________________________________________________________
20

DESCRIPTION

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

API

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

CONFIGURATION

46       The text export plugin recognizes the following configuration variables
47       and changes its behaviour as they specify.
48
49       dictionary map
50              This  standard configuration variable contains a dictionary map‐
51              ping from the symbolic files names in manpage references to  the
52              actual filenames and/or urls to be used in the output.
53
54              Url  references  and  symbolic  file names without a mapping are
55              used unchanged.
56
57       Note that this plugin  ignores  the  standard  configuration  variables
58       user, file, and format, and their values.
59

KEYWORD INDEX SERIALIZATION FORMAT

61       Here  we specify the format used by the doctools v2 packages to serial‐
62       ize keyword indices as immutable values for transport, comparison, etc.
63
64       We distinguish between regular and canonical  serializations.  While  a
65       keyword index may have more than one regular serialization only exactly
66       one of them will be canonical.
67
68       regular serialization
69
70              [1]    An index serialization is a nested Tcl dictionary.
71
72              [2]    This dictionary holds a single  key,  doctools::idx,  and
73                     its value. This value holds the contents of the index.
74
75              [3]    The  contents  of  the index are a Tcl dictionary holding
76                     the title of the index, a label,  and  the  keywords  and
77                     references. The relevant keys and their values are
78
79                     title  The  value is a string containing the title of the
80                            index.
81
82                     label  The value is a string containing a label  for  the
83                            index.
84
85                     keywords
86                            The  value is a Tcl dictionary, using the keywords
87                            known to the index as keys. The associated  values
88                            are lists containing the identifiers of the refer‐
89                            ences associated with that particular keyword.
90
91                            Any reference identifier used in these  lists  has
92                            to  exist  as  a key in the references dictionary,
93                            see the next item for its definition.
94
95                     references
96                            The value is a Tcl dictionary, using  the  identi‐
97                            fiers  for  the  references  known to the index as
98                            keys. The associated values  are  2-element  lists
99                            containing the type and label of the reference, in
100                            this order.
101
102                            Any key here has to be associated  with  at  least
103                            one  keyword,  i.e.  occur  in at least one of the
104                            reference lists which are the values in  the  key‐
105                            words  dictionary, see previous item for its defi‐
106                            nition.
107
108              [4]    The type of a reference can be one of two values,
109
110                     manpage
111                            The identifier of the reference is interpreted  as
112                            symbolic  file name, referring to one of the docu‐
113                            ments the index was made for.
114
115                     url    The identifier of the reference is interpreted  as
116                            an  url, referring to some external location, like
117                            a website, etc.
118
119       canonical serialization
120              The canonical serialization of a keyword index has the format as
121              specified  in the previous item, and then additionally satisfies
122              the constraints below, which make it unique among all the possi‐
123              ble serializations of the keyword index.
124
125              [1]    The  keys  found  in  all the nested Tcl dictionaries are
126                     sorted in ascending dictionary  order,  as  generated  by
127                     Tcl's builtin command lsort -increasing -dict.
128
129              [2]    The  references  listed for each keyword of the index, if
130                     any, are listed in ascending dictionary  order  of  their
131                     labels,  as generated by Tcl's builtin command lsort -in‐
132                     creasing -dict.
133

BUGS, IDEAS, FEEDBACK

135       This document, and the package it describes, will  undoubtedly  contain
136       bugs  and  other problems.  Please report such in the category doctools
137       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
138       also  report any ideas for enhancements you may have for either package
139       and/or documentation.
140
141       When proposing code changes, please provide unified diffs, i.e the out‐
142       put of diff -u.
143
144       Note  further  that  attachments  are  strongly  preferred over inlined
145       patches. Attachments can be made by going  to  the  Edit  form  of  the
146       ticket  immediately  after  its  creation, and then using the left-most
147       button in the secondary navigation bar.
148

KEYWORDS

150       doctools, export, index, plain text, serialization
151

CATEGORY

153       Text formatter plugin
154
156       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
157
158
159
160
161tcllib                                0.2       doctools::idx::export::text(n)
Impressum