NAME¶
doctools::idx - docidx - Processing indices
SYNOPSIS¶
package require
Tcl 8.2
package require
doctools::idx ?1.0.4?
::doctools::idx::new objectName ?
-option value ...?
::doctools::idx::help
::doctools::idx::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
docidx 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
docidx language introduction and proceed from there to the formal
specifications, i.e. the
docidx language syntax and the
docidx
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
docidx 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::idx::new objectName ?-option value
...?
- This command creates a new docidx 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::idx::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::idx::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::idx::new have the following general
form and may be used to invoke various operations on their docidx 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 docidx format as
specified in the companion document docidx_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
docidx plugin API reference which specifies the interaction between
the objects created by this package and index 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 index
formatting engines. See also the command ::doctools::idx::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 docidx 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 command dt_file. This
command is described in more detail in the companion document
docidx_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.
- -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.
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
" idx.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 "
idx. foo". If yes, then that file is taken as the
implementation.
This list of paths can be extended through the command
::doctools::idx::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 "
docidx.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 formatting engines for the following formats.
Some of the formatting engines support engine parameters. These will be
explicitly highlighted.
- html
- This engine generates HTML markup, for processing by web browsers and the
like. This engine supports three 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.
- 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 Trackers [
http://core.tcl.tk/tcllib/reportlist]. Please also
report any ideas for enhancements you may have for either package and/or
documentation.
SEE ALSO¶
docidx_intro, docidx_lang_cmdref, docidx_lang_intro, docidx_lang_syntax,
docidx_plugin_apiref
KEYWORDS¶
HTML, TMML, conversion, docidx, documentation, index, keyword index, latex,
manpage, markup, nroff, wiki
CATEGORY¶
Documentation tools
COPYRIGHT¶
Copyright (c) 2003-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>