


doctools::idx(n)       Documentation tools       doctools::idx(n)


______________________________________________________________________________

NAME
       doctools::idx - docidx - Processing indices

SYNOPSIS
       package require Tcl  8.2

       package require doctools::idx  ?1.0.2?

       ::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 pro-
       cess 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 spec-
       ifications,  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



doctools                      1.0.2                             1





doctools::idx(n)       Documentation tools       doctools::idx(n)


       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  pro-
              vide  their  user with a short description of the available for-
              matting commands and their meanings. It returns  a  string  con-
              taining 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 format-
              ting  engine it will search for the file in a number of directo-
              ries 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  con-
       verter object.

       objectName method ?arg arg ...?
              The  method method and its arg'uments determine the exact behav-
              ior of the command. See section OBJECT METHODS for the  detailed
              specifications.


   OBJECT METHODS




doctools                      1.0.2                             2





doctools::idx(n)       Documentation tools       doctools::idx(n)


       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  sin-
              gle  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 CONFIGURA-
              TION.

       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  speci-
              fied 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  sym-
              bolic 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  speci-
              fies 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



doctools                      1.0.2                             3





doctools::idx(n)       Documentation tools       doctools::idx(n)


              index  formatting  engines.  See   also   the   command   ::doc-
              tools::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  parame-
              ters.

       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  com-
              mand  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 for-
              mat. 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



doctools                      1.0.2                             4





doctools::idx(n)       Documentation tools       doctools::idx(n)


       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  direc-
              tory in the list the package checks if that directory contains a
              file "idx.foo". If yes, then that file is taken as the implemen-
              tation.

              This  list  of  paths can be extended through the command ::doc-
              tools::idx::search.  It contains initially one path, the  subdi-
              rectory  "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 selfcon-
                     tained HTML markup for the body section of a  HTML  docu-
                     ment. 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  selfcon-
                     tained  HTML  markup for the body section of a HTML docu-
                     ment. 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.




doctools                      1.0.2                             5





doctools::idx(n)       Documentation tools       doctools::idx(n)


                     This can be used to insert boilerplate header markup into
                     the generated document.

              meta   The  value  for  this  parameter has to be valid selfcon-
                     tained HTML markup for the header section of a HTML docu-
                     ment. 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 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 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       SF       Trackers       [http://source-
       forge.net/tracker/?group_id=12883].  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_syn-
       tax, docidx_plugin_apiref

KEYWORDS
       HTML, TMML, conversion, docidx, documentation,  index,  keyword  index,
       latex, manpage, markup, nroff, wiki

CATEGORY
       Documentation tools





doctools                      1.0.2                             6





doctools::idx(n)       Documentation tools       doctools::idx(n)


COPYRIGHT
       Copyright (c) 2003-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>























































doctools                      1.0.2                             7


