idx_container(3)



doctools::idx(3tcl)           Documentation tools          doctools::idx(3tcl)

______________________________________________________________________________

NAME
       doctools::idx - Holding keyword indices

SYNOPSIS
       package require doctools::idx  ?2?

       package require Tcl  8.4

       package require doctools::idx::structure

       package require snit

       ::doctools::idx objectName

       objectName method ?arg arg ...?

       objectName destroy

       objectName key add name

       objectName key remove name

       objectName key references name

       objectName keys

       objectName reference add type key name label

       objectName reference remove name

       objectName reference label name

       objectName reference keys name

       objectName reference type name

       objectName references

       objectName title

       objectName title text

       objectName label

       objectName label text

       objectName importer

       objectName importer object

       objectName exporter

       objectName exporter object

       objectName deserialize = data ?format?

       objectName deserialize += data ?format?

       objectName serialize ?format?

______________________________________________________________________________

DESCRIPTION
       This  package  provides a class to contain and programmatically manipu-
       late keyword indices

       This is one of the three public pillars the management of  keyword  in-
       dices resides on. The other two pillars are

       [1]    Exporting keyword indices, and

       [2]    Importing keyword indices

       For information about the Concepts of keyword indices, and their parts,
       see the same-named section.  For information about the  data  structure
       which  is used to encode keyword indices as values see the section Key-
       word index serialization format.  This  is  the  only  format  directly
       known  to this class. Conversions from and to any other format are han-
       dled by export and import manager objects. These may be attached  to  a
       container, but do not have to be, it is merely a convenience.

CONCEPTS
       [1]    A keyword index consists of a (possibly empty) set of keywords.

       [2]    Each keyword in the set is identified by its name.

       [3]    Each keyword has a (possibly empty) set of references.

       [4]    A reference can be associated with more than one keyword.

       [5]    A reference not associated with at least one keyword is not pos-
              sible however.

       [6]    Each reference is identified by its target, specified as  either
              an  url or symbolic filename, depending on the type of reference
              (url, or manpage).

       [7]    The type of a reference (url, or manpage) depends  only  on  the
              reference itself, and not the keywords it is associated with.

       [8]    In  addition to a type each reference has a descriptive label as
              well. This label depends only on the reference itself,  and  not
              the keywords it is associated with.

       A few notes

       [1]    Manpage references are intended to be used for references to the
              documents the index is made for. Their target is a symbolic file
              name  identifying  the  document, and export plugins may replace
              symbolic with actual file names, if specified.

       [2]    Url references are intended on the othre hand are inteded to  be
              used  for links to anything else, like websites. Their target is
              an url.

       [3]    While url and manpage references share  a  namespace  for  their
              identifiers, this should be no problem, given that manpage iden-
              tifiers are symbolic filenames and as  such  they  should  never
              look like urls, the identifiers for url references.

API
   PACKAGE COMMANDS
       ::doctools::idx objectName
              This  command  creates a new container object with an associated
              Tcl command whose name is objectName. This object command is ex-
              plained 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.

   OBJECT COMMAND
       All objects created by the ::doctools::idx command have  the  following
       general form:

       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
       objectName destroy
              This method destroys the object it is invoked for.

       objectName key add name
              This  method  adds the keyword name to the index. If the keyword
              is already known nothing is done. The result of  the  method  is
              the empty string.

       objectName key remove name
              This method removes the keyword name from the index. If the key-
              word is already gone nothing is done. Any  references  for  whom
              this  keyword was the last association are removed as well.  The
              result of the method is the empty string.

       objectName key references name
              This method returns a list containing the names  of  all  refer-
              ences  associated  with  the keyword name. An error is thrown in
              the keyword is not known to the index. The order of  the  refer-
              ences in the list is undefined.

       objectName keys
              This  method returns a list containing the names of all keywords
              known to the index. The order of the keywords in the list is un-
              defined.

       objectName reference add type key name label
              This  method adds the reference name to the index and associates
              it with the keyword key.  The other two arguments hold the  type
              and label of the reference, respectively.  The type has to match
              the stored information, should the reference exist already, i.e.
              this  information is immutable after the reference is known. The
              only way to change it is delete and recreate the reference.  The
              label on the other hand is automatically updated to the value of
              the argument, overwriting  any  previously  stored  information.
              Should the reference exists already it is simply associated with
              the key.  If that is true already as well nothing is  done,  but
              the label updated to the new value.  The result of the method is
              the empty string.

              The type argument has be to one of manpage or url.

       objectName reference remove name
              The reference name is removed from the index.  All  associations
              with keywords are released and the relevant reference labels re-
              moved.  The result of the method is the empty string.

       objectName reference label name
              This method returns the  label  associated  with  the  reference
              name. An error is thrown if the reference is not known.

       objectName reference keys name
              This  method returns a list containing the names of all keywords
              associated with the reference name. An error is  thrown  in  the
              reference  is  not known to the index. The order of the keywords
              in the list is undefined.

       objectName reference type name
              This method returns the type of the reference name. An error  is
              thrown in the reference is not known to the index.

       objectName references
              This  method  returns  a list containing the names of all refer-
              ences known to the index. The order of  the  references  in  the
              list is undefined.

       objectName title
              Returns the currently defined title of the keyword index.

       objectName title text
              Sets  the  title of the keyword index to text, and returns it as
              the result of the command.

       objectName label
              Returns the currently defined label of the keyword index.

       objectName label text
              Sets the label of the keyword index to text, and returns  it  as
              the result of the command.

       objectName importer
              Returns the import manager object currently attached to the con-
              tainer, if any.

       objectName importer object
              Attaches the object as import manager to the container, and  re-
              turns  it as the result of the command.  Note that the object is
              not put into ownership of the container.  I.e.,  destruction  of
              the container will not destroy the object.

              It  is  expected that object provides a method named import text
              which takes a text and a format name, and returns the  canonical
              serialization of the keyword index contained in the text, assum-
              ing the given format.

       objectName exporter
              Returns the export manager object currently attached to the con-
              tainer, if any.

       objectName exporter object
              Attaches  the object as export manager to the container, and re-
              turns it as the result of the command.  Note that the object  is
              not  put  into  ownership of the container. I.e., destruction of
              the container will not destroy the object.

              It is expected that object provides a method named export object
              which  takes the container and a format name, and returns a text
              encoding keyword index stored in the  container,  in  the  given
              format. It is further expected that the object will use the con-
              tainer's method serialize to obtain  the  serialization  of  the
              keyword index from which to generate the text.

       objectName deserialize = data ?format?
              This  method  replaces the contents of the index object with the
              index contained in the data. If no format was  specified  it  is
              assumed to be the regular serialization of a keyword index.

              Otherwise  the  object  will  use the attached import manager to
              convert the data from the specified format to a serialization it
              can  handle.   In  that case an error will be thrown if the con-
              tainer has no import manager attached to it.

              The result of the method is the empty string.

       objectName deserialize += data ?format?
              This method behaves like deserialize = in its essentials, except
              that it merges the keyword index in the data to its contents in-
              stead of replacing it.  The method will throw an error if  merg-
              ing  is  not  possible, i.e. would produce an invalid index. The
              existing content is left unchanged in that case.

              The result of the method is the empty string.

       objectName serialize ?format?
              This method returns the keyword index contained in  the  object.
              If no format is not specified the returned result is the canoni-
              cal serialization of its contents.

              Otherwise the object will use the  attached  export  manager  to
              convert the data to the specified format.  In that case an error
              will be thrown if the container has no export  manager  attached
              to it.

KEYWORD INDEX SERIALIZATION FORMAT
       Here  we specify the format used by the doctools v2 packages to serial-
       ize keyword indices as immutable values for transport, comparison, etc.

       We distinguish between regular and canonical  serializations.  While  a
       keyword index may have more than one regular serialization only exactly
       one of them will be canonical.

       regular serialization

              [1]    An index serialization is a nested Tcl dictionary.

              [2]    This dictionary holds a single  key,  doctools::idx,  and
                     its value. This value holds the contents of the index.

              [3]    The  contents  of  the index are a Tcl dictionary holding
                     the title of the index, a label,  and  the  keywords  and
                     references. The relevant keys and their values are

                     title  The  value is a string containing the title of the
                            index.

                     label  The value is a string containing a label  for  the
                            index.

                     keywords
                            The  value is a Tcl dictionary, using the keywords
                            known to the index as keys. The associated  values
                            are lists containing the identifiers of the refer-
                            ences associated with that particular keyword.

                            Any reference identifier used in these  lists  has
                            to  exist  as  a key in the references dictionary,
                            see the next item for its definition.

                     references
                            The value is a Tcl dictionary, using  the  identi-
                            fiers  for  the  references  known to the index as
                            keys. The associated values  are  2-element  lists
                            containing the type and label of the reference, in
                            this order.

                            Any key here has to be associated  with  at  least
                            one  keyword,  i.e.  occur  in at least one of the
                            reference lists which are the values in  the  key-
                            words  dictionary, see previous item for its defi-
                            nition.

              [4]    The type of a reference can be one of two values,

                     manpage
                            The identifier of the reference is interpreted  as
                            symbolic  file name, referring to one of the docu-
                            ments the index was made for.

                     url    The identifier of the reference is interpreted  as
                            an  url, referring to some external location, like
                            a website, etc.

       canonical serialization
              The canonical serialization of a keyword index has the format as
              specified  in the previous item, and then additionally satisfies
              the constraints below, which make it unique among all the possi-
              ble serializations of the keyword index.

              [1]    The  keys  found  in  all the nested Tcl dictionaries are
                     sorted in ascending dictionary  order,  as  generated  by
                     Tcl's builtin command lsort -increasing -dict.

              [2]    The  references  listed for each keyword of the index, if
                     any, are listed in ascending dictionary  order  of  their
                     labels,  as generated by Tcl's builtin command lsort -in-
                     creasing -dict.

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 out-
       put 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.

KEYWORDS
       HTML, TMML, conversion, docidx markup, documentation, formatting,  gen-
       eration,  index,  json,  keyword  index, latex, manpage, markup, nroff,
       parsing, plugin, reference, tcler's wiki, text, url, wiki

CATEGORY
       Documentation tools

COPYRIGHT
       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>

tcllib                                 2                   doctools::idx(3tcl)

Man(1) output converted with man2html
list of all man pages