


doctools::idx::import::Documentatdoctools::idx::import::docidx(n)


______________________________________________________________________________

NAME
       doctools::idx::import::docidx - docidx import plugin

SYNOPSIS
       package require Tcl  8.4

       package require doctools::idx::import::docidx  ?0.1?

       package require doctools::idx::parse

       package require doctools::idx::structure

       package require doctools::msgcat

       package require doctools::tcl::parse

       package require fileutil

       package require logger

       package require snit

       package require struct::list

       package require struct::set

       package require struct::stack

       package require struct::tree

       package require treeql

       import string configuration

_________________________________________________________________

DESCRIPTION
       This  package  implements  the doctools keyword index import plugin for
       the parsing of docidx markup.

       This is an internal package of doctools, for use by  the  higher  level
       management   packages   handling   keyword   indices,  especially  doc-
       tools::idx::import, the import manager.

       Using it from a regular interpreter is possible, however only with con-
       tortions, and is not recommended.  The proper way to use this function-
       ality is through the package doctools::idx::import and the import  man-
       ager objects it provides.

API
       The  API  provided  by  this package satisfies the specification of the
       docidx import plugin API version 2.



doctools2idx                   0.1                              1





doctools::idx::import::Documentatdoctools::idx::import::docidx(n)


       import string configuration
              This command takes the string and parses  it  as  docidx  markup
              encoding  a  keyword index, in the context of the specified con-
              figuration (a dictionary). The result  of  the  command  is  the
              canonical serialization of that keyword index, in the form spec-
              ified in section Keyword index serialization format.


[DOCIDX] NOTATION OF KEYWORD INDICES
       The docidx format for keyword indices, also called  the  docidx  markup
       language, is too large to be covered in single section.  The interested
       reader should start with the document

       [1]    docidx language introduction

       and then proceed from there to the formal specifications, i.e. the doc-
       uments

       [1]    docidx language syntax and

       [2]    docidx language command reference.

       to get a thorough understanding of the language.

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



doctools2idx                   0.1                              2





doctools::idx::import::Documentatdoctools::idx::import::docidx(n)


                             references  associated  with that particular key-
                             word.

                             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, refering to one of the docu-
                             ments the index was made for.

                      url    The identifier of the reference is interpreted as
                             an  url, refering 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
                     -increasing -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       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.




doctools2idx                   0.1                              3





doctools::idx::import::Documentatdoctools::idx::import::docidx(n)


KEYWORDS
       deserialization, docidx, doctools, import, index

CATEGORY
       Text formatter plugin

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

















































doctools2idx                   0.1                              4


