1doctoc_api(n) Documentation tools doctoc_api(n)
2______________________________________________________________________________
6
8 doctoc_api - Specification of the Interface to ToC Formatting Engines
9
11 toc_numpasses
12 toc_initialize
14 toc_setup n
16 toc_postprocess text
18 toc_shutdown
20 toc_listvariables
22 toc_varset varname text
24 fmt_plain_text text
26 fmt_comment text
28 fmt_toc_begin text title
30 fmt_toc_end
32 fmt_division_start text ?symfile?
34 fmt_division_end
36 fmt_item file text desc
38 dt_format
40 dt_fmap symfname
42 dt_source file
44 ex_cappend
46 ex_cget
48 ex_cis
50 ex_cname
52 ex_cpop
54 ex_cpush
56 ex_cset
58 ex_lb
60 ex_rb
62_________________________________________________________________
64
66 This document specifies version 1 of the interface an toc formatting
67 engine has to comply with to be usable by the package doctools::toc.
68 The specification of the doctoc format all toc formatting engines have
69 to process can be found in the companion document doctoc_fmt.
70
72 EXPORTED COMMANDS
73 Each toc formatting engine has to provide a number of commands through
74 which objects created by the package doctools::toc will upon the func‐
75 tionality of the engine. These commands are described here.
76 Management commands
78 toc_numpasses
80 This command is called by a doctoc object immediately
81 after it has loaded the engine. No other command of the
82 engine will be called before it. It has to return the
83 number of passes this engine requires to fully process
84 the input document. This value has to be an integer num‐
85 ber greater or equal to one.
86 toc_initialize
88 This command is called at the beginning of every conver‐
89 sion run, as the first command of that run. Note that a
90 run is not a pass, but may consist of multiple passes.
91 See toc_numpasses. The command has to initialize the gen‐
92 eral state of the toc formatting engine, beyond the ini‐
93 tialization done during the load.
94 toc_setup n
96 This command is called at the beginning of each pass over
97 the input in a run. Its argument is the number of the
98 pass which has begun. Passes are counted from 1 upward.
99 The command has to set up the internal state of the toc
100 formatting engine for this particular pass.
101 toc_postprocess text
103 This command is called immediately after the last pass in
104 a run. Its argument is the result of the conversion gen‐
105 erated by that pass. It is provided to allow the engine
106 to perform any global last-ditch modifications of the
107 generated document. The text returned by this command
108 will be the final result of the conversion.
109 An engine for a format which requires no postprocessing
111 can simply return the argument without change.
112 toc_shutdown
114 This command is called at the end of every conversion
115 run. It is the last command called in a run. It has to
116 clean up of all the run-specific state in the toc format‐
117 ting engine. After the call the engine has to be in a
118 state which allows the initiation of another run without
119 fear that information from the last run is leaked into
120 this new run.
121 toc_listvariables
123 This command is called by a doctoc object after it has
124 loaded the engine (after toc_numpasses). It has to return
125 a list containing the names of the engine parameters pro‐
126 vided by the engine. This list can be empty.
127 toc_varset varname text
129 This command is called whenever the doctoc object wishes
130 to set an engine parameter to a particular value. The
131 parameter to change is specified by varname, the value to
132 set in text.
133 The command has to throw an error if an unknown varname
135 is used. Only the names returned by toc_listvariables are
136 considered known.
137 The values of all engine parameters have to persist
139 between passes and runs.
140 Formatting commands
143 The commands listed in this section are responsible for the con‐
144 version of the input into the wanted output. Their names are
145 the names of the associated markup command, with prefix fmt_
146 added to them. Not all markup commands have associated format‐
147 ting commands. The two exceptions are vset and include. These
148 markup commands are processed by the doctoc object itself.
149 A detailed documentation of the markup commands can be found in
151 the companion document doctoc_fmt. It is the formal specifica‐
152 tion of the doctoc format.
153 Note: The formatting commands can expect that they are only
155 called in an order allowed by the format specification.
156 fmt_plain_text text
158 This command has no associated markup command. It is
159 called for any plain text encountered by the processor in
160 the input. It has to perform any special processing
161 required for plain text. The text returned as its result
162 is added to the output. If no special processing is
163 required it has to simply return its argument without
164 change.
165 fmt_comment text
167 This command has to format the text as a comment and
168 return the formatted string. It has to return the empty
169 string if the output format has no way of formatting com‐
170 ments.
171 fmt_toc_begin text title
173 This command has to format the label text and the associ‐
174 ated title string as the start of the generated table of
175 contents and return the formatted string.
176 fmt_toc_end
178 This command has to generate the end of the generated ta‐
179 ble of contents and return the formatted string.
180 fmt_division_start text ?symfile?
182 This command has to open the beginning of a new section
183 in the generated table of contents and return the format‐
184 ted string. This opening may refer to another file, if
185 supported by the format, and specified through symfile.
186 An possible application of this would be to refer to a
187 smaller table of contents just for the section. The text
188 argument is the title of the new section.
189 fmt_division_end
191 This command has to close a section in the generated ta‐
192 ble of contents and return the formatted string.
193 fmt_item file text desc
195 This command has to format an individual toc element and
196 return the formatted string. The document referenced by
197 the element is specified through its symbolic name file,
198 whereas the label to use for the link is provided by
199 text. Use the command dt_fmap to convert the symbolic
200 name to the actual link. It is described in section
201 IMPORTED ENVIRONMENT. The last argument, desc, provides
202 a short descriptive text for the referenced document.
203 IMPORTED ENVIRONMENT
205 The implementation of an toc formatting engine can make the following
206 assumptions about the environment it is executed in:
207 [1] That it has full access to its own safe interpreter. In other
209 words, the engine cannot damage the other parts of the proces‐
210 sor, nor can it damage the filesystem.
211 [2] That the following commands are provided by the doctoc object
213 controlling the engine:
214 Doctools commands
216 dt_format
218 This command returns the name of the format cur‐
219 rently executing.
220 dt_fmap symfname
222 This command returns the actual name to use in the
223 output in place of the symbolic filename symfname.
224 It will return the unchanged input if no mapping
225 was found for symfname.
226 dt_source file
228 This command allows the toc formatting engine to
229 load additional tcl code. Only files which are
230 either in the same directory as the file contain‐
231 ing the engine, or below it, can be loaded. Trying
232 to load a file outside of this directory causes an
233 error.
234 Expander commands
237 All of the commands below are methods of the expander
238 object (without the prefix ex_) handling the current
239 input. This gives the engine limited access to the state
240 of the expander. Their arguments and results are
241 described in the documentation for the package expander.
242 ex_cappend
244 ex_cget
246 ex_cis
248 ex_cname
250 ex_cpop
252 ex_cpush
254 ex_cset
256 ex_lb
258 ex_rb
260 Other commands
263 The file "_toc_common.tcl" contains default implementa‐
264 tions of fmt_plaint_text and all the toc_ commands listed
265 in section EXPORTED COMMANDS. It resides in the subdi‐
266 rectory "mpformats" containing all the predefined for‐
267 mats. This means that all external formats (i.e. not pro‐
268 vided by the package doctools::toc) cannot use it immedi‐
269 ately, but have to have a copy at their location.
270
272 doctoc, doctoc_fmt
273
275 HTML, LaTeX, TMML, generic markup, markup, nroff, table of contents,
276 toc
277
279 Copyright (c) 2003-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
280doctools 1.0 doctoc_api(n)