1doctools::toc(n) Documentation tools doctools::toc(n)
2______________________________________________________________________________
6
8 doctools::toc - Create and manipulate doctoc converter objects
9
11 package require Tcl 8.2
12 package require doctools::toc ?0.2.1?
14 ::doctools::toc::new objectName ?-option value ...?
16 ::doctools::toc::help
18 ::doctools::toc::search path
20 objectName method ?arg arg ...?
22 objectName configure
24 objectName configure option
26 objectName configure -option value...
28 objectName cget -option
30 objectName destroy
32 objectName format text
34 objectName map symbolic actual
36 objectName parameters
38 objectName search path
40 objectName setparam name value
42 objectName warnings
44_________________________________________________________________
46
48 This package provides objects for the conversion of text written in the
49 doctoc format into any output format X, assuming that a formatting
50 engine for X is available.
51 This document has two companions. The first, doctoc_fmt, is the formal
53 specification of the doctoc format; the other, doctoc_api, is the for‐
54 mal specification of the interface between the objects provided here
55 and the formatting engines they require.
56
58 PACKAGE COMMANDS
59 ::doctools::toc::new objectName ?-option value ...?
60 This command creates a new doctoc object with an associated Tcl
61 command whose name is objectName. This object command is
62 explained in full detail in the sections OBJECT COMMAND and
63 OBJECT METHODS. The object command will be created under the
64 current namespace if the objectName is not fully qualified, and
65 in the specified namespace otherwise.
66 The options and their values coming after the name of the object
68 are used to set the initial configuration of the object.
69 ::doctools::toc::help
71 This is a convenience command for applications wishing to pro‐
72 vide their user with a short description of the available for‐
73 matting commands and their meanings. It returns a string con‐
74 taining a standard help text.
75 ::doctools::toc::search path
77 Whenever an object created by this the package has to map the
78 name of a format to the file containing the code for its format‐
79 ting engine it will search for the file in a number of directo‐
80 ries stored in a list. See section FORMAT MAPPING for more
81 explanations.
82 This list not only contains three default directories which are
84 declared by the package itself, but is also extensible user of
85 the package. This command is the means to do so. When given a
86 path to an existing and readable directory it will prepend that
87 directory to the list of directories to search. This means that
88 the path added last is later searched through first.
89 An error will be thrown if the path either does not exist, is
91 not a directory, or is not readable.
92 OBJECT COMMAND
94 All commands created by ::doctools::toc::new have the following general
95 form and may be used to invoke various operations on their doctoc con‐
96 verter object.
97 objectName method ?arg arg ...?
99 The method method and its arg'uments determine the exact behav‐
100 ior of the command. See section OBJECT METHODS for the detailed
101 specifications.
102 OBJECT METHODS
104 objectName configure
105 The method returns a list of all known options and their current
106 values when called without any arguments.
107 objectName configure option
109 The method behaves like the method cget when called with a sin‐
110 gle argument and returns the value of the option specified by
111 said argument.
112 objectName configure -option value...
114 The method reconfigures the specified options of the object,
115 setting them to the associated values, when called with an even
116 number of arguments, at least two.
117 The legal options are described in the section OBJECT CONFIGURA‐
119 TION.
120 objectName cget -option
122 This method expects a legal configuration option as argument and
123 will return the current value of that option for the object the
124 method was invoked for.
125 The legal configuration options are described in section OBJECT
127 CONFIGURATION.
128 objectName destroy
130 This method destroys the object it is invoked for.
131 objectName format text
133 This method runs the text through the configured formatting
134 engine and returns the generated string as its result. An error
135 will be thrown if no -format was configured for the object.
136 The method assumes that the text is in doctoc format as speci‐
138 fied in the companion document doctoc_fmt. Errors will be thrown
139 otherwise.
140 objectName map symbolic actual
142 This methods add one entry to the per-object mapping from sym‐
143 bolic filenames to the actual uris. The object just stores this
144 mapping and makes it available to the configured formatting
145 engine through the command dt_fmap. This command is described
146 in more detail in the companion document doctoc_api which speci‐
147 fies the API between the object and toc formatting engines.
148 objectName parameters
150 This method returns a list containing the names of all engine
151 parameters provided by the configured formatting engine. It will
152 return an empty list if the object is not yet configured for a
153 specific format.
154 objectName search path
156 This method extends the per-object list of paths searched for
157 toc formatting engines. See also the command ::doc‐
158 tools::toc::search on how to extend the per-package list of
159 paths. Note that the path entered last will be searched first.
160 For more details see section FORMAT MAPPING.
161 objectName setparam name value
163 This method sets the named engine parameter to the specified
164 value. It will throw an error if the object is either not yet
165 configured for a specific format, or if the formatting engine
166 for the configured format does not provide a parameter with the
167 given name. The list of parameters provided by the configured
168 formatting engine can be retrieved through the method parame‐
169 ters.
170 objectName warnings
172 This method returns a list containing all the warnings which
173 were generated by the configured formatting engine during the
174 last invocation of the method format.
175 OBJECT CONFIGURATION
177 All doctoc objects understand the following configuration options:
178 -file file
180 The argument of this option is stored in the object and made
181 available to the configured formatting engine through the com‐
182 mand dt_file. This command is described in more detail in the
183 companion document doctoc_api which specifies the API between
184 the object and formatting engines.
185 The default value of this option is the empty string.
187 The configured formatting engine should interpret the value as
189 the name of the file containing the document which is currently
190 processed.
191 -format text
193 The argument of this option specifies the format to generate and
194 by implication the formatting engine to use when converting text
195 via the method format. Its default value is the empty string.
196 The method format cannot be used if this option is not set to a
197 valid value at least once.
198 The package will immediately try to map the given name to a file
200 containing the code for a formatting engine generating that for‐
201 mat. An error will be thrown if this mapping fails. In that case
202 a previously configured format is left untouched.
203 The section FORMAT MAPPING explains in detail how the package
205 and object will look for engine implementations.
206 FORMAT MAPPING
208 The package and object will perform the following algorithm when trying
209 to map a format name foo to a file containing an implementation of a
210 formatting engine for foo:
211 [1] If foo is the name of an existing file then this file is
213 directly taken as the implementation.
214 [2] If not, the list of per-object search paths is searched. For
216 each directory in the list the package checks if that directory
217 contains a file "toc.foo". If yes, then that file is taken as
218 the implementation.
219 Note that this list of paths is initially empty and can be
221 extended through the object method search.
222 [3] If not, the list of package paths is searched. For each direc‐
224 tory in the list the package checks if that directory contains a
225 file "toc.foo". If yes, then that file is taken as the implemen‐
226 tation.
227 This list of paths can be extended through the command ::doc‐
229 tools::toc::search. It contains initially one path, the subdi‐
230 rectory "mpformats" of the directory the package itself is
231 located in. In other words, if the package implementation "doc‐
232 toc.tcl" is installed in the directory
233 "/usr/local/lib/tcllib/doctools" then it will by default search
234 the directory "/usr/local/lib/tcllib/doctools/mpformats" for
235 format implementations.
236 [4] The mapping fails.
238
240 The package provides predefined formatting engines for the following
241 formats. Some of the formatting engines support engine parameters.
242 These will be explicitly highlighted.
243 html This engine generates HTML markup, for processing by web
245 browsers and the like. This engine supports three parameters:
246 footer The value for this parameter has to be valid selfcon‐
248 tained HTML markup for the body section of a HTML docu‐
249 ment. The default value is the empty string. The value is
250 inserted into the generated output just before the
251 </body> tag, closing the body of the generated HTML.
252 This can be used to insert boilerplate footer markup into
254 the generated document.
255 header The value for this parameter has to be valid selfcon‐
257 tained HTML markup for the body section of a HTML docu‐
258 ment. The default value is the empty string. The value is
259 inserted into the generated output just after the <body>
260 tag, starting the body of the generated HTML.
261 This can be used to insert boilerplate header markup into
263 the generated document.
264 meta The value for this parameter has to be valid selfcon‐
266 tained HTML markup for the header section of a HTML docu‐
267 ment. The default value is the empty string. The value is
268 inserted into the generated output just after the <head>
269 tag, starting the header section of the generated HTML.
270 This can be used to insert boilerplate meta data markup
272 into the generated document, like references to a
273 stylesheet, standard meta keywords, etc.
274 latex This engine generates output suitable for the latex text proces‐
277 sor coming out of the TeX world.
278 list This engine retrieves version, section and title of the manpage
280 from the document. As such it can be used to generate a direc‐
281 tory listing for a set of manpages.
282 nroff This engine generates nroff output, for processing by nroff, or
284 groff. The result will be standard man pages as they are known
285 in the unix world.
286 null This engine generates no outout at all. This can be used if one
288 just wants to validate some input.
289 tmml This engine generates TMML markup as specified by Joe English.
291 The Tcl Manpage Markup Language is a derivate of XML.
292 wiki This engine generates Wiki markup as understood by Jean Claude
294 Wippler's wikit application.
295
297 doctoc_api, doctoc_fmt, doctools
298
300 HTML, TMML, conversion, doctoc, documentation, latex, manpage, markup,
301 nroff, table of contents, toc, wiki
302
304 Copyright (c) 2003-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
305doctools 0.2.1 doctools::toc(n)