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.21?
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 mands dt_file and dt_mainfile. These commands are described in
190 more detail in the companion document doctools_api which speci‐
191 fies the API between 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 -ibase file
200 The argument of this option is stored in the object and used as
201 the base path for resolution of relative include paths. If this
202 option is not set (empty string) the value of -file is used
203 instead.
204 Note that -file and -ibase, while similar looking, are actually
206 very different. The value of -file is used by some engines for
207 the generation of proper relative references between output doc‐
208 uments (HTML). As such this is a destination path. The -ibase on
209 the other hand is used to resolve relative include paths, and as
210 such deals with source paths.
211 The default value of this option is the empty string.
213 -module text
215 The argument of this option is stored in the object and made
216 available to the configured formatting engine through the com‐
217 mand dt_module. This command is described in more detail in the
218 companion document doctools_api which specifies the API between
219 the object and formatting engines.
220 The default value of this option is the empty string.
222 The configured formatting engine should interpret the value as
224 the name of the module the file containing the document which is
225 currently processed belongs to.
226 -format text
228 The argument of this option specifies the format to generate and
229 by implication the formatting engine to use when converting text
230 via the method format. Its default value is the empty string.
231 The method format cannot be used if this option is not set to a
232 valid value at least once.
233 The package will immediately try to map the given name to a file
235 containing the code for a formatting engine generating that for‐
236 mat. An error will be thrown if this mapping fails. In that case
237 a previously configured format is left untouched.
238 The section FORMAT MAPPING explains in detail how the package
240 and object will look for engine implementations.
241 -deprecated boolean
243 This option is a boolean flag. The object will generate warnings
244 if this flag is set and the text given to method format contains
245 the deprecated markup command strong. Its default value is
246 FALSE. In other words, no warnings will be generated.
247 -copyright text
249 The argument of this option is stored in the object and made
250 available to the configured formatting engine through the com‐
251 mand dt_copyright. This command is described in more detail in
252 the companion document doctools_api which specifies the API
253 between the object and formatting engines.
254 The default value of this option is the empty string.
256 The configured formatting engine should interpret the value as a
258 copyright assignment for the document which is currently pro‐
259 cessed, or the package described by it.
260 This information must be used if and only if the engine is
262 unable to find any copyright assignments within the document
263 itself. Such are specified by the formatting command copyright.
264 This command is described in more detail in the companion docu‐
265 ment doctools_fmt which specifies the doctools format itself.
266 FORMAT MAPPING
268 The package and object will perform the following algorithm when trying
269 to map a format name foo to a file containing an implementation of a
270 formatting engine for foo:
271 [1] If foo is the name of an existing file then this file is
273 directly taken as the implementation.
274 [2] If not, the list of per-object search paths is searched. For
276 each directory in the list the package checks if that directory
277 contains a file "fmt.foo". If yes, then that file is taken as
278 the implementation.
279 Note that this list of paths is initially empty and can be
281 extended through the object method search.
282 [3] If not, the list of package paths is searched. For each direc‐
284 tory in the list the package checks if that directory contains a
285 file "fmt.foo". If yes, then that file is taken as the implemen‐
286 tation.
287 This list of paths can be extended through the command ::doc‐
289 tools::search. It contains initially one path, the subdirectory
290 "mpformats" of the directory the package itself is located in.
291 In other words, if the package implementation "doctools.tcl" is
292 installed in the directory "/usr/local/lib/tcllib/doctools" then
293 it will by default search the directory
294 "/usr/local/lib/tcllib/doctools/mpformats" for format implemen‐
295 tations.
296 [4] The mapping fails.
298
300 The package provides predefined engines for the following formats. Some
301 of the engines support parameters. These will be explained below as
302 well.
303 html This engine generates HTML markup, for processing by web
305 browsers and the like. This engine supports four parameters:
306 footer The value for this parameter has to be valid selfcon‐
308 tained HTML markup for the body section of a HTML docu‐
309 ment. The default value is the empty string. The value is
310 inserted into the generated output just before the
311 </body> tag, closing the body of the generated HTML.
312 This can be used to insert boilerplate footer markup into
314 the generated document.
315 header The value for this parameter has to be valid selfcon‐
317 tained HTML markup for the body section of a HTML docu‐
318 ment. The default value is the empty string. The value is
319 inserted into the generated output just after the <body>
320 tag, starting the body of the generated HTML.
321 This can be used to insert boilerplate header markup into
323 the generated document.
324 meta The value for this parameter has to be valid selfcon‐
326 tained HTML markup for the header section of a HTML docu‐
327 ment. The default value is the empty string. The value is
328 inserted into the generated output just after the <head>
329 tag, starting the header section of the generated HTML.
330 This can be used to insert boilerplate meta data markup
332 into the generated document, like references to a
333 stylesheet, standard meta keywords, etc.
334 xref The value for this parameter has to be a list of triples
336 specifying cross-reference information. This information
337 is used by the engine to create more hyperlinks. Each
338 triple is a list containing a pattern, symbolic filename
339 and fragment reference, in this order. If a pattern is
340 specified multiple times the last occurrence of the pat‐
341 tern will be used.
342 The engine will consult the xref database when encounter‐
344 ing specific commands and will create a link if the rele‐
345 vant text matches one of the patterns. No link will be
346 created if no match was found. The link will go to the
347 uri file#fragment listed in the relevant triple, after
348 conversion of the symbolic file name to the actual uri
349 via dt_fmap (see the doctools plugin API reference).
350 This file-to-uri mapping was build by calls to the method
351 map of the doctools object (See section OBJECT METHODS).
352 The following formatting commands will consult the xref
354 database:
355 cmd word
357 The command will look for the patterns sa,word,
358 and word, in this order. If this fails if it will
359 convert word to all lowercase and try again.
360 syscmd word
362 The command will look for the patterns sa,word,
363 and word, in this order. If this fails if it will
364 convert word to all lowercase and try again.
365 term word
367 The command will look for the patterns kw,word,
368 sa,word, and word, in this order. If this fails if
369 it will convert word to all lowercase and try
370 again.
371 package word
373 The command will look for the patterns sa,word,
374 kw,word, and word, in this order. If this fails if
375 it will convert word to all lowercase and try
376 again.
377 see_also word...
379 The command will look for the patterns sa,word,
380 and word, in this order, for each word given to
381 the command. If this fails if it will convert word
382 to all lowercase and try again.
383 keywords word...
385 The command will look for the patterns kw,word,
386 and word, in this order, for each word given to
387 the command. If this fails if it will convert word
388 to all lowercase and try again.
389 latex This engine generates output suitable for the latex text proces‐
392 sor coming out of the TeX world.
393 list This engine retrieves version, section and title of the manpage
395 from the document. As such it can be used to generate a direc‐
396 tory listing for a set of manpages.
397 nroff This engine generates nroff output, for processing by nroff, or
399 groff. The result will be standard man pages as they are known
400 in the unix world.
401 null This engine generates no outout at all. This can be used if one
403 just wants to validate some input.
404 tmml This engine generates TMML markup as specified by Joe English.
406 The Tcl Manpage Markup Language is a derivate of XML.
407 wiki This engine generates Wiki markup as understood by Jean Claude
409 Wippler's wikit application.
410
412 This document, and the package it describes, will undoubtedly contain
413 bugs and other problems. Please report such in the category doctools
414 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
415 also report any ideas for enhancements you may have for either package
416 and/or documentation.
417 When proposing code changes, please provide unified diffs, i.e the out‐
419 put of diff -u.
420 Note further that attachments are strongly preferred over inlined
422 patches. Attachments can be made by going to the Edit form of the
423 ticket immediately after its creation, and then using the left-most
424 button in the secondary navigation bar.
425
427 doctools_intro, doctools_lang_cmdref, doctools_lang_intro, doc‐
428 tools_lang_syntax, doctools_plugin_apiref
429
431 HTML, TMML, conversion, documentation, manpage, markup, nroff
432
434 Documentation tools
435
437 Copyright (c) 2003-2017 Andreas Kupries <andreas_kupries@users.sourceforge.net>
438tcllib 1.4.21 doctools(n)