1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
|
[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.4.19]
[manpage_begin doctools n [vset PACKAGE_VERSION]]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_intro]
[see_also doctools_lang_syntax]
[see_also doctools_plugin_apiref]
[keywords conversion]
[keywords documentation]
[keywords HTML]
[keywords manpage]
[keywords markup]
[keywords nroff]
[keywords TMML]
[copyright {2003-2014 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
[moddesc {Documentation tools}]
[titledesc {doctools - Processing documents}]
[category {Documentation tools}]
[require Tcl 8.2]
[require doctools [opt [vset PACKAGE_VERSION]]]
[description]
This package provides a class for the creation of objects able to
process and convert text written in the [term doctools] markup
language into any output format X for which a
[term {formatting engine}] is available.
[para]
A reader interested in the markup language itself should start with
the [term {doctools language introduction}] and proceed from there to
the formal specifications, i.e. the [term {doctools language syntax}]
and the [term {doctools language command reference}].
[para]
If on the other hand the reader wishes to write her own formatting
engine for some format, i.e. is a [term {plugin writer}] then reading
and understanding the [term {doctools plugin API reference}] is an
absolute necessity, as that document specifies the interaction between
this package and its plugins, i.e. the formatting engines, in detail.
[section {PUBLIC API}]
[subsection {PACKAGE COMMANDS}]
[list_begin definitions]
[call [cmd ::doctools::new] [arg objectName] [opt [arg "option value"]...]]
This command creates a new doctools object with an associated Tcl
command whose name is [arg objectName]. This [term object] command is
explained in full detail in the sections [sectref {OBJECT COMMAND}]
and [sectref {OBJECT METHODS}]. The object command will be created
under the current namespace if the [arg objectName] is not fully
qualified, and in the specified namespace otherwise.
[para]
The options and their values coming after the name of the object are
used to set the initial configuration of the object.
[call [cmd ::doctools::help]]
This is a convenience command for applications wishing to provide
their user with a short description of the available formatting
commands and their meanings. It returns a string containing a standard
help text.
[call [cmd ::doctools::search] [arg path]]
Whenever an object created by this the package has to map the name of
a format to the file containing the code for its formatting engine it
will search for the file in a number of directories stored in a
list. See section [sectref {FORMAT MAPPING}] for more explanations.
[para]
This list not only contains three default directories which are
declared by the package itself, but is also extensible user of the
package.
This command is the means to do so. When given a [arg path] to an
existing and readable directory it will prepend that directory to the
list of directories to search. This means that the [arg path] added
last is later searched through first.
[para]
An error will be thrown if the [arg path] either does not exist, is
not a directory, or is not readable.
[list_end]
[subsection {OBJECT COMMAND}]
All commands created by [cmd ::doctools::new] have the following
general form and may be used to invoke various operations on their
doctools converter object.
[list_begin definitions]
[call [cmd objectName] [method method] [opt [arg "arg arg ..."]]]
The method [method method] and its [arg arg]'uments determine the exact
behavior of the command. See section [sectref {OBJECT METHODS}] for
the detailed specifications.
[list_end]
[subsection {OBJECT METHODS}]
[list_begin definitions]
[call [arg objectName] [method configure]]
The method returns a list of all known options and their current
values when called without any arguments.
[call [arg objectName] [method configure] [arg option]]
The method behaves like the method [method cget] when called with a
single argument and returns the value of the option specified by said
argument.
[call [arg objectName] [method configure] [option -option] [arg value]...]
The method reconfigures the specified [option option]s of the object,
setting them to the associated [arg value]s, when called with an even
number of arguments, at least two.
[para]
The legal options are described in the section
[sectref {OBJECT CONFIGURATION}].
[call [arg objectName] [method cget] [option -option]]
This method expects a legal configuration option as argument and will
return the current value of that option for the object the method was
invoked for.
[para]
The legal configuration options are described in section
[sectref {OBJECT CONFIGURATION}].
[call [arg objectName] [method destroy]]
This method destroys the object it is invoked for.
[call [arg objectName] [method format] [arg text]]
This method runs the [arg text] through the configured formatting
engine and returns the generated string as its result. An error will
be thrown if no [option -format] was configured for the object.
[para]
The method assumes that the [arg text] is in [term doctools] format as
specified in the companion document [term doctools_fmt]. Errors will
be thrown otherwise.
[call [arg objectName] [method map] [arg symbolic] [arg actual]]
This methods add one entry to the per-object mapping from
[arg symbolic] filenames to the [arg actual] uris.
The object just stores this mapping and makes it available to the
configured formatting engine through the command [cmd dt_fmap].
This command is described in more detail in the
[term {doctools plugin API reference}] which specifies the interaction
between the objects created by this package and doctools formatting
engines.
[call [arg objectName] [method parameters]]
This method returns a list containing the names of all engine
parameters provided by the configured formatting engine. It will
return an empty list if the object is not yet configured for a
specific format.
[call [arg objectName] [method search] [arg path]]
This method extends the per-object list of paths searched for doctools
formatting engines. See also the command [cmd ::doctools::search] on
how to extend the per-package list of paths. Note that the path
entered last will be searched first.
For more details see section [sectref {FORMAT MAPPING}].
[call [arg objectName] [method setparam] [arg name] [arg value]]
This method sets the [arg name]d engine parameter to the specified
[arg value].
It will throw an error if the object is either not yet configured for
a specific format, or if the formatting engine for the configured
format does not provide a parameter with the given [arg name].
The list of parameters provided by the configured formatting engine
can be retrieved through the method [method parameters].
[call [arg objectName] [method warnings]]
This method returns a list containing all the warnings which were
generated by the configured formatting engine during the last
invocation of the method [method format].
[list_end]
[subsection {OBJECT CONFIGURATION}]
All doctools objects understand the following configuration options:
[list_begin options]
[opt_def -file [arg file]]
The argument of this option is stored in the object and made available
to the configured formatting engine through the commands [cmd dt_file]
and [cmd dt_mainfile].
These commands are described in more detail in the companion document
[term doctools_api] which specifies the API between the object and
formatting engines.
[para]
The default value of this option is the empty string.
[para]
The configured formatting engine should interpret the value as the
name of the file containing the document which is currently processed.
[opt_def -ibase [arg file]]
The argument of this option is stored in the object and used as the
base path for resolution of relative include paths. If this option is
not set (empty string) the value of [option -file] is used instead.
[para]
Note that [option -file] and [option -ibase], while similar looking,
are actually very different. The value of [option -file] is used by
some engines for the generation of proper relative references between
output documents (HTML). As such this is a [term destination]
path. The [option -ibase] on the other hand is used to resolve
relative include paths, and as such deals with [term source] paths.
[para]
The default value of this option is the empty string.
[opt_def -module [arg text]]
The argument of this option is stored in the object and made available
to the configured formatting engine through the command [cmd dt_module].
This command is described in more detail in the companion document
[term doctools_api] which specifies the API between the object and
formatting engines.
[para]
The default value of this option is the empty string.
[para]
The configured formatting engine should interpret the value as the
name of the module the file containing the document which is currently
processed belongs to.
[opt_def -format [arg text]]
The argument of this option specifies the format to generate and by
implication the formatting engine to use when converting text via the
method [method format]. Its default value is the empty string. The
method [method format] cannot be used if this option is not set to a
valid value at least once.
[para]
The package will immediately try to map the given name to a file
containing the code for a formatting engine generating that format. An
error will be thrown if this mapping fails. In that case a previously
configured format is left untouched.
[para]
The section [sectref {FORMAT MAPPING}] explains in detail how the
package and object will look for engine implementations.
[opt_def -deprecated [arg boolean]]
This option is a boolean flag. The object will generate warnings if
this flag is set and the text given to method [method format] contains
the deprecated markup command [cmd strong].
Its default value is [const FALSE]. In other words, no warnings will
be generated.
[opt_def -copyright [arg text]]
The argument of this option is stored in the object and made available
to the configured formatting engine through the command [cmd dt_copyright].
This command is described in more detail in the companion document
[term doctools_api] which specifies the API between the object and
formatting engines.
[para]
The default value of this option is the empty string.
[para]
The configured formatting engine should interpret the value as a
copyright assignment for the document which is currently processed, or
the package described by it.
[para]
This information must be used if and only if the engine is unable to
find any copyright assignments within the document itself. Such are
specified by the formatting command [cmd copyright]. This command is
described in more detail in the companion document [term doctools_fmt]
which specifies the [term doctools] format itself.
[list_end]
[subsection {FORMAT MAPPING}]
The package and object will perform the following algorithm when
trying to map a format name [term foo] to a file containing an
implementation of a formatting engine for [term foo]:
[list_begin enumerated]
[enum]
If [term foo] is the name of an existing file then this file is
directly taken as the implementation.
[enum]
If not, the list of per-object search paths is searched. For each
directory in the list the package checks if that directory contains a
file [file fmt.[term foo]]. If yes, then that file is taken as the
implementation.
[para]
Note that this list of paths is initially empty and can be extended
through the object method [method search].
[enum]
If not, the list of package paths is searched.
For each directory in the list the package checks if that directory
contains a file [file fmt.[term foo]]. If yes, then that file is taken
as the implementation.
[para]
This list of paths can be extended
through the command [cmd ::doctools::search].
It contains initially one path, the subdirectory [file mpformats] of
the directory the package itself is located in.
In other words, if the package implementation [file doctools.tcl] is
installed in the directory [file /usr/local/lib/tcllib/doctools] then
it will by default search the
directory [file /usr/local/lib/tcllib/doctools/mpformats] for format
implementations.
[enum]
The mapping fails.
[list_end]
[section {PREDEFINED ENGINES}]
The package provides predefined engines for the following
formats. Some of the engines support parameters. These will be
explained below as well.
[list_begin definitions]
[def html]
This engine generates HTML markup, for processing by web browsers and
the like. This engine supports four parameters:
[list_begin definitions]
[def footer]
The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
before the [const </body>] tag, closing the body of the generated
HTML.
[para]
This can be used to insert boilerplate footer markup into the
generated document.
[def header]
The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
after the [const <body>] tag, starting the body of the generated HTML.
[para]
This can be used to insert boilerplate header markup into the
generated document.
[def meta]
The value for this parameter has to be valid selfcontained HTML markup
for the header section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
after the [const <head>] tag, starting the header section of the
generated HTML.
[para]
This can be used to insert boilerplate meta data markup into the
generated document, like references to a stylesheet, standard meta
keywords, etc.
[def xref]
The value for this parameter has to be a list of triples specifying
cross-reference information. This information is used by the engine to
create more hyperlinks. Each triple is a list containing a pattern,
symbolic filename and fragment reference, in this order. If a pattern
is specified multiple times the last occurence of the pattern will be
used.
[para]
The engine will consult the xref database when encountering specific
commands and will create a link if the relevant text matches one of
the patterns. No link will be created if no match was found. The link
will go to the uri [const {file#fragment}] listed in the relevant
triple, after conversion of the symbolic file name to the actual uri
via [cmd dt_fmap] (see the [term {doctools plugin API reference}]).
This file-to-uri mapping was build by calls to the method [method map]
of the doctools object (See section [sectref {OBJECT METHODS}]).
[para]
The following formatting commands will consult the xref database:
[list_begin definitions]
[def "[cmd cmd] [arg word]"]
The command will look for the patterns [const sa,][arg word], and
[arg word], in this order. If this fails if it will convert [arg word]
to all lowercase and try again.
[def "[cmd syscmd] [arg word]"]
The command will look for the patterns [const sa,][arg word], and
[arg word], in this order. If this fails if it will convert [arg word]
to all lowercase and try again.
[def "[cmd term] [arg word]"]
The command will look for the patterns [const kw,][arg word],
[const sa,][arg word], and [arg word], in this order. If this fails if
it will convert [arg word] to all lowercase and try again.
[def "[cmd package] [arg word]"]
The command will look for the patterns [const sa,][arg word],
[const kw,][arg word], and [arg word], in this order. If this fails if
it will convert [arg word] to all lowercase and try again.
[def "[cmd see_also] [arg word]..."]
The command will look for the patterns [const sa,][arg word], and
[arg word], in this order, for each [arg word] given to the
command. If this fails if it will convert [arg word] to all lowercase
and try again.
[def "[cmd keywords] [arg word]..."]
The command will look for the patterns [const kw,][arg word], and
[arg word], in this order, for each [arg word] given to the
command. If this fails if it will convert [arg word] to all lowercase
and try again.
[list_end]
[list_end]
[para]
[def latex]
This engine generates output suitable for the [syscmd latex] text
processor coming out of the TeX world.
[def list]
This engine retrieves version, section and title of the manpage from
the document. As such it can be used to generate a directory listing
for a set of manpages.
[def nroff]
This engine generates nroff output, for processing by [syscmd nroff],
or [syscmd groff]. The result will be standard man pages as they are
known in the unix world.
[def null]
This engine generates no outout at all. This can be used if one just
wants to validate some input.
[def tmml]
This engine generates TMML markup as specified by Joe English. The Tcl
Manpage Markup Language is a derivate of XML.
[def wiki]
This engine generates Wiki markup as understood by Jean Claude
Wippler's [syscmd wikit] application.
[list_end]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
|