doctools::idx::import::docidx(Documentation todoctools::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
       doctools::idx::import, the import manager.

       Using it from a regular interpreter is possible, however only with
       contortions, and is not recommended.  The proper way to use this
       functionality is through the package doctools::idx::import and the
       import manager objects it provides.

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

       import string configuration
              This command takes the string and parses it as docidx markup
              encoding a keyword index, in the context of the specified
              configuration (a dictionary). The result of the command is the
              canonical serialization of that keyword index, in the form
              specified 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
       documents

       [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
       serialize 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
                            references 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
                            identifiers 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
                            keywords dictionary, see previous item for its
                            definition.

              [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
                            documents 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
              possible 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://sourceforge.net/tracker/?group_id=12883].  Please also report
       any ideas for enhancements you may have for either package and/or
       documentation.

KEYWORDS
       deserialization, docidx, doctools, import, index

CATEGORY
       Text formatter plugin

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




doctools2idx                          0.1     doctools::idx::import::docidx(n)
