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.5.6?
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 en‐
58 gine 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 ex‐
68 plained in full detail in the sections OBJECT COMMAND and OBJECT
69 METHODS. The object command will be created under the current
70 namespace if the objectName is not fully qualified, and in the
71 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 ex‐
87 planations.
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 en‐
140 gine 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 en‐
151 gine through the command dt_fmap. This command is described in
152 more detail in the doctools plugin API reference which specifies
153 the interaction between the objects created by this package and
154 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 in‐
203 stead.
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 be‐
253 tween 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 un‐
262 able to find any copyright assignments within the document it‐
263 self. 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 di‐
273 rectly 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 ex‐
281 tended 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 "/usr/lo‐
294 cal/lib/tcllib/doctools/mpformats" for format implementations.
295 [4] The mapping fails.
297
299 The package provides predefined engines for the following formats. Some
300 of the engines support parameters. These will be explained below as
301 well.
302 html This engine generates HTML markup, for processing by web
304 browsers and the like. This engine supports four parameters:
305 footer The value for this parameter has to be valid selfcon‐
307 tained HTML markup for the body section of a HTML docu‐
308 ment. The default value is the empty string. The value is
309 inserted into the generated output just before the
310 </body> tag, closing the body of the generated HTML.
311 This can be used to insert boilerplate footer markup into
313 the generated document.
314 header The value for this parameter has to be valid selfcon‐
316 tained HTML markup for the body section of a HTML docu‐
317 ment. The default value is the empty string. The value is
318 inserted into the generated output just after the <body>
319 tag, starting the body of the generated HTML.
320 This can be used to insert boilerplate header markup into
322 the generated document.
323 meta The value for this parameter has to be valid selfcon‐
325 tained HTML markup for the header section of a HTML docu‐
326 ment. The default value is the empty string. The value is
327 inserted into the generated output just after the <head>
328 tag, starting the header section of the generated HTML.
329 This can be used to insert boilerplate meta data markup
331 into the generated document, like references to a
332 stylesheet, standard meta keywords, etc.
333 xref The value for this parameter has to be a list of triples
335 specifying cross-reference information. This information
336 is used by the engine to create more hyperlinks. Each
337 triple is a list containing a pattern, symbolic filename
338 and fragment reference, in this order. If a pattern is
339 specified multiple times the last occurrence of the pat‐
340 tern will be used.
341 The engine will consult the xref database when encounter‐
343 ing specific commands and will create a link if the rele‐
344 vant text matches one of the patterns. No link will be
345 created if no match was found. The link will go to the
346 uri file#fragment listed in the relevant triple, after
347 conversion of the symbolic file name to the actual uri
348 via dt_fmap (see the doctools plugin API reference).
349 This file-to-uri mapping was build by calls to the method
350 map of the doctools object (See section OBJECT METHODS).
351 The following formatting commands will consult the xref
353 database:
354 cmd word
356 The command will look for the patterns sa,word,
357 and word, in this order. If this fails if it will
358 convert word to all lowercase and try again.
359 syscmd word
361 The command will look for the patterns sa,word,
362 and word, in this order. If this fails if it will
363 convert word to all lowercase and try again.
364 term word
366 The command will look for the patterns kw,word,
367 sa,word, and word, in this order. If this fails if
368 it will convert word to all lowercase and try
369 again.
370 package word
372 The command will look for the patterns sa,word,
373 kw,word, and word, in this order. If this fails if
374 it will convert word to all lowercase and try
375 again.
376 see_also word...
378 The command will look for the patterns sa,word,
379 and word, in this order, for each word given to
380 the command. If this fails if it will convert word
381 to all lowercase and try again.
382 keywords word...
384 The command will look for the patterns kw,word,
385 and word, in this order, for each word given to
386 the command. If this fails if it will convert word
387 to all lowercase and try again.
388 latex This engine generates output suitable for the latex text proces‐
391 sor coming out of the TeX world.
392 list This engine retrieves version, section and title of the manpage
394 from the document. As such it can be used to generate a direc‐
395 tory listing for a set of manpages.
396 nroff This engine generates nroff output, for processing by nroff, or
398 groff. The result will be standard man pages as they are known
399 in the unix world.
400 markdown
402 This engine generates Markdown markup. This engine supports two
403 parameters:
404 header The value for this parameter has to be valid selfcon‐
406 tained markdown markup for the body section of a markdown
407 document. The default value is the empty string. The
408 value is inserted into the generated output just before
409 the table of contents.
410 This can be used to insert boilerplate header markup into
412 the generated document.
413 xref The value for this parameter has to be a list of triples
415 specifying cross-reference information.
416 The full details of expected syntax and engine-internal
418 use are explained above for the html engine.
419 null This engine generates no outout at all. This can be used if one
422 just wants to validate some input.
423 tmml This engine generates TMML markup as specified by Joe English.
425 The Tcl Manpage Markup Language is a derivate of XML.
426 wiki This engine generates Wiki markup as understood by Jean Claude
428 Wippler's wikit application.
429
431 This document, and the package it describes, will undoubtedly contain
432 bugs and other problems. Please report such in the category doctools
433 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
434 also report any ideas for enhancements you may have for either package
435 and/or documentation.
436 When proposing code changes, please provide unified diffs, i.e the out‐
438 put of diff -u.
439 Note further that attachments are strongly preferred over inlined
441 patches. Attachments can be made by going to the Edit form of the
442 ticket immediately after its creation, and then using the left-most
443 button in the secondary navigation bar.
444
446 doctools_intro, doctools_lang_cmdref, doctools_lang_intro, doc‐
447 tools_lang_syntax, doctools_plugin_apiref
448
450 HTML, TMML, conversion, documentation, manpage, markdown, markup, nroff
451
453 Documentation tools
454
456 Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
457tcllib 1.5.6 doctools(n)