|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
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 через Генератор отчетов Ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.