1doctools::toc(n) Documentation tools doctools::toc(n)
2______________________________________________________________________________
6
8 doctools::toc - doctoc - Processing tables of contents
9
11 package require Tcl 8.2
12 package require doctools::toc ?1.2?
14 ::doctools::toc::new objectName ?-option value ...?
16 ::doctools::toc::help
18 ::doctools::toc::search path
20 objectName method ?arg arg ...?
22 objectName configure
24 objectName configure option
26 objectName configure -option value...
28 objectName cget -option
30 objectName destroy
32 objectName format text
34 objectName map symbolic actual
36 objectName parameters
38 objectName search path
40 objectName setparam name value
42 objectName warnings
44______________________________________________________________________________
46
48 This package provides a class for the creation of objects able to
49 process and convert text written in the doctoc markup language into any
50 output format X for which a formatting engine is available.
51 A reader interested in the markup language itself should start with the
53 doctoc language introduction and proceed from there to the formal spec‐
54 ifications, i.e. the doctoc language syntax and the doctoc language
55 command reference.
56 If on the other hand the reader wishes to write her own formatting en‐
58 gine for some format, i.e. is a plugin writer then reading and under‐
59 standing the doctoc plugin API reference is an absolute necessity, as
60 that document specifies the interaction between this package and its
61 plugins, i.e. the formatting engines, in detail.
62
64 PACKAGE COMMANDS
65 ::doctools::toc::new objectName ?-option value ...?
66 This command creates a new doctoc object with an associated Tcl
67 command whose name is objectName. This object command is ex‐
68 plained in full detail in the sections OBJECT COMMAND and OBJECT
69 METHODS. The object command will be created under the current
70 namespace if the objectName is not fully qualified, and in the
71 specified namespace otherwise.
72 The options and their values coming after the name of the object
74 are used to set the initial configuration of the object.
75 ::doctools::toc::help
77 This is a convenience command for applications wishing to pro‐
78 vide their user with a short description of the available for‐
79 matting commands and their meanings. It returns a string con‐
80 taining a standard help text.
81 ::doctools::toc::search path
83 Whenever an object created by this the package has to map the
84 name of a format to the file containing the code for its format‐
85 ting engine it will search for the file in a number of directo‐
86 ries stored in a list. See section FORMAT MAPPING for more ex‐
87 planations.
88 This list not only contains three default directories which are
90 declared by the package itself, but is also extensible user of
91 the package. This command is the means to do so. When given a
92 path to an existing and readable directory it will prepend that
93 directory to the list of directories to search. This means that
94 the path added last is later searched through first.
95 An error will be thrown if the path either does not exist, is
97 not a directory, or is not readable.
98 OBJECT COMMAND
100 All commands created by ::doctools::toc::new have the following general
101 form and may be used to invoke various operations on their doctoc con‐
102 verter object.
103 objectName method ?arg arg ...?
105 The method method and its arg'uments determine the exact behav‐
106 ior of the command. See section OBJECT METHODS for the detailed
107 specifications.
108 OBJECT METHODS
110 objectName configure
111 The method returns a list of all known options and their current
112 values when called without any arguments.
113 objectName configure option
115 The method behaves like the method cget when called with a sin‐
116 gle argument and returns the value of the option specified by
117 said argument.
118 objectName configure -option value...
120 The method reconfigures the specified options of the object,
121 setting them to the associated values, when called with an even
122 number of arguments, at least two.
123 The legal options are described in the section OBJECT CONFIGURA‐
125 TION.
126 objectName cget -option
128 This method expects a legal configuration option as argument and
129 will return the current value of that option for the object the
130 method was invoked for.
131 The legal configuration options are described in section OBJECT
133 CONFIGURATION.
134 objectName destroy
136 This method destroys the object it is invoked for.
137 objectName format text
139 This method runs the text through the configured formatting en‐
140 gine and returns the generated string as its result. An error
141 will be thrown if no -format was configured for the object.
142 The method assumes that the text is in doctoc format as speci‐
144 fied in the companion document doctoc_fmt. Errors will be thrown
145 otherwise.
146 objectName map symbolic actual
148 This methods add one entry to the per-object mapping from sym‐
149 bolic filenames to the actual uris. The object just stores this
150 mapping and makes it available to the configured formatting en‐
151 gine through the command dt_fmap. This command is described in
152 more detail in the doctoc plugin API reference which specifies
153 the interaction between the objects created by this package and
154 toc formatting engines.
155 objectName parameters
157 This method returns a list containing the names of all engine
158 parameters provided by the configured formatting engine. It will
159 return an empty list if the object is not yet configured for a
160 specific format.
161 objectName search path
163 This method extends the per-object list of paths searched for
164 toc formatting engines. See also the command ::doc‐
165 tools::toc::search on how to extend the per-package list of
166 paths. Note that the path entered last will be searched first.
167 For more details see section FORMAT MAPPING.
168 objectName setparam name value
170 This method sets the named engine parameter to the specified
171 value. It will throw an error if the object is either not yet
172 configured for a specific format, or if the formatting engine
173 for the configured format does not provide a parameter with the
174 given name. The list of parameters provided by the configured
175 formatting engine can be retrieved through the method parame‐
176 ters.
177 objectName warnings
179 This method returns a list containing all the warnings which
180 were generated by the configured formatting engine during the
181 last invocation of the method format.
182 OBJECT CONFIGURATION
184 All doctoc objects understand the following configuration options:
185 -file file
187 The argument of this option is stored in the object and made
188 available to the configured formatting engine through the com‐
189 mand dt_file. This command is described in more detail in the
190 companion document doctoc_api which specifies the API between
191 the object and formatting engines.
192 The default value of this option is the empty string.
194 The configured formatting engine should interpret the value as
196 the name of the file containing the document which is currently
197 processed.
198 -format text
200 The argument of this option specifies the format to generate and
201 by implication the formatting engine to use when converting text
202 via the method format. Its default value is the empty string.
203 The method format cannot be used if this option is not set to a
204 valid value at least once.
205 The package will immediately try to map the given name to a file
207 containing the code for a formatting engine generating that for‐
208 mat. An error will be thrown if this mapping fails. In that case
209 a previously configured format is left untouched.
210 The section FORMAT MAPPING explains in detail how the package
212 and object will look for engine implementations.
213 FORMAT MAPPING
215 The package and object will perform the following algorithm when trying
216 to map a format name foo to a file containing an implementation of a
217 formatting engine for foo:
218 [1] If foo is the name of an existing file then this file is di‐
220 rectly taken as the implementation.
221 [2] If not, the list of per-object search paths is searched. For
223 each directory in the list the package checks if that directory
224 contains a file "toc.foo". If yes, then that file is taken as
225 the implementation.
226 Note that this list of paths is initially empty and can be ex‐
228 tended through the object method search.
229 [3] If not, the list of package paths is searched. For each direc‐
231 tory in the list the package checks if that directory contains a
232 file "toc.foo". If yes, then that file is taken as the implemen‐
233 tation.
234 This list of paths can be extended through the command ::doc‐
236 tools::toc::search. It contains initially one path, the subdi‐
237 rectory "mpformats" of the directory the package itself is lo‐
238 cated in. In other words, if the package implementation "doc‐
239 toc.tcl" is installed in the directory "/usr/lo‐
240 cal/lib/tcllib/doctools" then it will by default search the di‐
241 rectory "/usr/local/lib/tcllib/doctools/mpformats" for format
242 implementations.
243 [4] The mapping fails.
245
247 The package provides predefined formatting engines for the following
248 formats. Some of the formatting engines support engine parameters.
249 These will be explicitly highlighted.
250 html This engine generates HTML markup, for processing by web
252 browsers and the like. This engine supports three parameters:
253 footer The value for this parameter has to be valid selfcon‐
255 tained HTML markup for the body section of a HTML docu‐
256 ment. The default value is the empty string. The value is
257 inserted into the generated output just before the
258 </body> tag, closing the body of the generated HTML.
259 This can be used to insert boilerplate footer markup into
261 the generated document.
262 header The value for this parameter has to be valid selfcon‐
264 tained HTML markup for the body section of a HTML docu‐
265 ment. The default value is the empty string. The value is
266 inserted into the generated output just after the <body>
267 tag, starting the body of the generated HTML.
268 This can be used to insert boilerplate header markup into
270 the generated document.
271 meta The value for this parameter has to be valid selfcon‐
273 tained HTML markup for the header section of a HTML docu‐
274 ment. The default value is the empty string. The value is
275 inserted into the generated output just after the <head>
276 tag, starting the header section of the generated HTML.
277 This can be used to insert boilerplate meta data markup
279 into the generated document, like references to a
280 stylesheet, standard meta keywords, etc.
281 latex This engine generates output suitable for the latex text proces‐
284 sor coming out of the TeX world.
285 list This engine retrieves version, section and title of the manpage
287 from the document. As such it can be used to generate a direc‐
288 tory listing for a set of manpages.
289 markdown
291 This engine generates Markdown markup.
292 nroff This engine generates nroff output, for processing by nroff, or
294 groff. The result will be standard man pages as they are known
295 in the unix world.
296 null This engine generates no outout at all. This can be used if one
298 just wants to validate some input.
299 tmml This engine generates TMML markup as specified by Joe English.
301 The Tcl Manpage Markup Language is a derivate of XML.
302 wiki This engine generates Wiki markup as understood by Jean Claude
304 Wippler's wikit application.
305
307 This document, and the package it describes, will undoubtedly contain
308 bugs and other problems. Please report such in the category doctools
309 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
310 also report any ideas for enhancements you may have for either package
311 and/or documentation.
312 When proposing code changes, please provide unified diffs, i.e the out‐
314 put of diff -u.
315 Note further that attachments are strongly preferred over inlined
317 patches. Attachments can be made by going to the Edit form of the
318 ticket immediately after its creation, and then using the left-most
319 button in the secondary navigation bar.
320
322 doctoc_intro, doctoc_lang_cmdref, doctoc_lang_intro, doctoc_lang_syn‐
323 tax, doctoc_plugin_apiref
324
326 HTML, TMML, conversion, doctoc, documentation, latex, manpage, mark‐
327 down, markup, nroff, table of contents, toc, wiki
328
330 Documentation tools
331
333 Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
334tcllib 1.2 doctools::toc(n)