PACKAGECOMMANDS::doctools::idx::newobjectName ?-optionvalue ...?
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 OBJECTCOMMAND and OBJECTMETHODS.
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::searchpath
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 FORMATMAPPING 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.
OBJECTCOMMAND
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.
objectNamemethod ?argarg...?
The method method and its arg'uments determine the exact behavior of the command. See section
OBJECTMETHODS for the detailed specifications.
OBJECTMETHODSobjectNameconfigure
The method returns a list of all known options and their current values when called without any
arguments.
objectNameconfigureoption
The method behaves like the method cget when called with a single argument and returns the value
of the option specified by said argument.
objectNameconfigure-optionvalue...
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 OBJECTCONFIGURATION.
objectNamecget-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 OBJECTCONFIGURATION.
objectNamedestroy
This method destroys the object it is invoked for.
objectNameformattext
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.
objectNamemapsymbolicactual
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 docidxpluginAPIreference which specifies the interaction between the objects created by this package and index
formatting engines.
objectNameparameters
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.
objectNamesearchpath
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 FORMATMAPPING.
objectNamesetparamnamevalue
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.
objectNamewarnings
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.
OBJECTCONFIGURATION
All docidx objects understand the following configuration options:
-filefile
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.
-formattext
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 FORMATMAPPING explains in detail how the package and object will look for engine
implementations.
FORMATMAPPING
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.
Install Now
Emojis
PNG Icons