1doctools(n) Documentation tools doctools(n)
2______________________________________________________________________________
6
8 doctools - Create and manipulate doctools converter objects
9
11 package require Tcl 8.2
12 package require doctools ?1.2.1?
14 ::doctools::new objectName ?option value...?
16 ::doctools::help
18 ::doctools::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 doctools format into any output format X, assuming that a formatting
50 engine for X is available.
51 This document has two companions. The first, doctools_fmt, is the for‐
53 mal specification of the doctools format; the other, doctools_api, is
54 the formal specification of the interface between the objects provided
55 here and the formatting engines they require.
56
58 PACKAGE COMMANDS
59 ::doctools::new objectName ?option value...?
60 This command creates a new doctools object with an associated
61 Tcl 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::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::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::new have the following general form
95 and may be used to invoke various operations on their doctools 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 doctools format as speci‐
138 fied in the companion document doctools_fmt. Errors will be
139 thrown 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 doctools_api which
147 specifies the API between the object and doctools formatting
148 engines.
149 objectName parameters
151 This method returns a list containing the names of all engine
152 parameters provided by the configured formatting engine. It will
153 return an empty list if the object is not yet configured for a
154 specific format.
155 objectName search path
157 This method extends the per-object list of paths searched for
158 doctools formatting engines. See also the command ::doc‐
159 tools::search on how to extend the per-package list of paths.
160 Note that the path entered last will be searched first. For
161 more details see section FORMAT MAPPING.
162 objectName setparam name value
164 This method sets the named engine parameter to the specified
165 value. It will throw an error if the object is either not yet
166 configured for a specific format, or if the formatting engine
167 for the configured format does not provide a parameter with the
168 given name. The list of parameters provided by the configured
169 formatting engine can be retrieved through the method parame‐
170 ters.
171 objectName warnings
173 This method returns a list containing all the warnings which
174 were generated by the configured formatting engine during the
175 last invocation of the method format.
176 OBJECT CONFIGURATION
178 All doctools objects understand the following configuration options:
179 -file file
181 The argument of this option is stored in the object and made
182 available to the configured formatting engine through the com‐
183 mand dt_file. This command is described in more detail in the
184 companion document doctools_api which specifies the API between
185 the object and formatting engines.
186 The default value of this option is the empty string.
188 The configured formatting engine should interpret the value as
190 the name of the file containing the document which is currently
191 processed.
192 -module text
194 The argument of this option is stored in the object and made
195 available to the configured formatting engine through the com‐
196 mand dt_module. This command is described in more detail in the
197 companion document doctools_api which specifies the API between
198 the object and formatting engines.
199 The default value of this option is the empty string.
201 The configured formatting engine should interpret the value as
203 the name of the module the file containing the document which is
204 currently processed belongs to.
205 -format text
207 The argument of this option specifies the format to generate and
208 by implication the formatting engine to use when converting text
209 via the method format. Its default value is the empty string.
210 The method format cannot be used if this option is not set to a
211 valid value at least once.
212 The package will immediately try to map the given name to a file
214 containing the code for a formatting engine generating that for‐
215 mat. An error will be thrown if this mapping fails. In that case
216 a previously configured format is left untouched.
217 The section FORMAT MAPPING explains in detail how the package
219 and object will look for engine implementations.
220 -deprecated boolean
222 This option is a boolean flag. The object will generate warnings
223 if this flag is set and the text given to method format contains
224 the deprecated markup command strong. Its default value is
225 FALSE. In other words, no warnings will be generated.
226 -copyright text
228 The argument of this option is stored in the object and made
229 available to the configured formatting engine through the com‐
230 mand dt_copyright. This command is described in more detail in
231 the companion document doctools_api which specifies the API
232 between the object and formatting engines.
233 The default value of this option is the empty string.
235 The configured formatting engine should interpret the value as a
237 copyright assignment for the document which is currently pro‐
238 cessed, or the package described by it.
239 This information must be used if and only if the engine is
241 unable to find any copyright assignments within the document
242 itself. Such are specified by the formatting command copyright.
243 This command is described in more detail in the companion docu‐
244 ment doctools_fmt which specifies the doctools format itself.
245 FORMAT MAPPING
247 The package and object will perform the following algorithm when trying
248 to map a format name foo to a file containing an implementation of a
249 formatting engine for foo:
250 [1] If foo is the name of an existing file then this file is
252 directly taken as the implementation.
253 [2] If not, the list of per-object search paths is searched. For
255 each directory in the list the package checks if that directory
256 contains a file "fmt.foo". If yes, then that file is taken as
257 the implementation.
258 Note that this list of paths is initially empty and can be
260 extended through the object method search.
261 [3] If not, the list of package paths is searched. For each direc‐
263 tory in the list the package checks if that directory contains a
264 file "fmt.foo". If yes, then that file is taken as the implemen‐
265 tation.
266 This list of paths can be extended through the command ::doc‐
268 tools::search. It contains initially one path, the subdirectory
269 "mpformats" of the directory the package itself is located in.
270 In other words, if the package implementation "doctools.tcl" is
271 installed in the directory "/usr/local/lib/tcllib/doctools" then
272 it will by default search the directory
273 "/usr/local/lib/tcllib/doctools/mpformats" for format implemen‐
274 tations.
275 [4] The mapping fails.
277
279 The package provides predefined engines for the following formats. Some
280 of the engines support parameters. These will be explained below as
281 well.
282 html This engine generates HTML markup, for processing by web
284 browsers and the like. This engine supports four parameters:
285 footer The value for this parameter has to be valid selfcon‐
287 tained HTML markup for the body section of a HTML docu‐
288 ment. The default value is the empty string. The value is
289 inserted into the generated output just before the
290 </body> tag, closing the body of the generated HTML.
291 This can be used to insert boilerplate footer markup into
293 the generated document.
294 header The value for this parameter has to be valid selfcon‐
296 tained HTML markup for the body section of a HTML docu‐
297 ment. The default value is the empty string. The value is
298 inserted into the generated output just after the <body>
299 tag, starting the body of the generated HTML.
300 This can be used to insert boilerplate header markup into
302 the generated document.
303 meta The value for this parameter has to be valid selfcon‐
305 tained HTML markup for the header section of a HTML docu‐
306 ment. The default value is the empty string. The value is
307 inserted into the generated output just after the <head>
308 tag, starting the header section of the generated HTML.
309 This can be used to insert boilerplate meta data markup
311 into the generated document, like references to a
312 stylesheet, standard meta keywords, etc.
313 xref The value for this parameter has to be a list of triples
315 specifying cross-reference information. This information
316 is used by the engine to create more hyperlinks. Each
317 triple is a list containing a pattern, symbolic filename
318 and fragment reference, in this order. If a pattern is
319 specified multiple times the last occurence of the pat‐
320 tern will be used.
321 The engine will consult the xref database when encounter‐
323 ing specific commands and will create a link if the rele‐
324 vant text matches one of the patterns. No link will be
325 created if no match was found. The link will go to the
326 uri file#fragment listed in the relevant triple, after
327 conversion of the symbolic file name to the actual uri
328 via dt_fmap (see doctools_api). This file-to-uri mapping
329 was build by calls to the method map of the doctools
330 object (See section OBJECT METHODS).
331 The following formatting commands will consult the xref
333 database:
334 cmd word
336 The command will look for the patterns sa,word,
337 and word, in this order. If this fails if it will
338 convert word to all lowercase and try again.
339 syscmd word
341 The command will look for the patterns sa,word,
342 and word, in this order. If this fails if it will
343 convert word to all lowercase and try again.
344 term word
346 The command will look for the patterns kw,word,
347 sa,word, and word, in this order. If this fails if
348 it will convert word to all lowercase and try
349 again.
350 package word
352 The command will look for the patterns sa,word,
353 kw,word, and word, in this order. If this fails if
354 it will convert word to all lowercase and try
355 again.
356 see_also word...
358 The command will look for the patterns sa,word,
359 and word, in this order, for each word given to
360 the command. If this fails if it will convert word
361 to all lowercase and try again.
362 keywords word...
364 The command will look for the patterns kw,word,
365 and word, in this order, for each word given to
366 the command. If this fails if it will convert word
367 to all lowercase and try again.
368 latex This engine generates output suitable for the latex text proces‐
371 sor coming out of the TeX world.
372 list This engine retrieves version, section and title of the manpage
374 from the document. As such it can be used to generate a direc‐
375 tory listing for a set of manpages.
376 nroff This engine generates nroff output, for processing by nroff, or
378 groff. The result will be standard man pages as they are known
379 in the unix world.
380 null This engine generates no outout at all. This can be used if one
382 just wants to validate some input.
383 tmml This engine generates TMML markup as specified by Joe English.
385 The Tcl Manpage Markup Language is a derivate of XML.
386 wiki This engine generates Wiki markup as understood by Jean Claude
388 Wippler's wikit application.
389
391 doctools_api, doctools_fmt
392
394 HTML, TMML, conversion, documentation, index, manpage, markup, nroff,
395 table of contents, toc
396
398 Copyright (c) 2003-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
399doctools 1.2.1 doctools(n)