Spec-Zone .ru
спецификации, руководства, описания, API
Spec-Zone .ru
спецификации, руководства, описания, API
Библиотека разработчика Mac Разработчик
Поиск

 

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

Если Вы выполняете различную версию  Mac OS X, просматриваете документацию локально:

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

Страницы руководства предназначаются как справочник для людей, уже понимающих технологию.

  • Чтобы изучить, как руководство организовано или узнать о синтаксисе команды, прочитайте страницу руководства для страниц справочника (5).

  • Для получения дополнительной информации об этой технологии, ищите другую документацию в Библиотеке Разработчика Apple.

  • Для получения общей информации о записи сценариев оболочки, считайте Shell, Пишущий сценарий Учебника для начинающих.



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



____________________________________________________________________________________________________________

NAME
       doctools::toc - doctoc - Processing tables of contents

SYNOPSIS
       package require Tcl  8.2

       package require doctools::toc  ?1.1.3?

       ::doctools::toc::new objectName ?-option value ...?

       ::doctools::toc::help

       ::doctools::toc::search path

       objectName method ?arg arg ...?

       objectName configure

       objectName configure option

       objectName configure -option value...

       objectName cget -option

       objectName destroy

       objectName format text

       objectName map symbolic actual

       objectName parameters

       objectName search path

       objectName setparam name value

       objectName warnings

____________________________________________________________________________________________________________

DESCRIPTION
       This package provides a class for the creation of objects able to process and convert text written in
       the doctoc markup language into any output format X for which a formatting engine is available.

       A reader interested in the markup language itself should start with the doctoc language  introduction
       and  proceed  from there to the formal specifications, i.e. the doctoc language syntax and the doctoc
       language command reference.

       If on the other hand the reader wishes to write her own formatting engine for some format, i.e. is  a
       plugin  writer  then  reading and understanding the doctoc plugin API reference is an absolute neces-sity, necessity,
       sity, as that document specifies the interaction between this package and its plugins, i.e. the  for-matting formatting
       matting engines, in detail.

PUBLIC API
   PACKAGE COMMANDS
       ::doctools::toc::new objectName ?-option value ...?
              This  command creates a new doctoc object with an associated Tcl command whose name is object-Name. objectName.
              Name. This object command is explained in full detail  in  the  sections  OBJECT  COMMAND  and
              OBJECT  METHODS. The object command will be created under the current namespace if the object-Name objectName
              Name is not fully qualified, and in the specified namespace otherwise.

              The options and their values coming after the name of the object are used to set  the  initial
              configuration of the object.

       ::doctools::toc::help
              This  is  a  convenience  command  for applications wishing to provide their user with a short
              description of the available formatting commands and their meanings. It returns a string  con-taining containing
              taining a standard help text.

       ::doctools::toc::search path
              Whenever  an  object  created  by this the package has to map the name of a format to the file
              containing the code for its formatting engine it will search for  the  file  in  a  number  of
              directories stored in a list. See section FORMAT MAPPING for more explanations.

              This  list  not  only  contains  three  default  directories which are declared by the package
              itself, but is also extensible user of the package.  This command is the means to do so.  When
              given  a path to an existing and readable directory it will prepend that directory to the list
              of directories to search. This means that the path added last is later searched through first.

              An error will be thrown if the path either does not exist, is not a directory, or is not read-able. readable.
              able.


   OBJECT COMMAND
       All commands created by ::doctools::toc::new have the following general  form  and  may  be  used  to
       invoke various operations on their doctoc converter object.

       objectName method ?arg arg ...?
              The  method method and its arg'uments determine the exact behavior of the command. See section
              OBJECT METHODS for the detailed specifications.


   OBJECT METHODS
       objectName configure
              The method returns a list of all known options and their current values  when  called  without
              any arguments.

       objectName configure option
              The  method  behaves  like  the method cget when called with a single argument and returns the
              value of the option specified by said argument.

       objectName configure -option value...
              The method reconfigures the specified options of the object, setting them  to  the  associated
              values, when called with an even number of arguments, at least two.

              The legal options are described in the section OBJECT CONFIGURATION.

       objectName cget -option
              This method expects a legal configuration option as argument and will return the current value
              of that option for the object the method was invoked for.

              The legal configuration options are described in section OBJECT CONFIGURATION.

       objectName destroy
              This method destroys the object it is invoked for.

       objectName format text
              This method runs the text through the configured formatting engine and returns  the  generated
              string as its result. An error will be thrown if no -format was configured for the object.

              The  method  assumes  that the text is in doctoc format as specified in the companion document
              doctoc_fmt. Errors will be thrown otherwise.

       objectName map symbolic actual
              This methods add one entry to the per-object mapping from symbolic  filenames  to  the  actual
              uris.  The object just stores this mapping and makes it available to the configured formatting
              engine through the command dt_fmap.  This command is described in more detail  in  the  doctoc
              plugin API reference which specifies the interaction between the objects created by this pack-age package
              age and toc formatting engines.

       objectName parameters
              This method returns a list containing the names of all engine parameters provided by the  con-figured configured
              figured  formatting  engine.  It will return an empty list if the object is not yet configured
              for a specific format.

       objectName search path
              This method extends the per-object list of paths searched for toc formatting engines. See also
              the  command ::doctools::toc::search on how to extend the per-package list of paths. Note that
              the path entered last will be searched first.  For more details see section FORMAT MAPPING.

       objectName setparam name value
              This method sets the named engine parameter to the specified value.  It will throw an error if
              the object is either not yet configured for a specific format, or if the formatting engine for
              the configured format does not provide a parameter with the given name.  The list  of  parame-ters parameters
              ters  provided by the configured formatting engine can be retrieved through the method parame-ters. parameters.
              ters.

       objectName warnings
              This method returns a list containing all the warnings which were generated by the  configured
              formatting engine during the last invocation of the method format.


   OBJECT CONFIGURATION
       All doctoc objects understand the following configuration options:

       -file file
              The  argument of this option is stored in the object and made available to the configured for-matting formatting
              matting engine through the command dt_file.  This command is described in more detail  in  the
              companion  document  doctoc_api  which  specifies  the  API  between the object and formatting
              engines.

              The default value of this option is the empty string.

              The configured formatting engine should interpret the value as the name of the file containing
              the document which is currently processed.

       -format text
              The argument of this option specifies the format to generate and by implication the formatting
              engine to use when converting text via the method format.  Its  default  value  is  the  empty
              string.  The  method format cannot be used if this option is not set to a valid value at least
              once.

              The package will immediately try to map the given name to a file containing  the  code  for  a
              formatting  engine  generating  that format. An error will be thrown if this mapping fails. In
              that case a previously configured format is left untouched.

              The section FORMAT MAPPING explains in detail how the package and object will look for  engine
              implementations.


   FORMAT MAPPING
       The package and object will perform the following algorithm when trying to map a format name foo to a
       file containing an implementation of a formatting engine for foo:

       [1]    If foo is the name of an existing file then this file is directly taken as the implementation.

       [2]    If  not,  the  list of per-object search paths is searched. For each directory in the list the
              package checks if that directory contains a file "toc.foo". If yes, then that file is taken as
              the implementation.

              Note  that this list of paths is initially empty and can be extended through the object method
              search.

       [3]    If not, the list of package paths is searched.  For each directory in  the  list  the  package
              checks  if  that  directory  contains a file "toc.foo". If yes, then that file is taken as the
              implementation.

              This list of paths can be extended through the command ::doctools::toc::search.   It  contains
              initially  one  path,  the  subdirectory  "mpformats"  of  the directory the package itself is
              located in. In other words, if the package implementation "doctoc.tcl"  is  installed  in  the
              directory  "/usr/local/lib/tcllib/doctools"  then  it  will  by  default  search the directory
              "/usr/local/lib/tcllib/doctools/mpformats" for format implementations.

       [4]    The mapping fails.


PREDEFINED ENGINES
       The package provides predefined formatting engines for the following formats. Some of the  formatting
       engines support engine parameters. These will be explicitly highlighted.

       html   This  engine  generates  HTML markup, for processing by web browsers and the like. This engine
              supports three parameters:

              footer The value for this parameter has to be valid selfcontained HTML  markup  for  the  body
                     section  of  a  HTML  document.  The  default  value  is the empty string. The value is
                     inserted into the generated output just before the </body> tag, closing the body of the
                     generated HTML.

                     This can be used to insert boilerplate footer markup into the generated document.

              header The  value  for  this  parameter has to be valid selfcontained HTML markup for the body
                     section of a HTML document. The default  value  is  the  empty  string.  The  value  is
                     inserted  into the generated output just after the <body> tag, starting the body of the
                     generated HTML.

                     This can be used to insert boilerplate header markup into the generated document.

              meta   The value for this parameter has to be valid selfcontained HTML markup for  the  header
                     section  of  a  HTML  document.  The  default  value  is the empty string. The value is
                     inserted into the generated output just after the <head> tag, starting the header  sec-tion section
                     tion of the generated HTML.

                     This  can  be  used to insert boilerplate meta data markup into the generated document,
                     like references to a stylesheet, standard meta keywords, etc.


       latex  This engine generates output suitable for the latex text  processor  coming  out  of  the  TeX
              world.

       list   This  engine retrieves version, section and title of the manpage from the document. As such it
              can be used to generate a directory listing for a set of manpages.

       nroff  This engine generates nroff output, for processing by nroff, or  groff.  The  result  will  be
              standard man pages as they are known in the unix world.

       null   This  engine  generates  no outout at all. This can be used if one just wants to validate some
              input.

       tmml   This engine generates TMML markup as specified by Joe English. The Tcl Manpage Markup Language
              is a derivate of XML.

       wiki   This engine generates Wiki markup as understood by Jean Claude Wippler's wikit application.


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.

SEE ALSO
       doctoc_intro, doctoc_lang_cmdref, doctoc_lang_intro, doctoc_lang_syntax, doctoc_plugin_apiref

KEYWORDS
       HTML, TMML, conversion, doctoc, documentation, latex, manpage, markup, nroff, table of contents, toc,
       wiki

CATEGORY
       Documentation tools

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




doctools                                            1.1.3                                   doctools::toc(n)

Сообщение о проблемах

Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:

Ошибки содержания
Ошибки отчета в содержании этой документации со ссылками на отзыв ниже.
Отчеты об ошибках
Сообщите об ошибках в функциональности описанного инструмента или API через Генератор отчетов Ошибки.
Форматирование проблем
Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.