1doctools::toc(n)              Documentation tools             doctools::toc(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::toc - Create and manipulate doctoc converter objects
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require doctools::toc  ?0.2.1?
14
15       ::doctools::toc::new objectName ?-option value ...?
16
17       ::doctools::toc::help
18
19       ::doctools::toc::search path
20
21       objectName method ?arg arg ...?
22
23       objectName configure
24
25       objectName configure option
26
27       objectName configure -option value...
28
29       objectName cget -option
30
31       objectName destroy
32
33       objectName format text
34
35       objectName map symbolic actual
36
37       objectName parameters
38
39       objectName search path
40
41       objectName setparam name value
42
43       objectName warnings
44
45_________________________________________________________________
46

DESCRIPTION

48       This package provides objects for the conversion of text written in the
49       doctoc format into any output format  X,  assuming  that  a  formatting
50       engine for X is available.
51
52       This document has two companions.  The first, doctoc_fmt, is the formal
53       specification of the doctoc format; the other, doctoc_api, is the  for‐
54       mal  specification  of  the interface between the objects provided here
55       and the formatting engines they require.
56

PUBLIC API

58   PACKAGE COMMANDS
59       ::doctools::toc::new objectName ?-option value ...?
60              This command creates a new doctoc object with an associated  Tcl
61              command  whose  name  is  objectName.  This  object  command  is
62              explained in full detail in  the  sections  OBJECT  COMMAND  and
63              OBJECT  METHODS.  The  object  command will be created under the
64              current namespace if the objectName is not fully qualified,  and
65              in the specified namespace otherwise.
66
67              The options and their values coming after the name of the object
68              are used to set the initial configuration of the object.
69
70       ::doctools::toc::help
71              This is a convenience command for applications wishing  to  pro‐
72              vide  their  user with a short description of the available for‐
73              matting commands and their meanings. It returns  a  string  con‐
74              taining a standard help text.
75
76       ::doctools::toc::search path
77              Whenever  an  object  created by this the package has to map the
78              name of a format to the file containing the code for its format‐
79              ting  engine it will search for the file in a number of directo‐
80              ries stored in a list.  See  section  FORMAT  MAPPING  for  more
81              explanations.
82
83              This  list not only contains three default directories which are
84              declared by the package itself, but is also extensible  user  of
85              the  package.   This command is the means to do so. When given a
86              path to an existing and readable directory it will prepend  that
87              directory  to the list of directories to search. This means that
88              the path added last is later searched through first.
89
90              An error will be thrown if the path either does  not  exist,  is
91              not a directory, or is not readable.
92
93   OBJECT COMMAND
94       All commands created by ::doctools::toc::new have the following general
95       form and may be used to invoke various operations on their doctoc  con‐
96       verter object.
97
98       objectName method ?arg arg ...?
99              The  method method and its arg'uments determine the exact behav‐
100              ior of the command. See section OBJECT METHODS for the  detailed
101              specifications.
102
103   OBJECT METHODS
104       objectName configure
105              The method returns a list of all known options and their current
106              values when called without any arguments.
107
108       objectName configure option
109              The method behaves like the method cget when called with a  sin‐
110              gle  argument  and  returns the value of the option specified by
111              said argument.
112
113       objectName configure -option value...
114              The method reconfigures the specified  options  of  the  object,
115              setting  them to the associated values, when called with an even
116              number of arguments, at least two.
117
118              The legal options are described in the section OBJECT CONFIGURA‐
119              TION.
120
121       objectName cget -option
122              This method expects a legal configuration option as argument and
123              will return the current value of that option for the object  the
124              method was invoked for.
125
126              The  legal configuration options are described in section OBJECT
127              CONFIGURATION.
128
129       objectName destroy
130              This method destroys the object it is invoked for.
131
132       objectName format text
133              This method runs the  text  through  the  configured  formatting
134              engine  and returns the generated string as its result. An error
135              will be thrown if no -format was configured for the object.
136
137              The method assumes that the text is in doctoc format  as  speci‐
138              fied in the companion document doctoc_fmt. Errors will be thrown
139              otherwise.
140
141       objectName map symbolic actual
142              This methods add one entry to the per-object mapping  from  sym‐
143              bolic filenames to the actual uris.  The object just stores this
144              mapping and makes it  available  to  the  configured  formatting
145              engine  through  the command dt_fmap.  This command is described
146              in more detail in the companion document doctoc_api which speci‐
147              fies the API between the object and toc formatting engines.
148
149       objectName parameters
150              This  method  returns  a list containing the names of all engine
151              parameters provided by the configured formatting engine. It will
152              return  an  empty list if the object is not yet configured for a
153              specific format.
154
155       objectName search path
156              This method extends the per-object list of  paths  searched  for
157              toc   formatting   engines.   See   also   the   command  ::doc‐
158              tools::toc::search on how to  extend  the  per-package  list  of
159              paths.  Note  that the path entered last will be searched first.
160              For more details see section FORMAT MAPPING.
161
162       objectName setparam name value
163              This method sets the named engine  parameter  to  the  specified
164              value.   It  will throw an error if the object is either not yet
165              configured for a specific format, or if  the  formatting  engine
166              for  the configured format does not provide a parameter with the
167              given name.  The list of parameters provided by  the  configured
168              formatting  engine  can  be retrieved through the method parame‐
169              ters.
170
171       objectName warnings
172              This method returns a list containing  all  the  warnings  which
173              were  generated  by  the configured formatting engine during the
174              last invocation of the method format.
175
176   OBJECT CONFIGURATION
177       All doctoc objects understand the following configuration options:
178
179       -file file
180              The argument of this option is stored in  the  object  and  made
181              available  to  the configured formatting engine through the com‐
182              mand dt_file.  This command is described in more detail  in  the
183              companion  document  doctoc_api  which specifies the API between
184              the object and formatting engines.
185
186              The default value of this option is the empty string.
187
188              The configured formatting engine should interpret the  value  as
189              the  name of the file containing the document which is currently
190              processed.
191
192       -format text
193              The argument of this option specifies the format to generate and
194              by implication the formatting engine to use when converting text
195              via the method format. Its default value is  the  empty  string.
196              The  method format cannot be used if this option is not set to a
197              valid value at least once.
198
199              The package will immediately try to map the given name to a file
200              containing the code for a formatting engine generating that for‐
201              mat. An error will be thrown if this mapping fails. In that case
202              a previously configured format is left untouched.
203
204              The  section  FORMAT  MAPPING explains in detail how the package
205              and object will look for engine implementations.
206
207   FORMAT MAPPING
208       The package and object will perform the following algorithm when trying
209       to  map  a  format name foo to a file containing an implementation of a
210       formatting engine for foo:
211
212       [1]    If foo is the name  of  an  existing  file  then  this  file  is
213              directly taken as the implementation.
214
215       [2]    If  not,  the  list  of per-object search paths is searched. For
216              each directory in the list the package checks if that  directory
217              contains  a  file  "toc.foo". If yes, then that file is taken as
218              the implementation.
219
220              Note that this list of paths  is  initially  empty  and  can  be
221              extended through the object method search.
222
223       [3]    If  not, the list of package paths is searched.  For each direc‐
224              tory in the list the package checks if that directory contains a
225              file "toc.foo". If yes, then that file is taken as the implemen‐
226              tation.
227
228              This list of paths can be extended through  the  command  ::doc‐
229              tools::toc::search.   It contains initially one path, the subdi‐
230              rectory "mpformats" of  the  directory  the  package  itself  is
231              located  in. In other words, if the package implementation "doc‐
232              toc.tcl"      is      installed      in      the       directory
233              "/usr/local/lib/tcllib/doctools"  then it will by default search
234              the  directory  "/usr/local/lib/tcllib/doctools/mpformats"   for
235              format implementations.
236
237       [4]    The mapping fails.
238

PREDEFINED ENGINES

240       The  package  provides  predefined formatting engines for the following
241       formats. Some of the  formatting  engines  support  engine  parameters.
242       These will be explicitly highlighted.
243
244       html   This  engine  generates  HTML  markup,  for  processing  by  web
245              browsers and the like. This engine supports three parameters:
246
247              footer The value for this parameter has  to  be  valid  selfcon‐
248                     tained  HTML  markup for the body section of a HTML docu‐
249                     ment. The default value is the empty string. The value is
250                     inserted  into  the  generated  output  just  before  the
251                     </body> tag, closing the body of the generated HTML.
252
253                     This can be used to insert boilerplate footer markup into
254                     the generated document.
255
256              header The  value  for  this  parameter has to be valid selfcon‐
257                     tained HTML markup for the body section of a  HTML  docu‐
258                     ment. The default value is the empty string. The value is
259                     inserted into the generated output just after the  <body>
260                     tag, starting the body of the generated HTML.
261
262                     This can be used to insert boilerplate header markup into
263                     the generated document.
264
265              meta   The value for this parameter has  to  be  valid  selfcon‐
266                     tained HTML markup for the header section of a HTML docu‐
267                     ment. The default value is the empty string. The value is
268                     inserted  into the generated output just after the <head>
269                     tag, starting the header section of the generated HTML.
270
271                     This can be used to insert boilerplate meta  data  markup
272                     into   the  generated  document,  like  references  to  a
273                     stylesheet, standard meta keywords, etc.
274
275
276       latex  This engine generates output suitable for the latex text proces‐
277              sor coming out of the TeX world.
278
279       list   This  engine retrieves version, section and title of the manpage
280              from the document. As such it can be used to generate  a  direc‐
281              tory listing for a set of manpages.
282
283       nroff  This  engine generates nroff output, for processing by nroff, or
284              groff. The result will be standard man pages as they  are  known
285              in the unix world.
286
287       null   This  engine generates no outout at all. This can be used if one
288              just wants to validate some input.
289
290       tmml   This engine generates TMML markup as specified by  Joe  English.
291              The Tcl Manpage Markup Language is a derivate of XML.
292
293       wiki   This  engine  generates Wiki markup as understood by Jean Claude
294              Wippler's wikit application.
295

SEE ALSO

297       doctoc_api, doctoc_fmt, doctools
298

KEYWORDS

300       HTML, TMML, conversion, doctoc, documentation, latex, manpage,  markup,
301       nroff, table of contents, toc, wiki
302
304       Copyright (c) 2003-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
305
306
307
308
309doctools                             0.2.1                    doctools::toc(n)
Impressum