docidx(n) Documentation tools docidx(n)
NAME
docidx - Create and manipulate docidx converter objects
SYNOPSIS
package require TTccll 88..22
package require ddooccttoooollss::::iiddxx ??11..00??
::::ddooccttoooollss::::iiddxx::::nneeww objectName ?option value...?
::::ddooccttoooollss::::iiddxx::::hheellpp
::::ddooccttoooollss::::iiddxx::::sseeaarrcchh path
oobbjjeeccttNNaammee option ?arg arg ...?
objectName ccoonnffiigguurree
objectName ccoonnffiigguurree option
objectName ccoonnffiigguurree option value...
objectName ccggeett option
objectName ddeessttrrooyy
objectName ffoorrmmaatt text
objectName sseeaarrcchh path
objectName wwaarrnniinnggss
DESCRIPTION
This package provides objects which can be used to convert text written
in the doctoc format as specified in ddoocciiddxxffmmtt into any output format
X, assuming that a formatting engine for X is available and provides
the interface specified in ddoocciiddxxaappii.
AAPPII
::::ddooccttoooollss::::iiddxx::::nneeww objectName ?option value...?
Creates a new docidx object with an associated global Tcl com-
mand whose name is objectName. This command is explained in full
detail in the sections OOBBJJEECCTT CCOOMMMMAANNDD and OOBBJJEECCTT MMEETTHHOODDSS.
The list of options and values coming after the name of the
object is used to set the initial configuration of the object.
::::ddooccttoooollss::::iiddxx::::hheellpp
This is a pure convenience command for applications which want
to provide their user with a reminder of the available format-
ting commands and their meanings. It returns a string containing
a standard help for this purpose.
::::ddooccttoooollss::::iiddxx::::sseeaarrcchh path
Whenever the package has to map the name of a format to the file
containing the code for its formatting engine it will search the
file in a number of directories. Three such directories are
declared by the package itself.
However the list is extensible by the user of the package and
the command above is the means to do so. When given a path to an
existing and readable directory it will prepend that directory
to the existing list. This means that the path added last is
searched through first.
An error will be thrown if the path either does not excist, is
not a directory, or is not readable.
OOBBJJEECCTT CCOOMMMMAANNDD
All commands created by ::::ddooccttoooollss::::iiddxx::::nneeww have the following general
form and may be used to invoke various operations on the object they
are associated with.
oobbjjeeccttNNaammee option ?arg arg ...?
The option and its args determine the exact behavior of the com-
mand. See section OOBBJJEECCTT MMEETTHHOODDSS for more explanations.
OOBBJJEECCTT MMEETTHHOODDSS
objectName ccoonnffiigguurree
When called without argument this method returns a list of all
known options and their current values.
objectName ccoonnffiigguurree option
When called with a single argument this method behaves like
ccggeett.
objectName ccoonnffiigguurree option value...
When called with more than one argument the method reconfigures
the object using the options and values given to it.
The legal configuration options are described in section OOBBJJEECCTT
CCOONNFFIIGGUURRAATTIIOONN.
objectName ccggeett option
This method expects a legal configuration option as argument and
returns the current value of that option for the object the
method was invoked for.
The legal configuration options are described in section OOBBJJEECCTT
CCOONNFFIIGGUURRAATTIIOONN.
objectName ddeessttrrooyy
Destroys the object it is invoked for.
objectName ffoorrmmaatt text
Takes the text and runs it through the configured formatting
engine. The resulting string is returned as the result of this
method. An error will be thrown if no -ffoorrmmaatt was configured for
the object.
The method assumes that the text is in docidx format as speci-
fied in ddttffoorrmmaatt((nn)). Errors will be thrown otherwise.
objectName sseeaarrcchh path
This method extends the per-object list of paths searched for
formatting engines. See also ::::ddooccttoooollss::::iiddxx::::sseeaarrcchh on how to
extend the global (per-package) list of paths.
The path entered last is searched through first.
objectName wwaarrnniinnggss
Returns a list containing all the warnings generated by the
engine during the last invocation of method ffoorrmmaatt.
OOBBJJEECCTT CCOONNFFIIGGUURRAATTIIOONN
All docidx objects understand the following configuration options:
-ffiillee file
The argument of this option is stored in the object and can be
retrieved by the formatting engine via the command ddttffiillee (see
ddttffoorrmmaatttteerr((nn))). Its default value is the empty string.
It will be interpreted as the name of the file containing the
text currently processed by the engine.
-mmoodduullee text
The argument of this option is stored in the object and can be
retrieved by the formatting engine via the command ddttmmoodduullee
(see ddttffoorrmmaatttteerr((nn))). Its default value is the empty string.
It will be interpreted as the name of the module the file con-
taining the text currently processed by the engine belongs to.
-ffoorrmmaatt text
The argument of this option specifies the format and thus the
engine to use when converting text via ffoorrmmaatt. Its default value
is the empty string. No formatting is possible if this option is
not set at least once.
The package will immediately try to map the name of the format
to a file containing the implementation of the engine for that
format. An error will be thrown if this mapping fails and a pre-
viously configured format is left untouched.
Section FFOORRMMAATT MMAAPPPPIINNGG explains how the package looks for engine
implementations.
-ddeepprreeccaatteedd boolean
This option is a flag. If set the object will generate warnings
when formatting a text containing the deprecated markup command
ssttrroonngg Its default value is FFAALLSSEE. In other words, no warnings
will be generated.
FFOORRMMAATT MMAAPPPPIINNGG
When trying to map a format name foo to the file containing the imple-
mentation of formatting engine for foo the package will perform the
following algorithm:
[1] If foo is the name of an existing file 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, that file is taken as the
implementation.
This list of paths is initially empty and can be extended
through the object method sseeaarrcchh.
[3] If not, the list of global (package) paths is searched. For each
directory in the list the package checks if that directory con-
tains a file "idx.foo". If yes, that file is taken as the imple-
mentation.
This list of paths contains initially one path and can be
extended through the command ::::ddooccttoooollss::::iiddxx::::sseeaarrcchh.
The initial (standard) path is the sub directory "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/doc-
tools/mpformats" for format implementations.
[4] The mapping fails.
EENNGGIINNEESS
The package comes with the following predefined formatting engines
html This engine generates HTML markup, for processing by web
browsers and the like.
latex This engine generates output suitable for the llaatteexx text proces-
sor 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 direc-
tory listing for a set of manpages.
nroff This engine generates nroff output, for processing by nnrrooffff, or
ggrrooffff. 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 wwiikkiitt application.
SEE ALSO
docidxapi, docidxfmt
KKEEYYWWOORRDDSS
HTML, TMML, conversion, documentation, index, manpage, markup, nroff,
table of contents, toc
COPYRIGHT Copyright (c) 2003 Andreas Kupries
doctools 1.0 docidx(n)