1doctools_api(n) Documentation tools doctools_api(n)
2______________________________________________________________________________
6
8 doctools_api - Specification of the Interface to Doctools Formatting
9 Engines
10
12 fmt_numpasses
13 fmt_initialize
15 fmt_setup n
17 fmt_postprocess text
19 fmt_shutdown
21 fmt_listvariables
23 fmt_varset varname text
25 fmt_plain_text text
27 fmt_comment text
29 fmt_manpage_begin command section version
31 fmt_manpage_end
33 fmt_moddesc desc
35 fmt_titledesc desc
37 fmt_copyright text
39 fmt_description
41 fmt_require pkg ?version?
43 fmt_section name
45 fmt_subsection name
47 fmt_para
49 fmt_see_also args
51 fmt_keywords args
53 fmt_arg text
55 fmt_cmd text
57 fmt_opt text
59 fmt_emph text
61 fmt_strong text
63 fmt_sectref text ?label?
65 fmt_syscmd text
67 fmt_method text
69 fmt_namespace text
71 fmt_option text
73 fmt_widget text
75 fmt_fun text
77 fmt_type text
79 fmt_package text
81 fmt_class text
83 fmt_var text
85 fmt_file text
87 fmt_uri text ?text?
89 fmt_term text
91 fmt_const text
93 fmt_nl
95 fmt_example_begin
97 fmt_example_end
99 fmt_list_begin what
101 fmt_list_end
103 fmt_bullet
105 fmt_enum
107 fmt_lst_item text
109 fmt_call args
111 fmt_arg_def type name ?mode?
113 fmt_opt_def name ?arg?
115 fmt_cmd_def command
117 fmt_tkoption_def name dbname dbclass
119 fmt_usage args
121 dt_copyright
123 dt_file
125 dt_fileid
127 dt_fmap symfname
129 dt_format
131 dt_lnesting
133 dt_module
135 dt_source file
137 dt_user
139 ex_cappend
141 ex_cget
143 ex_cis
145 ex_cname
147 ex_cpop
149 ex_cpush
151 ex_cset
153 ex_lb
155 ex_rb
157 c_inpass
159 c_begin
161 c_begun
163 c_set_module text
165 c_get_module
167 c_set_title text
169 c_get_title
171 c_provenance
173 c_pass pass proc arguments body
175 c_holdBuffers args
177 c_hold buffer entry
179 c_held buffer
181 c_cnext
183 c_cinit
185 c_creset
187 NOP args
189 NYI ?message?
191 c_sectionId name
193 c_possibleReference text gi
195_________________________________________________________________
197
199 This document specifies version 1 of the interface a doctools format‐
200 ting engine has to comply with to be usable by the package doctools.
201 The specification of the doctools format all doctools formatting
202 engines have to process can be found in the companion document doc‐
203 tools_fmt.
204
206 EXPORTED COMMANDS
207 Each doctools formatting engine has to provide a number of commands
208 through which objects created by the package doctools will upon the
209 functionality of the engine. These commands are described here.
210 Management commands
212 fmt_numpasses
214 This command is called by a doctools object immediately
215 after it has loaded the engine. No other command of the
216 engine will be called before it. It has to return the
217 number of passes this engine requires to fully process
218 the input document. This value has to be an integer num‐
219 ber greater or equal to one.
220 fmt_initialize
222 This command is called at the beginning of every conver‐
223 sion run, as the first command of that run. Note that a
224 run is not a pass, but may consist of multiple passes.
225 See fmt_numpasses. The command has to initialize the gen‐
226 eral state of the doctools formatting engine, beyond the
227 initialization done during the load.
228 fmt_setup n
230 This command is called at the beginning of each pass over
231 the input in a run. Its argument is the number of the
232 pass which has begun. Passes are counted from 1 upward.
233 The command has to set up the internal state of the doc‐
234 tools formatting engine for this particular pass.
235 fmt_postprocess text
237 This command is called immediately after the last pass in
238 a run. Its argument is the result of the conversion gen‐
239 erated by that pass. It is provided to allow the engine
240 to perform any global last-ditch modifications of the
241 generated document. The text returned by this command
242 will be the final result of the conversion.
243 An engine for a format which requires no postprocessing
245 can simply return the argument without change.
246 fmt_shutdown
248 This command is called at the end of every conversion
249 run. It is the last command called in a run. It has to
250 clean up of all the run-specific state in the doctools
251 formatting engine. After the call the engine has to be in
252 a state which allows the initiation of another run with‐
253 out fear that information from the last run is leaked
254 into this new run.
255 fmt_listvariables
257 This command is called by a doctools object after it has
258 loaded the engine (after fmt_numpasses). It has to return
259 a list containing the names of the engine parameters pro‐
260 vided by the engine. This list can be empty.
261 fmt_varset varname text
263 This command is called whenever the doctools object
264 wishes to set an engine parameter to a particular value.
265 The parameter to change is specified by varname, the
266 value to set in text.
267 The command has to throw an error if an unknown varname
269 is used. Only the names returned by fmt_listvariables are
270 considered known.
271 The values of all engine parameters have to persist
273 between passes and runs.
274 Formatting commands
276 The commands listed in this section are responsible for the con‐
277 version of the input into the wanted output. Their names are
278 the names of the associated markup command, with prefix fmt_
279 added to them. Not all markup commands have associated format‐
280 ting commands. The two exceptions are vset and include. These
281 markup commands are processed by the doctools object itself.
282 A detailed documentation of the markup commands can be found in
284 the companion document doctools_fmt. It is the formal specifica‐
285 tion of the doctools format.
286 Note: The formatting commands can expect that they are only
288 called in an order allowed by the format specification.
289 fmt_plain_text text
291 This command has no associated markup command. It is
292 called for any plain text encountered by the processor in
293 the input. It has to perform any special processing
294 required for plain text. The text returned as its result
295 is added to the output. If no special processing is
296 required it has to simply return its argument without
297 change.
298 fmt_comment text
300 This command has to format the text as a comment and
301 return the formatted string. It has to return the empty
302 string if the output format has no way of formatting com‐
303 ments.
304 fmt_manpage_begin command section version
306 This command has to format the command name, the section
307 the manpage resides in, and the version of the module as
308 the start of the generated manpage and return the format‐
309 ted string.
310 fmt_manpage_end
312 This command has to generate the end of the generated
313 manpage and return the formatted string.
314 fmt_moddesc desc
316 This command remembers its argument desc as a short
317 description of the module the manpage resides in. It may
318 or may not return a formatted string.
319 fmt_titledesc desc
321 This command remembers its argument desc as the title of
322 the manpage. It may or may not return a formatted string.
323 If this command was omitted the argument of moddesc has
324 to be be used for the title as well.
325 fmt_copyright text
327 This command remembers its argument text as declaration
328 of a copyright assignment for the manpage. When invoked
329 more than once the assignments have to be accumulated. It
330 may or may not return a formatted string.
331 Assignments provided by this command have priority over
333 information supplied by an doctools processing applica‐
334 tion.
335 fmt_description
337 This command separates the header part of the manpage
338 from the main body. It may or may not return a formatted
339 string.
340 fmt_require pkg ?version?
342 This command remembers its arguments as name and version
343 of a package which is required by an application or other
344 library to use the described package. It may or may not
345 return a formatted string.
346 fmt_section name
348 This command partitions the body of the manpage into
349 named sections. Note that the command description at the
350 beginning of the manpage body implicitly started a sec‐
351 tion named "DESCRIPTION". A section command has to close
352 the last paragraph coming before it and also open the
353 first paragraph of the new section. It may or may not
354 return a formatted string.
355 fmt_subsection name
357 This command partitions the body of a section into named
358 sub-sections. A subsection command has to close the last
359 paragraph coming before it and also opens the first para‐
360 graph of the new section. It may or may not return a
361 formatted string.
362 fmt_para
364 This command partitions the text in a section or sub-sec‐
365 tion into paragraphs. Each invokation has to close the
366 paragraph coming before it and open a new paragraph for
367 the text coming after. It may or may not return a for‐
368 matted string.
369 fmt_see_also args
371 This command defines direct cross-references to other
372 documents. Each argument is a label identifying the ref‐
373 erenced document. If this command is used multiple times
374 all the arguments have to accumulate. It may or may not
375 return a formatted string.
376 fmt_keywords args
378 This command defines the keywords applying to this docu‐
379 ment. Each argument is a single keyword. If this command
380 is used multiple times all the arguments have to accumu‐
381 late. It may or may not return a formatted string.
382 fmt_arg text
384 This command declares that the argument text is the name
385 of a command argument. It has to return a formatted
386 string.
387 fmt_cmd text
389 This command declares that the argument text is the name
390 of a command. It has to return a formatted string.
391 fmt_opt text
393 This command declares that the argument text is something
394 optional. It has to return a formatted string.
395 fmt_emph text
397 This command emphasizes the text. It has to return a
398 formatted string.
399 fmt_strong text
401 This command emphasizes the text. Same as emph. Usage of
402 this command is discouraged. The command is deprecated
403 and present only for backward compatibility. It has to
404 return a formatted string.
405 fmt_sectref text ?label?
407 This command declares that the argument text is the name
408 of a section somewhere else in the document, and the cur‐
409 rent location should refer to it. It has to return a
410 formatted string. If a label is specified then it has to
411 be used in the returned text. Otherwise the section title
412 text is used.
413 fmt_syscmd text
415 This command declares that the argument text is the name
416 of a system command. It has to return a formatted
417 string.
418 fmt_method text
420 This command declares that the argument text is the name
421 of an object method. It has to return a formatted
422 string.
423 fmt_namespace text
425 This command declares that the argument text is the name
426 of a namespace. It has to return a formatted string.
427 fmt_option text
429 This command declares that the argument text is the name
430 of an option. It has to return a formatted string.
431 fmt_widget text
433 This command declares that the argument text is the name
434 of a widget. It has to return a formatted string.
435 fmt_fun text
437 This command declares that the argument text is the name
438 of a function. It has to return a formatted string.
439 fmt_type text
441 This command declares that the argument text is the name
442 of a data type. It has to return a formatted string.
443 fmt_package text
445 This command declares that the argument text is the name
446 of a package. It has to return a formatted string.
447 fmt_class text
449 This command declares that the argument text is the name
450 of a class. It has to return a formatted string.
451 fmt_var text
453 This command declares that the argument text is the name
454 of a variable. It has to return a formatted string.
455 fmt_file text
457 This command declares that the argument text is a file.
458 It has to return a formatted string.
459 fmt_uri text ?text?
461 This command declares that the argument text is an uri.
462 The second argument, if it is present, is the human-read‐
463 able description of the uri. In other words, the label
464 for the link. Without a labeling text the uri is used as
465 its own label. It has to return a formatted string.
466 fmt_term text
468 This command declares that the argument text contains
469 some unspecific terminology. It has to return a format‐
470 ted string.
471 fmt_const text
473 This command declares that the argument text is a con‐
474 stant value. It has to return a formatted string.
475 fmt_nl This command signals vertical space to separate blocks of
477 text. It may or may not return a formatted string.
478 fmt_example_begin
480 This command begins an example block. Subsequent text
481 belongs to the example. Line breaks, spaces, and tabs
482 have to be preserved literally. It may or may not return
483 a formatted string.
484 fmt_example_end
486 This command closes the example block. It may or may not
487 return a formatted string.
488 fmt_list_begin what
490 This command starts new list. The value of the argument
491 what determines what type of list is opened. This also
492 defines what command has to be used to start an item in
493 the new list. The allowed types (and their associated
494 item commands) are explained in the format specification,
495 i.e. doctools_fmt. It may or may not return a formatted
496 string.
497 fmt_list_end
499 This command ends the list opened by the last list_begin.
500 It may or may not return a formatted string.
501 fmt_bullet
503 This command starts a new list item in a bulletted list.
504 The previous item has to be closed automatically. It may
505 or may not return a formatted string.
506 fmt_enum
508 This command starts a new list item in an enumerated
509 list. The previous item has to be closed automatically.
510 It may or may not return a formatted string.
511 fmt_lst_item text
513 This command starts a new list item in a definition list.
514 The argument is the term to be defined. The previous item
515 has to be closed automatically. It may or may not return
516 a formatted string.
517 fmt_call args
519 This command starts a new list item in a definition list,
520 but the term defined by it is a command and its argu‐
521 ments. The previous item is automatically closed. The
522 first argument is the name of the described command, and
523 everything after that are descriptions of the command
524 arguments. It may or may not return a formatted string.
525 fmt_arg_def type name ?mode?
527 This command starts a new list item in an argument list.
528 The previous item has to be closed automatically. Speci‐
529 fies the data-type of the described argument, its name
530 and its i/o-mode. The latter is optional. It may or may
531 not return a formatted string.
532 fmt_opt_def name ?arg?
534 This command starts a new list item in an option list.
535 The previous item has to be closed automatically. Speci‐
536 fies the name of the option and its arguments (arg). The
537 latter is a list, and can be left out. It may or may not
538 return a formatted string.
539 fmt_cmd_def command
541 This command starts a new list item in a command list.
542 The previous item has to be closed automatically. Speci‐
543 fies the name of the command. It may or may not return a
544 formatted string.
545 fmt_tkoption_def name dbname dbclass
547 This command starts a new list item in a widget option
548 list. The previous item has to be closed automatically.
549 Specifies the name of the option, i.e. the name used in
550 scripts, the name used by the option database (dbname),
551 and the class (type) of the option (dbclass). It may or
552 may not return a formatted string.
553 fmt_usage args
555 This command is like call, except that a formatting
556 engine must not generate output at the location of the
557 command. In other words, this command is silent. The data
558 it defines may appear in a different section of the out‐
559 put, for example a table of contents, or synopsis,
560 depending on the formatting engine and its output format.
561 It may or may not return a formatted string.
562 IMPORTED ENVIRONMENT
564 The implementation of a doctools formatting engine can make the follow‐
565 ing assumptions about the environment it is executed in:
566 [1] That it has full access to its own safe interpreter. In other
568 words, the engine cannot damage the other parts of the proces‐
569 sor, nor can it damage the filesystem.
570 [2] That the following commands are provided by the doctools object
572 controlling the engine:
573 Doctools commands
575 dt_copyright
577 This command returns a string containing the copy‐
578 right information the doctools object was config‐
579 ured with (option -copyright).
580 dt_file
582 This command returns the full name of the file
583 currently processed by the engine.
584 dt_fileid
586 This command returns the name of the file cur‐
587 rently processed by the engine, without path, nor
588 extension.
589 dt_fmap symfname
591 This command returns the actual name to use in the
592 output in place of the symbolic filename symfname.
593 It will return the unchanged input if no mapping
594 was found for symfname.
595 dt_format
597 This command returns the name of the format cur‐
598 rently executing.
599 dt_lnesting
601 This command returns the number of lists currently
602 open.
603 dt_module
605 This command returns the name of the module the
606 file currently processed belongs to.
607 dt_source file
609 This command allows the doctools formatting engine
610 to load additional tcl code. Only files which are
611 either in the same directory as the file contain‐
612 ing the engine, or below it, can be loaded. Trying
613 to load a file outside of this directory causes an
614 error.
615 dt_user
617 This command returns the name of the current user
618 as known to the tcl interpreter the doctools
619 object controlling the engine resides in.
620 Expander commands
622 All of the commands below are methods of the expander
623 object (without the prefix ex_) handling the current
624 input. This gives the engine limited access to the state
625 of the expander. Their arguments and results are
626 described in the documentation for the package expander.
627 ex_cappend
629 ex_cget
631 ex_cis
633 ex_cname
635 ex_cpop
637 ex_cpush
639 ex_cset
641 ex_lb
643 ex_rb
645 Other commands
647 The file "_common.tcl" contains default implementations
648 of fmt_plaint_text and all the fmt_ commands listed in
649 section EXPORTED COMMANDS. It resides in the subdirec‐
650 tory "mpformats" containing all the predefined formats.
651 This means that all external formats (i.e. not provided
652 by the package doctools) cannot use it immediately, but
653 have to have a copy at their location. Additional com‐
654 mands provided by this file are:
655 c_inpass
657 This command returns the id of the pass currently
658 executing.
659 c_begin
661 This command signals that processing of the text
662 after manpage_begin has begun.
663 c_begun
665 This command checks the flag set by c_begin.
666 c_set_module text
668 This command remembers text as module information.
669 c_get_module
671 This command retrieves the module information
672 stored by c_set_module.
673 c_set_title text
675 This command remembers text as title.
676 c_get_title
678 This command retrieves the title stored by
679 c_set_title.
680 c_provenance
682 This command returns a string describing how the
683 input was processed.
684 c_pass pass proc arguments body
686 This command defines a procedure which is valid
687 when pass pass of the engine is executed.
688 c_holdBuffers args
690 This command defines one or more buffers for hold‐
691 ing data between passes.
692 c_hold buffer entry
694 This command adds an entry to the specified buf‐
695 fer. The buffer has to be defined by an earlier
696 invocation of the command c_holdBuffers.
697 c_held buffer
699 This command retrieves the contents of the speci‐
700 fied buffer. The buffer is empty afterwards. All
701 entries in the buffer are joined by newlines.
702 c_cnext
704 This command increments the counter and return its
705 current value.
706 c_cinit
708 This command pushes the current counter on the
709 stack and reinitialize the counter to zero.
710 c_creset
712 This command reinitializes the counter with the
713 value on the counter stack and removes that value
714 from the stack.
715 NOP args
717 This command does nothing. It can be used in con‐
718 junction with c_pass to visibly declare in which
719 passes a formatting command has nothing to do.
720 NYI ?message?
722 This command throws the error "message Not yet
723 implemented".
724 c_sectionId name
726 This command remembers the name of the section for
727 later cross-referencing.
728 c_possibleReference text gi
730 This command checks if a section is available for
731 text. This command is currently tuned for use by
732 engines like HTML and TMML.
733
735 doctools, doctools_fmt
736
738 HTML, LaTeX, TMML, document, generic markup, manpage, markup, nroff
739
741 Copyright (c) 2002-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
742doctools 1.0 doctools_api(n)