Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

doctools::idx::import::docidx(n)             Documentation tools            doctools::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  recom-mended. recommended.
       mended.   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 canon-ical canonical
              ical serialization of that keyword index, in the form specified in section Keyword index seri-alization serialization
              alization 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 refer-ences references
                            ences 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 dictio-nary, dictionary,
                            nary, 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 -increas-ing -increasing
                     ing -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.

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)