NAME
doctools_api - Specification of the Interface to Doctools Formatting Engines
SYNOPSIS
fmt_numpasses
fmt_initialize
fmt_setup n
fmt_postprocess text
fmt_shutdown
fmt_listvariables
fmt_varset varname text
fmt_plain_text text
fmt_comment text
fmt_manpage_begin command section version
fmt_manpage_end
fmt_moddesc desc
fmt_titledesc desc
fmt_copyright text
fmt_description
fmt_require pkg ?version?
fmt_section name
fmt_subsection name
fmt_para
fmt_see_also args
fmt_keywords args
fmt_arg text
fmt_cmd text
fmt_opt text
fmt_emph text
fmt_strong text
fmt_sectref text ?label?
fmt_syscmd text
fmt_method text
fmt_namespace text
fmt_option text
fmt_widget text
fmt_fun text
fmt_type text
fmt_package text
fmt_class text
fmt_var text
fmt_file text
fmt_uri text ?text?
fmt_term text
fmt_const text
fmt_nl
fmt_example_begin
fmt_example_end
fmt_list_begin what
fmt_list_end
fmt_bullet
fmt_enum
fmt_lst_item text
fmt_call args
fmt_arg_def type name ?mode?
fmt_opt_def name ?arg?
fmt_cmd_def command
fmt_tkoption_def name dbname dbclass
fmt_usage args
dt_copyright
dt_file
dt_fileid
dt_fmap symfname
dt_format
dt_lnesting
dt_module
dt_source file
dt_user
ex_cappend
ex_cget
ex_cis
ex_cname
ex_cpop
ex_cpush
ex_cset
ex_lb
ex_rb
c_inpass
c_begin
c_begun
c_set_module text
c_get_module
c_set_title text
c_get_title
c_provenance
c_pass pass proc arguments body
c_holdBuffers args
c_hold buffer entry
c_held buffer
c_cnext
c_cinit
c_creset
NOP args
NYI ?message?
c_sectionId name
c_possibleReference text gi
DESCRIPTION
This document specifies version 1 of the interface a doctools formatting engine has to comply with to be usable by the package doctools. The specification of the doctools format all doctools formatting engines have to process can be found in the companion document doctools_fmt.
API
EXPORTED COMMANDS
Each doctools formatting engine has to provide a number of commands through which objects created by the package doctools will upon the functionality of the engine. These commands are described here.
- Management commands
-
- fmt_numpasses
-
This command is called by a doctools object immediately after it has loaded the engine. No other command of the engine will be called before it. It has to return the number of passes this engine requires to fully process the input document. This value has to be an integer number greater or equal to one.
- fmt_initialize
-
This command is called at the beginning of every conversion run, as the first command of that run. Note that a run is not a pass, but may consist of multiple passes. See fmt_numpasses. The command has to initialize the general state of the doctools formatting engine, beyond the initialization done during the load.
- fmt_setup n
-
This command is called at the beginning of each pass over the input in a run. Its argument is the number of the pass which has begun. Passes are counted from 1 upward. The command has to set up the internal state of the doctools formatting engine for this particular pass.
- fmt_postprocess text
-
This command is called immediately after the last pass in a run. Its argument is the result of the conversion generated by that pass. It is provided to allow the engine to perform any global last-ditch modifications of the generated document. The text returned by this command will be the final result of the conversion.
An engine for a format which requires no postprocessing can simply return the argument without change.
- fmt_shutdown
-
This command is called at the end of every conversion run. It is the last command called in a run. It has to clean up of all the run-specific state in the doctools formatting engine. After the call the engine has to be in a state which allows the initiation of another run without fear that information from the last run is leaked into this new run.
- fmt_listvariables
-
This command is called by a doctools object after it has loaded the engine (after fmt_numpasses). It has to return a list containing the names of the engine parameters provided by the engine. This list can be empty.
- fmt_varset varname text
-
This command is called whenever the doctools object wishes to set an engine parameter to a particular value. The parameter to change is specified by varname, the value to set in text.
The command has to throw an error if an unknown varname is used. Only the names returned by fmt_listvariables are considered known.
The values of all engine parameters have to persist between passes and runs.
- Formatting commands
-
The commands listed in this section are responsible for the conversion of the input into the wanted output. Their names are the names of the associated markup command, with prefix fmt_ added to them. Not all markup commands have associated formatting commands. The two exceptions are vset and include. These markup commands are processed by the doctools object itself.
A detailed documentation of the markup commands can be found in the companion document doctools_fmt. It is the formal specification of the doctools format.
Note: The formatting commands can expect that they are only called in an order allowed by the format specification.
- fmt_plain_text text
-
This command has no associated markup command. It is called for any plain text encountered by the processor in the input. It has to perform any special processing required for plain text. The text returned as its result is added to the output. If no special processing is required it has to simply return its argument without change.
- fmt_comment text
-
This command has to format the text as a comment and return the formatted string. It has to return the empty string if the output format has no way of formatting comments.
- fmt_manpage_begin command section version
-
This command has to format the command name, the section the manpage resides in, and the version of the module as the start of the generated manpage and return the formatted string.
- fmt_manpage_end
-
This command has to generate the end of the generated manpage and return the formatted string.
- fmt_moddesc desc
-
This command remembers its argument desc as a short description of the module the manpage resides in. It may or may not return a formatted string.
- fmt_titledesc desc
-
This command remembers its argument desc as the title of the manpage. It may or may not return a formatted string. If this command was omitted the argument of moddesc has to be be used for the title as well.
- fmt_copyright text
-
This command remembers its argument text as declaration of a copyright assignment for the manpage. When invoked more than once the assignments have to be accumulated. It may or may not return a formatted string.
Assignments provided by this command have priority over information supplied by an doctools processing application.
- fmt_description
-
This command separates the header part of the manpage from the main body. It may or may not return a formatted string.
- fmt_require pkg ?version?
-
This command remembers its arguments as name and version of a package which is required by an application or other library to use the described package. It may or may not return a formatted string.
- fmt_section name
-
This command partitions the body of the manpage into named sections. Note that the command description at the beginning of the manpage body implicitly started a section named "DESCRIPTION". A section command has to close the last paragraph coming before it and also open the first paragraph of the new section. It may or may not return a formatted string.
- fmt_subsection name
-
This command partitions the body of a section into named sub-sections. A subsection command has to close the last paragraph coming before it and also opens the first paragraph of the new section. It may or may not return a formatted string.
- fmt_para
-
This command partitions the text in a section or sub-section into paragraphs. Each invokation has to close the paragraph coming before it and open a new paragraph for the text coming after. It may or may not return a formatted string.
- fmt_see_also args
-
This command defines direct cross-references to other documents. Each argument is a label identifying the referenced document. If this command is used multiple times all the arguments have to accumulate. It may or may not return a formatted string.
- fmt_keywords args
-
This command defines the keywords applying to this document. Each argument is a single keyword. If this command is used multiple times all the arguments have to accumulate. It may or may not return a formatted string.
- fmt_arg text
-
This command declares that the argument text is the name of a command argument. It has to return a formatted string.
- fmt_cmd text
-
This command declares that the argument text is the name of a command. It has to return a formatted string.
- fmt_opt text
-
This command declares that the argument text is something optional. It has to return a formatted string.
- fmt_emph text
-
This command emphasizes the text. It has to return a formatted string.
- fmt_strong text
-
This command emphasizes the text. Same as emph. Usage of this command is discouraged. The command is deprecated and present only for backward compatibility. It has to return a formatted string.
- fmt_sectref text ?label?
-
This command declares that the argument text is the name of a section somewhere else in the document, and the current location should refer to it. It has to return a formatted string. If a label is specified then it has to be used in the returned text. Otherwise the section title text is used.
- fmt_syscmd text
-
This command declares that the argument text is the name of a system command. It has to return a formatted string.
- fmt_method text
-
This command declares that the argument text is the name of an object method. It has to return a formatted string.
- fmt_namespace text
-
This command declares that the argument text is the name of a namespace. It has to return a formatted string.
- fmt_option text
-
This command declares that the argument text is the name of an option. It has to return a formatted string.
- fmt_widget text
-
This command declares that the argument text is the name of a widget. It has to return a formatted string.
- fmt_fun text
-
This command declares that the argument text is the name of a function. It has to return a formatted string.
- fmt_type text
-
This command declares that the argument text is the name of a data type. It has to return a formatted string.
- fmt_package text
-
This command declares that the argument text is the name of a package. It has to return a formatted string.
- fmt_class text
-
This command declares that the argument text is the name of a class. It has to return a formatted string.
- fmt_var text
-
This command declares that the argument text is the name of a variable. It has to return a formatted string.
- fmt_file text
-
This command declares that the argument text is a file. It has to return a formatted string.
- fmt_uri text ?text?
-
This command declares that the argument text is an uri. The second argument, if it is present, is the human-readable description of the uri. In other words, the label for the link. Without a labeling text the uri is used as its own label. It has to return a formatted string.
- fmt_term text
-
This command declares that the argument text contains some unspecific terminology. It has to return a formatted string.
- fmt_const text
-
This command declares that the argument text is a constant value. It has to return a formatted string.
- fmt_nl
-
This command signals vertical space to separate blocks of text. It may or may not return a formatted string.
- fmt_example_begin
-
This command begins an example block. Subsequent text belongs to the example. Line breaks, spaces, and tabs have to be preserved literally. It may or may not return a formatted string.
- fmt_example_end
-
This command closes the example block. It may or may not return a formatted string.
- fmt_list_begin what
-
This command starts new list. The value of the argument what determines what type of list is opened. This also defines what command has to be used to start an item in the new list. The allowed types (and their associated item commands) are explained in the format specification, i.e. doctools_fmt. It may or may not return a formatted string.
- fmt_list_end
-
This command ends the list opened by the last list_begin. It may or may not return a formatted string.
- fmt_bullet
-
This command starts a new list item in a bulletted list. The previous item has to be closed automatically. It may or may not return a formatted string.
- fmt_enum
-
This command starts a new list item in an enumerated list. The previous item has to be closed automatically. It may or may not return a formatted string.
- fmt_lst_item text
-
This command starts a new list item in a definition list. The argument is the term to be defined. The previous item has to be closed automatically. It may or may not return a formatted string.
- fmt_call args
-
This command starts a new list item in a definition list, but the term defined by it is a command and its arguments. The previous item is automatically closed. The first argument is the name of the described command, and everything after that are descriptions of the command arguments. It may or may not return a formatted string.
- fmt_arg_def type name ?mode?
-
This command starts a new list item in an argument list. The previous item has to be closed automatically. Specifies the data-type of the described argument, its name and its i/o-mode. The latter is optional. It may or may not return a formatted string.
- fmt_opt_def name ?arg?
-
This command starts a new list item in an option list. The previous item has to be closed automatically. Specifies the name of the option and its arguments (arg). The latter is a list, and can be left out. It may or may not return a formatted string.
- fmt_cmd_def command
-
This command starts a new list item in a command list. The previous item has to be closed automatically. Specifies the name of the command. It may or may not return a formatted string.
- fmt_tkoption_def name dbname dbclass
-
This command starts a new list item in a widget option list. The previous item has to be closed automatically. Specifies the name of the option, i.e. the name used in scripts, the name used by the option database (dbname), and the class (type) of the option (dbclass). It may or may not return a formatted string.
- fmt_usage args
-
This command is like call, except that a formatting engine must not generate output at the location of the command. In other words, this command is silent. The data it defines may appear in a different section of the output, for example a table of contents, or synopsis, depending on the formatting engine and its output format. It may or may not return a formatted string.
IMPORTED ENVIRONMENT
The implementation of a doctools formatting engine can make the following assumptions about the environment it is executed in:
- [1]
-
That it has full access to its own safe interpreter. In other words, the engine cannot damage the other parts of the processor, nor can it damage the filesystem.
- [2]
-
That the following commands are provided by the doctools object controlling the engine:
- Doctools commands
-
- dt_copyright
-
This command returns a string containing the copyright information the doctools object was configured with (option -copyright).
- dt_file
-
This command returns the full name of the file currently processed by the engine.
- dt_fileid
-
This command returns the name of the file currently processed by the engine, without path, nor extension.
- dt_fmap symfname
-
This command returns the actual name to use in the output in place of the symbolic filename symfname. It will return the unchanged input if no mapping was found for symfname.
- dt_format
-
This command returns the name of the format currently executing.
- dt_lnesting
-
This command returns the number of lists currently open.
- dt_module
-
This command returns the name of the module the file currently processed belongs to.
- dt_source file
-
This command allows the doctools formatting engine to load additional tcl code. Only files which are either in the same directory as the file containing the engine, or below it, can be loaded. Trying to load a file outside of this directory causes an error.
- dt_user
-
This command returns the name of the current user as known to the tcl interpreter the doctools object controlling the engine resides in.
- Expander commands
-
All of the commands below are methods of the expander object (without the prefix ex_) handling the current input. This gives the engine limited access to the state of the expander. Their arguments and results are described in the documentation for the package expander.
- ex_cappend
- ex_cget
- ex_cis
- ex_cname
- ex_cpop
- ex_cpush
- ex_cset
- ex_lb
- ex_rb
- Other commands
-
The file "_common.tcl" contains default implementations of fmt_plaint_text and all the fmt_ commands listed in section EXPORTED COMMANDS. It resides in the subdirectory "mpformats" containing all the predefined formats. This means that all external formats (i.e. not provided by the package doctools) cannot use it immediately, but have to have a copy at their location. Additional commands provided by this file are:
- c_inpass
-
This command returns the id of the pass currently executing.
- c_begin
-
This command signals that processing of the text after manpage_begin has begun.
- c_begun
-
This command checks the flag set by c_begin.
- c_set_module text
-
This command remembers text as module information.
- c_get_module
-
This command retrieves the module information stored by c_set_module.
- c_set_title text
-
This command remembers text as title.
- c_get_title
-
This command retrieves the title stored by c_set_title.
- c_provenance
-
This command returns a string describing how the input was processed.
- c_pass pass proc arguments body
-
This command defines a procedure which is valid when pass pass of the engine is executed.
- c_holdBuffers args
-
This command defines one or more buffers for holding data between passes.
- c_hold buffer entry
-
This command adds an entry to the specified buffer. The buffer has to be defined by an earlier invocation of the command c_holdBuffers.
- c_held buffer
-
This command retrieves the contents of the specified buffer. The buffer is empty afterwards. All entries in the buffer are joined by newlines.
- c_cnext
-
This command increments the counter and return its current value.
- c_cinit
-
This command pushes the current counter on the stack and reinitialize the counter to zero.
- c_creset
-
This command reinitializes the counter with the value on the counter stack and removes that value from the stack.
- NOP args
-
This command does nothing. It can be used in conjunction with c_pass to visibly declare in which passes a formatting command has nothing to do.
- NYI ?message?
-
This command throws the error "message Not yet implemented".
- c_sectionId name
-
This command remembers the name of the section for later cross-referencing.
- c_possibleReference text gi
-
This command checks if a section is available for text. This command is currently tuned for use by engines like HTML and TMML.
SEE ALSO
doctools, doctools_fmt
KEYWORDS
HTML, LaTeX, TMML, document, generic markup, manpage, markup, nroff
COPYRIGHT
Copyright (c) 2002-2004 Andreas Kupries <[email protected]>