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

NAME

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

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::idx::export::nroff  ?0.3?
14
15       package require doctools::text
16
17       package require doctools::nroff::man_macros
18
19       export serial configuration
20
21______________________________________________________________________________
22

DESCRIPTION

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

API

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

CONFIGURATION

48       The nroff export plugin recognizes the  following  configuration  vari‐
49       ables and changes its behaviour as they specify.
50
51       string user
52              This  standard  configuration  variable contains the name of the
53              user running the process which invoked the export  plugin.   The
54              plugin  puts this information into the provenance comment at the
55              beginning of the generated document.
56
57       string file
58              This standard configuration variable contains the  name  of  the
59              file  the  index came from. This variable may not be set or con‐
60              tain the empty string.  The plugin puts this information, if de‐
61              fined,  i.e.  set  and not the empty string, into the provenance
62              comment at the beginning of the generated document.
63
64       boolean inline
65              If this flag is set (default) the plugin will place the  defini‐
66              tions of the man macro set directly into the output.
67
68              If  this  flag  is not set, the plugin will place a reference to
69              the definitions of the man macro set into the  output,  but  not
70              the macro definitions themselves.
71
72       Note that this plugin ignores the standard configuration variables for‐
73       mat, and map, and their values.
74

KEYWORD INDEX SERIALIZATION FORMAT

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

BUGS, IDEAS, FEEDBACK

150       This  document,  and the package it describes, will undoubtedly contain
151       bugs and other problems.  Please report such in the  category  doctools
152       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
153       also report any ideas for enhancements you may have for either  package
154       and/or documentation.
155
156       When proposing code changes, please provide unified diffs, i.e the out‐
157       put of diff -u.
158
159       Note further that  attachments  are  strongly  preferred  over  inlined
160       patches.  Attachments  can  be  made  by  going to the Edit form of the
161       ticket immediately after its creation, and  then  using  the  left-most
162       button in the secondary navigation bar.
163

KEYWORDS

165       doctools, export, index, nroff, serialization
166

CATEGORY

168       Text formatter plugin
169
171       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
172
173
174
175
176tcllib                                0.3      doctools::idx::export::nroff(n)
Impressum