Provided by: tcllib_1.19-dfsg-2_all bug

NAME

       doctools::idx - docidx - Processing indices

SYNOPSIS

       package require Tcl  8.2

       package require doctools::idx  ?1.0.7?

       ::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.

       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

       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-2017 Andreas Kupries <andreas_kupries@users.sourceforge.net>