1doctools(n) Documentation tools doctools(n)
2______________________________________________________________________________
6
8 doctools - doctools - Processing documents
9
11 package require Tcl 8.2
12 package require doctools ?1.4?
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 a class for the creation of objects able to
49 process and convert text written in the doctools markup language into
50 any output format X for which a formatting engine is available.
51 A reader interested in the markup language itself should start with the
53 doctools language introduction and proceed from there to the formal
54 specifications, i.e. the doctools language syntax and the doctools lan‐
55 guage command reference.
56 If on the other hand the reader wishes to write her own formatting
58 engine for some format, i.e. is a plugin writer then reading and under‐
59 standing the doctools plugin API reference is an absolute necessity, as
60 that document specifies the interaction between this package and its
61 plugins, i.e. the formatting engines, in detail.
62
64 PACKAGE COMMANDS
65 ::doctools::new objectName ?option value...?
66 This command creates a new doctools object with an associated
67 Tcl command whose name is objectName. This object command is
68 explained in full detail in the sections OBJECT COMMAND and
69 OBJECT METHODS. The object command will be created under the
70 current namespace if the objectName is not fully qualified, and
71 in the specified namespace otherwise.
72 The options and their values coming after the name of the object
74 are used to set the initial configuration of the object.
75 ::doctools::help
77 This is a convenience command for applications wishing to pro‐
78 vide their user with a short description of the available for‐
79 matting commands and their meanings. It returns a string con‐
80 taining a standard help text.
81 ::doctools::search path
83 Whenever an object created by this the package has to map the
84 name of a format to the file containing the code for its format‐
85 ting engine it will search for the file in a number of directo‐
86 ries stored in a list. See section FORMAT MAPPING for more
87 explanations.
88 This list not only contains three default directories which are
90 declared by the package itself, but is also extensible user of
91 the package. This command is the means to do so. When given a
92 path to an existing and readable directory it will prepend that
93 directory to the list of directories to search. This means that
94 the path added last is later searched through first.
95 An error will be thrown if the path either does not exist, is
97 not a directory, or is not readable.
98 OBJECT COMMAND
100 All commands created by ::doctools::new have the following general form
101 and may be used to invoke various operations on their doctools con‐
102 verter object.
103 objectName method ?arg arg ...?
105 The method method and its arg'uments determine the exact behav‐
106 ior of the command. See section OBJECT METHODS for the detailed
107 specifications.
108 OBJECT METHODS
110 objectName configure
111 The method returns a list of all known options and their current
112 values when called without any arguments.
113 objectName configure option
115 The method behaves like the method cget when called with a sin‐
116 gle argument and returns the value of the option specified by
117 said argument.
118 objectName configure -option value...
120 The method reconfigures the specified options of the object,
121 setting them to the associated values, when called with an even
122 number of arguments, at least two.
123 The legal options are described in the section OBJECT CONFIGURA‐
125 TION.
126 objectName cget -option
128 This method expects a legal configuration option as argument and
129 will return the current value of that option for the object the
130 method was invoked for.
131 The legal configuration options are described in section OBJECT
133 CONFIGURATION.
134 objectName destroy
136 This method destroys the object it is invoked for.
137 objectName format text
139 This method runs the text through the configured formatting
140 engine and returns the generated string as its result. An error
141 will be thrown if no -format was configured for the object.
142 The method assumes that the text is in doctools format as speci‐
144 fied in the companion document doctools_fmt. Errors will be
145 thrown otherwise.
146 objectName map symbolic actual
148 This methods add one entry to the per-object mapping from sym‐
149 bolic filenames to the actual uris. The object just stores this
150 mapping and makes it available to the configured formatting
151 engine through the command dt_fmap. This command is described
152 in more detail in the doctools plugin API reference which speci‐
153 fies the interaction between the objects created by this package
154 and doctools formatting engines.
155 objectName parameters
157 This method returns a list containing the names of all engine
158 parameters provided by the configured formatting engine. It will
159 return an empty list if the object is not yet configured for a
160 specific format.
161 objectName search path
163 This method extends the per-object list of paths searched for
164 doctools formatting engines. See also the command ::doc‐
165 tools::search on how to extend the per-package list of paths.
166 Note that the path entered last will be searched first. For
167 more details see section FORMAT MAPPING.
168 objectName setparam name value
170 This method sets the named engine parameter to the specified
171 value. It will throw an error if the object is either not yet
172 configured for a specific format, or if the formatting engine
173 for the configured format does not provide a parameter with the
174 given name. The list of parameters provided by the configured
175 formatting engine can be retrieved through the method parame‐
176 ters.
177 objectName warnings
179 This method returns a list containing all the warnings which
180 were generated by the configured formatting engine during the
181 last invocation of the method format.
182 OBJECT CONFIGURATION
184 All doctools objects understand the following configuration options:
185 -file file
187 The argument of this option is stored in the object and made
188 available to the configured formatting engine through the com‐
189 mand dt_file. This command is described in more detail in the
190 companion document doctools_api which specifies the API between
191 the object and formatting engines.
192 The default value of this option is the empty string.
194 The configured formatting engine should interpret the value as
196 the name of the file containing the document which is currently
197 processed.
198 -module text
200 The argument of this option is stored in the object and made
201 available to the configured formatting engine through the com‐
202 mand dt_module. This command is described in more detail in the
203 companion document doctools_api which specifies the API between
204 the object and formatting engines.
205 The default value of this option is the empty string.
207 The configured formatting engine should interpret the value as
209 the name of the module the file containing the document which is
210 currently processed belongs to.
211 -format text
213 The argument of this option specifies the format to generate and
214 by implication the formatting engine to use when converting text
215 via the method format. Its default value is the empty string.
216 The method format cannot be used if this option is not set to a
217 valid value at least once.
218 The package will immediately try to map the given name to a file
220 containing the code for a formatting engine generating that for‐
221 mat. An error will be thrown if this mapping fails. In that case
222 a previously configured format is left untouched.
223 The section FORMAT MAPPING explains in detail how the package
225 and object will look for engine implementations.
226 -deprecated boolean
228 This option is a boolean flag. The object will generate warnings
229 if this flag is set and the text given to method format contains
230 the deprecated markup command strong. Its default value is
231 FALSE. In other words, no warnings will be generated.
232 -copyright text
234 The argument of this option is stored in the object and made
235 available to the configured formatting engine through the com‐
236 mand dt_copyright. This command is described in more detail in
237 the companion document doctools_api which specifies the API
238 between the object and formatting engines.
239 The default value of this option is the empty string.
241 The configured formatting engine should interpret the value as a
243 copyright assignment for the document which is currently pro‐
244 cessed, or the package described by it.
245 This information must be used if and only if the engine is
247 unable to find any copyright assignments within the document
248 itself. Such are specified by the formatting command copyright.
249 This command is described in more detail in the companion docu‐
250 ment doctools_fmt which specifies the doctools format itself.
251 FORMAT MAPPING
253 The package and object will perform the following algorithm when trying
254 to map a format name foo to a file containing an implementation of a
255 formatting engine for foo:
256 [1] If foo is the name of an existing file then this file is
258 directly taken as the implementation.
259 [2] If not, the list of per-object search paths is searched. For
261 each directory in the list the package checks if that directory
262 contains a file "fmt.foo". If yes, then that file is taken as
263 the implementation.
264 Note that this list of paths is initially empty and can be
266 extended through the object method search.
267 [3] If not, the list of package paths is searched. For each direc‐
269 tory in the list the package checks if that directory contains a
270 file "fmt.foo". If yes, then that file is taken as the implemen‐
271 tation.
272 This list of paths can be extended through the command ::doc‐
274 tools::search. It contains initially one path, the subdirectory
275 "mpformats" of the directory the package itself is located in.
276 In other words, if the package implementation "doctools.tcl" is
277 installed in the directory "/usr/local/lib/tcllib/doctools" then
278 it will by default search the directory
279 "/usr/local/lib/tcllib/doctools/mpformats" for format implemen‐
280 tations.
281 [4] The mapping fails.
283
285 The package provides predefined engines for the following formats. Some
286 of the engines support parameters. These will be explained below as
287 well.
288 html This engine generates HTML markup, for processing by web
290 browsers and the like. This engine supports four parameters:
291 footer The value for this parameter has to be valid selfcon‐
293 tained HTML markup for the body section of a HTML docu‐
294 ment. The default value is the empty string. The value is
295 inserted into the generated output just before the
296 </body> tag, closing the body of the generated HTML.
297 This can be used to insert boilerplate footer markup into
299 the generated document.
300 header The value for this parameter has to be valid selfcon‐
302 tained HTML markup for the body section of a HTML docu‐
303 ment. The default value is the empty string. The value is
304 inserted into the generated output just after the <body>
305 tag, starting the body of the generated HTML.
306 This can be used to insert boilerplate header markup into
308 the generated document.
309 meta The value for this parameter has to be valid selfcon‐
311 tained HTML markup for the header section of a HTML docu‐
312 ment. The default value is the empty string. The value is
313 inserted into the generated output just after the <head>
314 tag, starting the header section of the generated HTML.
315 This can be used to insert boilerplate meta data markup
317 into the generated document, like references to a
318 stylesheet, standard meta keywords, etc.
319 xref The value for this parameter has to be a list of triples
321 specifying cross-reference information. This information
322 is used by the engine to create more hyperlinks. Each
323 triple is a list containing a pattern, symbolic filename
324 and fragment reference, in this order. If a pattern is
325 specified multiple times the last occurence of the pat‐
326 tern will be used.
327 The engine will consult the xref database when encounter‐
329 ing specific commands and will create a link if the rele‐
330 vant text matches one of the patterns. No link will be
331 created if no match was found. The link will go to the
332 uri file#fragment listed in the relevant triple, after
333 conversion of the symbolic file name to the actual uri
334 via dt_fmap (see the doctools plugin API reference).
335 This file-to-uri mapping was build by calls to the method
336 map of the doctools object (See section OBJECT METHODS).
337 The following formatting commands will consult the xref
339 database:
340 cmd word
342 The command will look for the patterns sa,word,
343 and word, in this order. If this fails if it will
344 convert word to all lowercase and try again.
345 syscmd word
347 The command will look for the patterns sa,word,
348 and word, in this order. If this fails if it will
349 convert word to all lowercase and try again.
350 term word
352 The command will look for the patterns kw,word,
353 sa,word, and word, in this order. If this fails if
354 it will convert word to all lowercase and try
355 again.
356 package word
358 The command will look for the patterns sa,word,
359 kw,word, and word, in this order. If this fails if
360 it will convert word to all lowercase and try
361 again.
362 see_also word...
364 The command will look for the patterns sa,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 keywords word...
370 The command will look for the patterns kw,word,
371 and word, in this order, for each word given to
372 the command. If this fails if it will convert word
373 to all lowercase and try again.
374 latex This engine generates output suitable for the latex text proces‐
377 sor coming out of the TeX world.
378 list This engine retrieves version, section and title of the manpage
380 from the document. As such it can be used to generate a direc‐
381 tory listing for a set of manpages.
382 nroff This engine generates nroff output, for processing by nroff, or
384 groff. The result will be standard man pages as they are known
385 in the unix world.
386 null This engine generates no outout at all. This can be used if one
388 just wants to validate some input.
389 tmml This engine generates TMML markup as specified by Joe English.
391 The Tcl Manpage Markup Language is a derivate of XML.
392 wiki This engine generates Wiki markup as understood by Jean Claude
394 Wippler's wikit application.
395
397 This document, and the package it describes, will undoubtedly contain
398 bugs and other problems. Please report such in the category doctools
399 of the Tcllib SF Trackers [http://source‐
400 forge.net/tracker/?group_id=12883]. Please also report any ideas for
401 enhancements you may have for either package and/or documentation.
402
404 doctools_intro, doctools_lang_cmdref, doctools_lang_intro, doc‐
405 tools_lang_syntax, doctools_plugin_apiref
406
408 HTML, TMML, conversion, documentation, manpage, markup, nroff
409
411 Copyright (c) 2003-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>
412doctools 1.4 doctools(n)