docidx(3tcl)
NAME
doctools::idx - docidx - Processing indices
SYNOPSIS
package require Tcl 8.2 package require doctools::idx ?1.0.5? ::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.
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 "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-2014 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
