Provided by: tcllib_1.21+dfsg-1_all 
NAME
doctools - doctools - Processing documents
SYNOPSIS
package require Tcl 8.2
package require doctools ?1.5.6?
::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.
FORMAT MAPPING
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 occurrence 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.
markdown
This engine generates Markdown markup. This engine supports two parameters:
header The value for this parameter has to be valid selfcontained markdown markup
for the body section of a markdown document. The default value is the empty
string. The value is inserted into the generated output just before the
table of contents.
This can be used to insert boilerplate header markup into the generated
document.
xref The value for this parameter has to be a list of triples specifying cross-
reference information.
The full details of expected syntax and engine-internal use are explained
above for the html engine.
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 Trackers
[http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you
may have for either package and/or documentation.
When proposing code changes, please provide unified diffs, i.e the output of diff -u.
Note further that attachments are strongly preferred over inlined patches. Attachments can
be made by going to the Edit form of the ticket immediately after its creation, and then
using the left-most button in the secondary navigation bar.
SEE ALSO
doctools_intro, doctools_lang_cmdref, doctools_lang_intro, doctools_lang_syntax,
doctools_plugin_apiref
KEYWORDS
HTML, TMML, conversion, documentation, manpage, markdown, markup, nroff
CATEGORY
Documentation tools
COPYRIGHT
Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>