1doctools::toc::export::nroff(n)Documentation tooldsoctools::toc::export::nroff(n)
2______________________________________________________________________________
6
8 doctools::toc::export::nroff - nroff export plugin
9
11 package require Tcl 8.4
12 package require doctools::toc::export::nroff ?0.2?
14 package require doctools::text
16 package require doctools::nroff::man_macros
18 export serial configuration
20______________________________________________________________________________
22
24 This package implements the doctools table of contents export plugin
25 for the generation of nroff markup.
26 This is an internal package of doctools, for use by the higher level
28 management packages handling tables of contents, especially doc‐
29 tools::toc::export, the export manager.
30 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::toc::export and the export man‐
34 ager objects it provides.
35
37 The API provided by this package satisfies the specification of the
38 doctoc export plugin API version 2.
39 export serial configuration
41 This command takes the canonical serialization of a table of
42 contents, as specified in section ToC serialization format, and
43 contained in serial, the configuration, a dictionary, and gener‐
44 ates nroff markup encoding the table. The created string is
45 then returned as the result of the command.
46
48 The nroff export plugin recognizes the following configuration vari‐
49 ables and changes its behaviour as they specify.
50 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 string file
58 This standard configuration variable contains the name of the
59 file the table of contents came from. This variable may not be
60 set or contain the empty string. The plugin puts this informa‐
61 tion, if defined, i.e. set and not the empty string, into the
62 provenance comment at the beginning of the generated document.
63 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 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 Note that this plugin ignores the standard configuration variables for‐
73 mat, and map, and their values.
74
76 Here we specify the format used by the doctools v2 packages to serial‐
77 ize tables of contents as immutable values for transport, comparison,
78 etc.
79 We distinguish between regular and canonical serializations. While a
81 table of contents may have more than one regular serialization only
82 exactly one of them will be canonical.
83 regular serialization
85 [1] The serialization of any table of contents is a nested
87 Tcl dictionary.
88 [2] This dictionary holds a single key, doctools::toc, and
90 its value. This value holds the contents of the table of
91 contents.
92 [3] The contents of the table of contents are a Tcl dictio‐
94 nary holding the title of the table of contents, a label,
95 and its elements. The relevant keys and their values are
96 title The value is a string containing the title of the
98 table of contents.
99 label The value is a string containing a label for the
101 table of contents.
102 items The value is a Tcl list holding the elements of
104 the table, in the order they are to be shown.
105 Each element is a Tcl list holding the type of the
107 item, and its description, in this order. An
108 alternative description would be that it is a Tcl
109 dictionary holding a single key, the item type,
110 mapped to the item description.
111 The two legal item types and their descriptions
113 are
114 reference
116 This item describes a single entry in the
117 table of contents, referencing a single
118 document. To this end its value is a Tcl
119 dictionary containing an id for the refer‐
120 enced document, a label, and a longer tex‐
121 tual description which can be associated
122 with the entry. The relevant keys and
123 their values are
124 id The value is a string containing the
126 id of the document associated with
127 the entry.
128 label The value is a string containing a
130 label for this entry. This string
131 also identifies the entry, and no
132 two entries (references and divi‐
133 sions) in the containing list are
134 allowed to have the same label.
135 desc The value is a string containing a
137 longer description for this entry.
138 division
140 This item describes a group of entries in
141 the table of contents, inducing a hierarchy
142 of entries. To this end its value is a Tcl
143 dictionary containing a label for the
144 group, an optional id to a document for the
145 whole group, and the list of entries in the
146 group. The relevant keys and their values
147 are
148 id The value is a string containing the
150 id of the document associated with
151 the whole group. This key is
152 optional.
153 label The value is a string containing a
155 label for the group. This string
156 also identifies the entry, and no
157 two entries (references and divi‐
158 sions) in the containing list are
159 allowed to have the same label.
160 items The value is a Tcl list holding the
162 elements of the group, in the order
163 they are to be shown. This list has
164 the same structure as the value for
165 the keyword items used to describe
166 the whole table of contents, see
167 above. This closes the recusrive
168 definition of the structure, with
169 divisions holding the same type of
170 elements as the whole table of con‐
171 tents, including other divisions.
172 canonical serialization
174 The canonical serialization of a table of contents has the for‐
175 mat as specified in the previous item, and then additionally
176 satisfies the constraints below, which make it unique among all
177 the possible serializations of this table of contents.
178 [1] The keys found in all the nested Tcl dictionaries are
180 sorted in ascending dictionary order, as generated by
181 Tcl's builtin command lsort -increasing -dict.
182
184 This document, and the package it describes, will undoubtedly contain
185 bugs and other problems. Please report such in the category doctools
186 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
187 also report any ideas for enhancements you may have for either package
188 and/or documentation.
189 When proposing code changes, please provide unified diffs, i.e the out‐
191 put of diff -u.
192 Note further that attachments are strongly preferred over inlined
194 patches. Attachments can be made by going to the Edit form of the
195 ticket immediately after its creation, and then using the left-most
196 button in the secondary navigation bar.
197
199 doctools, export, nroff, serialization, table of contents, toc
200
202 Text formatter plugin
203
205 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
206tcllib 0.2 doctools::toc::export::nroff(n)