1doctools_plugin_apiref(n)     Documentation tools    doctools_plugin_apiref(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools_plugin_apiref - doctools plugin API reference
9

SYNOPSIS

11       dt_copyright
12
13       dt_file
14
15       dt_mainfile
16
17       dt_fileid
18
19       dt_fmap symfname
20
21       dt_format
22
23       dt_imgdata key extensions
24
25       dt_imgdst key extensions
26
27       dt_imgsrc key extensions
28
29       dt_lnesting
30
31       dt_module
32
33       dt_read file
34
35       dt_source file
36
37       dt_user
38
39       ex_cappend text
40
41       ex_cget varname
42
43       ex_cis cname
44
45       ex_cname
46
47       ex_cpop cname
48
49       ex_cpush cname
50
51       ex_cset varname value
52
53       ex_lb ?newbracket?
54
55       ex_rb ?newbracket?
56
57       fmt_initialize
58
59       fmt_listvariables
60
61       fmt_numpasses
62
63       fmt_postprocess text
64
65       fmt_setup n
66
67       fmt_shutdown
68
69       fmt_varset varname text
70
71       fmt_plain_text text
72
73______________________________________________________________________________
74

DESCRIPTION

76       This  document  is intended for plugin writers, i.e. developers wishing
77       to write a doctools formatting engine for some output format X.
78
79       It specifies the interaction between the doctools package and its plug‐
80       ins,  i.e.  the  interface any doctools formatting engine has to comply
81       with.
82
83       This document deals with version 1 of the interface.
84
85       A reader who is on the other hand more interested in  the  markup  lan‐
86       guage  itself  should start with the doctools language introduction and
87       proceed from there to the formal specifications, i.e. the doctools lan‐
88       guage syntax and the doctools language command reference.
89

OVERVIEW

91       The  API  for  a  doctools formatting engine consists of two major sec‐
92       tions.
93
94       On the one side we have a set of commands through which the  plugin  is
95       able to query the frontend. These commands are provided by the frontend
96       and linked into the plugin interpreter.  Please  see  section  FRONTEND
97       COMMANDS for their detailed specification.
98
99       And on the other side the plugin has to provide its own set of commands
100       which will then be called by the frontend in a specific sequence  while
101       processing input. They, again, fall into two categories, management and
102       formatting.  Please see section PLUGIN COMMANDS and its subsections for
103       their detailed specification.
104

FRONTEND COMMANDS

106       This section specifies the set of commands through which a plugin, also
107       known as a doctools formatting engine, is able to query  the  frontend.
108       These  commands are provided by the frontend and linked into the plugin
109       interpreter.
110
111       I.e. a doctools formatting engine can assume that all of the  following
112       commands are present when any of its own commands (as specified in sec‐
113       tion PLUGIN COMMANDS) are executed.
114
115       Beyond that it can also assume that it has full access to its own  safe
116       interpreter  and thus is not able to damage the other parts of the pro‐
117       cessor, nor can it damage the filesystem.  It is however able to either
118       kill  or  hang  the  whole  process, by exiting, or running an infinite
119       loop.
120
121       Coming back to the imported commands, all the commands with prefix  dt_
122       provide  limited  access to specific parts of the frontend, whereas the
123       commands with prefix ex_ provide access to  the  state  of  the  textu‐
124       til::expander  object  which  does the main parsing of the input within
125       the frontend. These commands should not be except  under  very  special
126       circumstances.
127
128       dt_copyright
129              Query  command.  It  returns  a  string containing the copyright
130              information the doctools processor was configured with. The rel‐
131              evant option is -copyright).
132
133       dt_file
134              Query  command.  It returns the full path of the file containing
135              the input currently processed by the  engine.  This  may  be  an
136              included file.
137
138       dt_mainfile
139              Query  command.  It  returns  the full path of the toplevel file
140              containing the input currently processed by the engine.
141
142       dt_fileid
143              Query command. It returns the name of the  file  containing  the
144              input  currently  processed  by  the  engine,  without path, nor
145              extension.
146
147       dt_fmap symfname
148              Query command. It returns the actual pathname to use in the out‐
149              put  in  place of the symbolic filename symfname. It will return
150              the unchanged input if no mapping was established for symfname.
151
152              The required mappings are established with the method map  of  a
153              frontend, as explained in section OBJECT METHODS of the documen‐
154              tation for the package doctools.
155
156       dt_format
157              Query command. It returns the name of the format associated with
158              the doctools formatting engine.
159
160       dt_imgdata key extensions
161              Query  command.  Access  to  the  image  map. Looks for an image
162              recorded under the key and having on the specified extension. If
163              a  matching image is found its data is returned as the result of
164              the command. Otherwise an empty string is returned.
165
166       dt_imgdst key extensions
167              Query command. Access to the  image  map.  Looks  for  an  image
168              recorded under the key and having on the specified extension. If
169              a matching image is found its destination path in the output  is
170              returned as the result of the command. Otherwise an empty string
171              is returned.
172
173       dt_imgsrc key extensions
174              Query command. Access to the  image  map.  Looks  for  an  image
175              recorded under the key and having on the specified extension. If
176              a matching image is found its origin path  is  returned  as  the
177              result of the command. Otherwise an empty string is returned.
178
179       dt_lnesting
180              Query command. It returns the number of lists currently open.
181
182       dt_module
183              Query  command. It returns the name of the module the input cur‐
184              rently processed belongs to.
185
186       dt_read file
187              Controlled filesystem access. Returns contents of file for what‐
188              ever  use desired by the plugin.  Only files which are either in
189              the same directory as the file containing the engine,  or  below
190              it,  can be loaded. Trying to load a file outside of this direc‐
191              tory causes an error.
192
193       dt_source file
194              Controlled filesystem access. This command allows  the  doctools
195              formatting engine to load additional Tcl code it may need.  Only
196              files which are either in the same directory as  the  file  con‐
197              taining the engine, or below it, can be loaded. Trying to load a
198              file outside of this directory causes an error.
199
200       dt_user
201              Query command. It returns the name of the current user as  known
202              to  the  tcl interpreter the frontend controlling the formatting
203              engine resides in.
204
205       ex_cappend text
206              Appends a string to the output in  the  current  context.   This
207              command should rarely be used by macros or application code.
208
209       ex_cget varname
210              Retrieves  the value of variable varname, defined in the current
211              context.
212
213       ex_cis cname
214              Determines whether or not the name of  the  current  context  is
215              cname.
216
217       ex_cname
218              Returns the name of the current context.
219
220       ex_cpop cname
221              Pops a context from the context stack, returning all accumulated
222              output in that context.  The context must be named cname, or  an
223              error results.
224
225       ex_cpush cname
226              Pushes  a  context named cname onto the context stack.  The con‐
227              text must be popped by cpop before expansion ends  or  an  error
228              results.
229
230       ex_cset varname value
231              Sets variable varname to value in the current context.
232
233       ex_lb ?newbracket?
234              Returns  the  current value of the left macro expansion bracket;
235              this is for use as or within a macro, when the bracket needs  to
236              be  included in the output text.  If newbracket is specified, it
237              becomes the new bracket, and is returned.
238
239       ex_rb ?newbracket?
240              Returns the current value of the right macro expansion  bracket;
241              this  is for use as or within a macro, when the bracket needs to
242              be included in the output text.  If newbracket is specified,  it
243              becomes the new bracket, and is returned.
244

PLUGIN COMMANDS

246       The  plugin  has  to provide its own set of commands which will then be
247       called by the frontend in a specific sequence while  processing  input.
248       They  fall  into  two  categories,  management  and  formatting.  Their
249       expected names, signatures, and responsibilities are specified  in  the
250       following two subsections.
251
252   MANAGEMENT COMMANDS
253       The  management  commands a plugin has to provide are used by the fron‐
254       tend to
255
256       [1]    initialize and shutdown the plugin
257
258       [2]    determine the number of passes it has to make over the input
259
260       [3]    initialize and shutdown each pass
261
262       [4]    query and initialize engine parameters
263
264       After the plugin has been loaded and the frontend commands  are  estab‐
265       lished the commands will be called in the following sequence:
266
267
268                  fmt_numpasses -> n
269                  fmt_listvariables -> vars
270
271                  fmt_varset var1 value1
272                  fmt_varset var2 value2
273                  ...
274                  fmt_varset varK valueK
275                  fmt_initialize
276                  fmt_setup 1
277                  ...
278                  fmt_setup 2
279                  ...
280                  ...
281                  fmt_setup n
282                  ...
283                  fmt_postprocess
284                  fmt_shutdown
285                  ...
286
287       I.e. first the number of passes and the set of available engine parame‐
288       ters is established, followed by calls  setting  the  parameters.  That
289       second part is optional.
290
291       After  that  the  plugin is initialized, the specified number of passes
292       executed, the final result run through a global  post  processing  step
293       and  at last the plugin is shutdown again. This can be followed by more
294       conversions, restarting the sequence at fmt_varset.
295
296       In each of the passes, i.e. after the calls of fmt_setup  the  frontend
297       will  process  the  input and call the formatting commands as markup is
298       encountered. This means that the sequence  of  formatting  commands  is
299       determined by the grammar of the doctools markup language, as specified
300       in the doctools language syntax specification.
301
302       A different way of looking at the sequence is:
303
304       ·      First some basic parameters are determined.
305
306       ·      Then everything starting at the first fmt_varset to fmt_shutdown
307              forms  a  run, the formatting of a single input. Each run can be
308              followed by more.
309
310       ·      Embedded within each run we have one or more passes, each start‐
311              ing  with fmt_setup and going until either the next fmt_setup or
312              fmt_postprocess is reached.
313
314              If more than one pass is required to perform the formatting only
315              the  output  of the last pass is relevant. The output of all the
316              previous, preparatory passes is ignored.
317
318       The commands, their names, signatures,  and  responsibilities  are,  in
319       detail:
320
321       fmt_initialize
322              Initialization/Shutdown.   This  command is called at the begin‐
323              ning of every conversion run, as the first command of that  run.
324              Note  that  a  run  is  not  a pass, but may consist of multiple
325              passes.  It has to initialize the general state of  the  plugin,
326              beyond  the initialization done during the load. No return value
327              is expected, and any returned value is ignored.
328
329       fmt_listvariables
330              Initialization/Shutdown and Engine parameters.   Second  command
331              is  called  after  the plugin code has been loaded, i.e. immedi‐
332              ately after fmt_numpasses.  It has to return a  list  containing
333              the  names  of  the parameters the frontend can set to configure
334              the engine. This list can be empty.
335
336       fmt_numpasses
337              Initialization/Shutdown  and  Pass  management.   First  command
338              called  after  the plugin code has been loaded. No other command
339              of the engine will be called before it.  It has  to  return  the
340              number of passes this engine requires to fully process the input
341              document. This value has to be  an  integer  number  greater  or
342              equal to one.
343
344       fmt_postprocess text
345              Initialization/Shutdown.   This  command  is  called immediately
346              after the last pass in a run. Its argument is the result of  the
347              conversion  generated  by that pass. It is provided to allow the
348              engine to perform any global modifications of the generated doc‐
349              ument.  If  no post-processing is required for a specific format
350              the command has to just return the argument.
351
352              Expected to return a value, the final result of  formatting  the
353              input.
354
355       fmt_setup n
356              Initialization/Shutdown  and  Pass  management.  This command is
357              called at the beginning of each pass over the input  in  a  run.
358              Its  argument  is the number of the pass which has begun. Passes
359              are counted from 1 upward.  The command has to set up the inter‐
360              nal  state  of  the  plugin  for this particular pass. No return
361              value is expected, and any returned value is ignored.
362
363       fmt_shutdown
364              Initialization/Shutdown.  This command is called at the  end  of
365              every conversion run. It is the last command called in a run. It
366              has to clean up of all the run-specific  state  in  the  plugin.
367              After  the call the engine has to be in a state which allows the
368              initiation of another run without fear that information from the
369              last  run  is  leaked  into  this  new  run.  No return value is
370              expected, and any returned value is ignored.
371
372       fmt_varset varname text
373              Engine parameters.  This command is called by  the  frontend  to
374              set an engine parameter to a particular value.  The parameter to
375              change is specified by varname, the value to set in text.
376
377              The command has to throw an error if an unknown varname is used.
378              Only  the names returned by fmt_listvariables have to be consid‐
379              ered as known.
380
381              The values of all engine  parameters  have  to  persist  between
382              passes and runs.
383
384   FORMATTING COMMANDS
385       The formatting commands have to implement the formatting for the output
386       format, for all the markup commands of the  doctools  markup  language,
387       except  lb,  rb,  vset, include, and comment. These exceptions are pro‐
388       cessed by the frontend and are never seen by the plugin.  In  return  a
389       command  for the formatting of plain text has to be provided, something
390       which has no markup in the input at all.
391
392       This means, that each of the 49 markup commands specified in  the  doc‐
393       tools  language  command reference and outside of the set of exceptions
394       listed above has an equivalent formatting command which takes the  same
395       arguments  as  the  markup command and whose name is the name of markup
396       command with the prefix fmt_ added to it.
397
398       All commands are expected to format their input in  some  way  per  the
399       semantics  specified  in  the  command reference and to return whatever
400       part of this that they deem necessary as their result,  which  will  be
401       added to the output.
402
403       To  avoid  essentially duplicating the command reference we do not list
404       any of the command here and simply refer the  reader  to  the  doctools
405       language  command  reference  for  their signature and description. The
406       sole exception is the plain text formatter,  which  has  no  equivalent
407       markup command.
408
409       The  calling sequence of formatting commands is not as rigid as for the
410       management commands, but determined by  the  grammar  of  the  doctools
411       markup  language, as specified in the doctools language syntax specifi‐
412       cation.
413
414       fmt_plain_text text
415              No associated markup command.
416
417              Called by the frontend for any plain  text  encountered  in  the
418              input. It has to perform any and all special processing required
419              for plain text.
420
421              The formatted text is expected as the result of the command, and
422              added to the output. If no special processing is required it has
423              to simply return its argument without change.
424

BUGS, IDEAS, FEEDBACK

426       This document, and the package it describes, will  undoubtedly  contain
427       bugs  and  other problems.  Please report such in the category doctools
428       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
429       also  report any ideas for enhancements you may have for either package
430       and/or documentation.
431
432       When proposing code changes, please provide unified diffs, i.e the out‐
433       put of diff -u.
434
435       Note  further  that  attachments  are  strongly  preferred over inlined
436       patches. Attachments can be made by going  to  the  Edit  form  of  the
437       ticket  immediately  after  its  creation, and then using the left-most
438       button in the secondary navigation bar.
439

SEE ALSO

441       doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doc‐
442       tools_lang_intro, doctools_lang_syntax
443

KEYWORDS

445       document,  formatter,  formatting  engine,  manpage,  markup,  semantic
446       markup
447

CATEGORY

449       Documentation tools
450
452       Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
453
454
455
456
457tcllib                                1.1            doctools_plugin_apiref(n)
Impressum