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

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

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

doctools::toc::export::nroff(n)              Documentation tools             doctools::toc::export::nroff(n)



____________________________________________________________________________________________________________

NAME
       doctools::toc::export::nroff - nroff export plugin

SYNOPSIS
       package require Tcl  8.4

       package require doctools::toc::export::nroff  ?0.2?

       package require doctools::text

       package require doctools::nroff::man_macros

       export serial configuration

____________________________________________________________________________________________________________

DESCRIPTION
       This  package  implements  the  doctools  table of contents export plugin for the generation of nroff
       markup.

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

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

       export serial configuration
              This command takes the canonical serialization of a table of contents, as specified in section
              ToC serialization format, and contained in serial, the configuration, a dictionary, and gener-ates generates
              ates nroff markup encoding the table.  The created string is then returned as  the  result  of
              the command.


CONFIGURATION
       The nroff export plugin recognizes the following configuration variables and changes its behaviour as
       they specify.

       string user
              This standard configuration variable contains the name of the user running the  process  which
              invoked  the  export  plugin.  The plugin puts this information into the provenance comment at
              the beginning of the generated document.

       string file
              This standard configuration variable contains the name of the file the table of contents  came
              from. This variable may not be set or contain the empty string.  The plugin puts this informa-tion, information,
              tion, if defined, i.e. set and not the empty string, into the provenance comment at the begin-ning beginning
              ning of the generated document.

       boolean inline
              If  this  flag  is  set  (default)  the plugin will place the definitions of the man macro set
              directly into the output.

              If this flag is not set, the plugin will place a reference to the definitions of the man macro
              set into the output, but not the macro definitions themselves.

       Note that this plugin ignores the standard configuration variables format, and map, and their values.

TOC SERIALIZATION FORMAT
       Here we specify the format used by the doctools v2  packages  to  serialize  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 exactly 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 dictionary holding the title of the ta-ble table
                     ble 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 alternative 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 referenced document, a label, and a longer textual descrip-tion description
                                   tion 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 divisions) 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 con-taining containing
                                   taining 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 optional.

                                   label  The  value  is  a  string  containing  a label for the group. This
                                          string also identifies the entry, and no two  entries  (references
                                          and divisions) 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 contents, including other divisions.

       canonical serialization
              The canonical serialization of a table of contents 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 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  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
       doctools, export, nroff, serialization, table of contents, toc

CATEGORY
       Text formatter plugin

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




doctools2toc                                         0.2                     doctools::toc::export::nroff(n)