|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
doctools_api(n) 1.0 "Documentation tools"
doctools_api - Specification of the Interface to Doctools
Formatting Engines
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
API
EXPORTED COMMANDS
IMPORTED ENVIRONMENT
SEE ALSO
KEYWORDS
COPYRIGHT
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
.
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.
The implementation of a doctools formatting engine can make the
following assumptions about the environment it is executed in:
- 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.
- 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.
doctools , doctools_fmt
HTML , LaTeX , TMML , document , generic markup , manpage , markup , nroff
Copyright © 2002-2004 Andreas Kupries
<andreas_kupries@users.sourceforge.net>