import_doctoc(3)



doctools::toc::import::doctoc(Documentationdoctools::toc::import::doctoc(3tcl)

______________________________________________________________________________

NAME
       doctools::toc::import::doctoc - doctoc import plugin

SYNOPSIS
       package require Tcl  8.5

       package require doctools::toc::import::doctoc  ?0.2.1?

       package require doctools::toc::parse

       package require doctools::toc::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 table of contents import plugin
       for the parsing of doctoc markup.

       This is an internal package of doctools, for use by  the  higher  level
       management  packages  handling  tables  of  contents,  especially  doc-
       tools::toc::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::toc::import and the import  man-
       ager objects it provides.

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

       import string configuration
              This command takes the string and parses it as doctoc markup en-
              coding a table of contents, in the context of the specified con-
              figuration (a dictionary). The result  of  the  command  is  the
              canonical  serialization  of that table of contents, in the form
              specified in section ToC serialization format.

[DOCTOC] NOTATION OF TABLES OF CONTENTS
       The doctoc format for tables of contents, also called the doctoc markup
       language, is too large to be covered in single section.  The interested
       reader should start with the document

       [1]    doctoc language introduction

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

       [1]    doctoc language syntax and

       [2]    doctoc language command reference.

       to get a thorough understanding of the language.

TOC SERIALIZATION FORMAT
       Here  we specify the format used by the doctools v2 packages to serial-
       ize tables of contents as immutable values for  transport,  comparison,
       etc.

       We  distinguish  between regular and canonical serializations.  While a
       table of contents may have more than one regular serialization only ex-
       actly one of them will be canonical.

       regular serialization

              [1]    The  serialization  of  any table of contents is a nested
                     Tcl dictionary.

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

              [3]    The contents of the table of contents are a  Tcl  dictio-
                     nary holding the title of the table of contents, a label,
                     and its elements. The relevant keys and their values are

                     title  The value is a string containing the title of  the
                            table of contents.

                     label  The  value  is a string containing a label for the
                            table of contents.

                     items  The value is a Tcl list holding  the  elements  of
                            the table, in the order they are to be shown.

                            Each element is a Tcl list holding the type of the
                            item, and its description, in this order.  An  al-
                            ternative  description  would  be that it is a Tcl
                            dictionary holding a single key,  the  item  type,
                            mapped to the item description.

                            The  two  legal  item types and their descriptions
                            are

                            reference
                                   This item describes a single entry  in  the
                                   table  of  contents,  referencing  a single
                                   document.  To this end its value is  a  Tcl
                                   dictionary  containing an id for the refer-
                                   enced document, a label, and a longer  tex-
                                   tual  description  which  can be associated
                                   with the  entry.   The  relevant  keys  and
                                   their values are

                                   id     The value is a string containing the
                                          id of the document  associated  with
                                          the entry.

                                   label  The  value  is a string containing a
                                          label for this  entry.  This  string
                                          also  identifies  the  entry, and no
                                          two entries  (references  and  divi-
                                          sions)  in  the  containing list are
                                          allowed to have the same label.

                                   desc   The value is a string  containing  a
                                          longer description for this entry.

                            division
                                   This  item  describes a group of entries in
                                   the table of contents, inducing a hierarchy
                                   of entries.  To this end its value is a Tcl
                                   dictionary  containing  a  label  for   the
                                   group, an optional id to a document for the
                                   whole group, and the list of entries in the
                                   group.   The relevant keys and their values
                                   are

                                   id     The value is a string containing the
                                          id  of  the document associated with
                                          the whole group.  This  key  is  op-
                                          tional.

                                   label  The  value  is a string containing a
                                          label for  the  group.  This  string
                                          also  identifies  the  entry, and no
                                          two entries  (references  and  divi-
                                          sions)  in  the  containing list are
                                          allowed to have the same label.

                                   items  The value is a Tcl list holding  the
                                          elements  of the group, in the order
                                          they are to be shown.  This list has
                                          the  same structure as the value for
                                          the keyword items used  to  describe
                                          the  whole  table  of  contents, see
                                          above.  This  closes  the  recusrive
                                          definition  of  the  structure, with
                                          divisions holding the same  type  of
                                          elements  as the whole table of con-
                                          tents, including other divisions.

       canonical serialization
              The canonical serialization of a table of contents has the  for-
              mat  as  specified  in  the previous item, and then additionally
              satisfies the constraints below, which make it unique among  all
              the possible serializations of this table of contents.

              [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.

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
       deserialization, doctoc, doctools, import, table of contents, toc

CATEGORY
       Text formatter plugin

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

tcllib                               0.2.1 doctools::toc::import::doctoc(3tcl)

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