NAME¶
doctools - doctools - Processing documents
SYNOPSIS¶
package require
Tcl 8.2
package require
doctools ?1.4.13?
::doctools::new objectName ?
option value...?
::doctools::help
::doctools::search path
objectName method ?
arg arg ...?
objectName configure
objectName configure option
objectName configure -option value...
objectName cget -option
objectName destroy
objectName format text
objectName map symbolic actual
objectName parameters
objectName search path
objectName setparam name value
objectName warnings
DESCRIPTION¶
This package provides a class for the creation of objects able to process and
convert text written in the
doctools markup language into any output
format X for which a
formatting engine is available.
A reader interested in the markup language itself should start with the
doctools language introduction and proceed from there to the formal
specifications, i.e. the
doctools language syntax and the
doctools
language command reference.
If on the other hand the reader wishes to write her own formatting engine for
some format, i.e. is a
plugin writer then reading and understanding the
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.
PUBLIC API¶
PACKAGE COMMANDS¶
- ::doctools::new objectName ?option
value...?
- This command creates a new doctools object with an
associated Tcl command whose name is objectName. This object
command is explained in full detail in the sections OBJECT COMMAND
and OBJECT METHODS. The object command will be created under the
current namespace if the objectName is not fully qualified, and in
the specified namespace otherwise.
The options and their values coming after the name of the object are used to
set the initial configuration of the object.
- ::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.
- ::doctools::search 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 FORMAT MAPPING for more explanations.
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 path to an existing and
readable directory it will prepend that directory to the list of
directories to search. This means that the path added last is later
searched through first.
An error will be thrown if the path either does not exist, is not a
directory, or is not readable.
OBJECT COMMAND¶
All commands created by
::doctools::new have the following general form
and may be used to invoke various operations on their doctools converter
object.
- objectName method ?arg arg ...?
- The method method and its arg'uments
determine the exact behavior of the command. See section OBJECT
METHODS for the detailed specifications.
OBJECT METHODS¶
- objectName configure
- The method returns a list of all known options and their
current values when called without any arguments.
- objectName configure option
- The method behaves like the method cget when called
with a single argument and returns the value of the option specified by
said argument.
- objectName configure -option
value...
- The method reconfigures the specified options of the
object, setting them to the associated values, when called with an
even number of arguments, at least two.
The legal options are described in the section OBJECT
CONFIGURATION.
- objectName cget -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.
The legal configuration options are described in section OBJECT
CONFIGURATION.
- objectName destroy
- This method destroys the object it is invoked for.
- objectName format text
- This method runs the text through the configured
formatting engine and returns the generated string as its result. An error
will be thrown if no -format was configured for the object.
The method assumes that the text is in doctools format as
specified in the companion document doctools_fmt. Errors will be
thrown otherwise.
- objectName map symbolic
actual
- This methods add one entry to the per-object mapping from
symbolic filenames to the actual uris. The object just
stores this mapping and makes it available to the configured formatting
engine through the command dt_fmap. This command is described in
more detail in the doctools plugin API reference which specifies
the interaction between the objects created by this package and doctools
formatting engines.
- objectName 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.
- objectName search path
- This method extends the per-object list of paths searched
for doctools formatting engines. See also the command
::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 FORMAT MAPPING.
- objectName setparam name
value
- This method sets the named engine parameter to the
specified 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 name.
The list of parameters provided by the configured formatting engine can be
retrieved through the method parameters.
- objectName 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 format.
OBJECT CONFIGURATION¶
All doctools objects understand the following configuration options:
- -file file
- The argument of this option is stored in the object and
made available to the configured formatting engine through the commands
dt_file and dt_mainfile. These commands are described in
more detail in the companion document doctools_api which specifies
the API between the object and formatting engines.
The default value of this option is the empty string.
The configured formatting engine should interpret the value as the name of
the file containing the document which is currently processed.
- -ibase 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 -file is used
instead.
Note that -file and -ibase, while similar looking, are
actually very different. The value of -file is used by some engines
for the generation of proper relative references between output documents
(HTML). As such this is a destination path. The -ibase on
the other hand is used to resolve relative include paths, and as such
deals with source paths.
The default value of this option is the empty string.
- -module text
- The argument of this option is stored in the object and
made available to the configured formatting engine through the command
dt_module. This command is described in more detail in the
companion document doctools_api which specifies the API between the
object and formatting engines.
The default value of this option is the empty string.
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.
- -format 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 format. Its default value is the empty string.
The method format cannot be used if this option is not set to a
valid value at least once.
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.
The section FORMAT MAPPING explains in detail how the package and
object will look for engine implementations.
- -deprecated boolean
- This option is a boolean flag. The object will generate
warnings if this flag is set and the text given to method format
contains the deprecated markup command strong. Its default value is
FALSE. In other words, no warnings will be generated.
- -copyright text
- The argument of this option is stored in the object and
made available to the configured formatting engine through the command
dt_copyright. This command is described in more detail in the
companion document doctools_api which specifies the API between the
object and formatting engines.
The default value of this option is the empty string.
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.
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 copyright. This command is described in
more detail in the companion document doctools_fmt which specifies
the doctools format itself.
The package and object will perform the following algorithm when trying to map a
format name
foo to a file containing an implementation of a formatting
engine for
foo:
- [1]
- If foo is the name of an existing file then this
file is directly taken as the implementation.
- [2]
- 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 " fmt.foo". If yes, then that file
is taken as the implementation.
Note that this list of paths is initially empty and can be extended through
the object method search.
- [3]
- If not, the list of package paths is searched. For each
directory in the list the package checks if that directory contains a file
" fmt.foo". If yes, then that file is taken as the
implementation.
This list of paths can be extended through the command
::doctools::search. It contains initially one path, the
subdirectory " mpformats" of the directory the package
itself is located in. In other words, if the package implementation "
doctools.tcl" is installed in the directory "
/usr/local/lib/tcllib/doctools" then it will by default search
the directory " /usr/local/lib/tcllib/doctools/mpformats"
for format implementations.
- [4]
- The mapping fails.
PREDEFINED ENGINES¶
The package provides predefined engines for the following formats. Some of the
engines support parameters. These will be explained below as well.
- html
- This engine generates HTML markup, for processing by web
browsers and the like. This engine supports four parameters:
- 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 </body> tag, closing the body of the generated
HTML.
This can be used to insert boilerplate footer markup into the generated
document.
- 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 <body> tag, starting the body of the generated
HTML.
This can be used to insert boilerplate header markup into the generated
document.
- 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 <head> tag, starting the header section of the
generated HTML.
This can be used to insert boilerplate meta data markup into the generated
document, like references to a stylesheet, standard meta keywords,
etc.
- 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.
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 file#fragment listed in the relevant triple, after
conversion of the symbolic file name to the actual uri via dt_fmap
(see the doctools plugin API reference). This file-to-uri mapping
was build by calls to the method map of the doctools object (See
section OBJECT METHODS).
The following formatting commands will consult the xref database:
- cmd word
- The command will look for the patterns
sa,word, and word, in this order. If this fails if it
will convert word to all lowercase and try again.
- syscmd word
- The command will look for the patterns
sa,word, and word, in this order. If this fails if it
will convert word to all lowercase and try again.
- term word
- The command will look for the patterns
kw,word, sa,word, and word, in this
order. If this fails if it will convert word to all lowercase and
try again.
- package word
- The command will look for the patterns
sa,word, kw,word, and word, in this
order. If this fails if it will convert word to all lowercase and
try again.
- see_also word...
- The command will look for the patterns
sa,word, and word, in this order, for each
word given to the command. If this fails if it will convert
word to all lowercase and try again.
- keywords word...
- The command will look for the patterns
kw,word, and word, in this order, for each
word given to the command. If this fails if it will convert
word to all lowercase and try again.
- latex
- This engine generates output suitable for the latex
text processor coming out of the TeX world.
- 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.
- nroff
- This engine generates nroff output, for processing by
nroff, or groff. The result will be standard man pages as
they are known in the unix world.
- null
- This engine generates no outout at all. This can be used if
one just wants to validate some input.
- tmml
- This engine generates TMML markup as specified by Joe
English. The Tcl Manpage Markup Language is a derivate of XML.
- wiki
- This engine generates Wiki markup as understood by Jean
Claude Wippler's wikit application.
BUGS, IDEAS, FEEDBACK¶
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category
doctools of the
Tcllib SF Trackers [
http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either package
and/or documentation.
SEE ALSO¶
doctools_intro, doctools_lang_cmdref, doctools_lang_intro, doctools_lang_syntax,
doctools_plugin_apiref
KEYWORDS¶
HTML, TMML, conversion, documentation, manpage, markup, nroff
CATEGORY¶
Documentation tools
COPYRIGHT¶
Copyright (c) 2003-2011 Andreas Kupries <andreas_kupries@users.sourceforge.net>