libsablot/doc/apidoc/sablot.xml

   1 <?xml version='1.0'?>
   2 <API id='Sablotron Guide and'>
   3
   4   <FOOT>
   5     &amp;copy; 2002 Ginger Alliance<BR/>
   6     <I>revision 02-11-04</I><BR/>
   7   </FOOT>
   8
   9   <!-- General -->
  10
  11   <ENTRY id='.Introduction'>
  12     <TYPE value='.General'/>
  13     <SUMMARY>
  14       Sablotron is an XML processor implementing XPath 1.0, XSLT 1.0 and
  15       DOM Level2. It also includes some other features such as XSLT debugger,
  16       SXP (access to external documents via callbacks) or EXSLT support.
  17     </SUMMARY>
  18     <DESCRIPTION>
  19       Sablotron is a single shared library written in C++ (sablot.dll
  20       or libsablot.so.x.xx). It provides a native C API; APIs for Perl, PHP,
  21       Python, Ruby and other languages are available through wrappers (not
  22       part of the Sablotron project). See <S>gingerall.org</S> for more
  23       information on Sablotron wrappers. Sablotron can also be used from the
  24       command line via a simple interface called <C>sabcmd</C>.<P/>
  25
  26       Sablotron implements the following W3C recommendations:
  27       <S>XPath 1.0</S>, <S>XSLT 1.0</S> and <S>DOM Level2</S>. See
  28       <C>.Known Issues</C> for details on deviations from the specs.
  29       Go to <C>.Sablotron DOM</C> for more information on Sablotron DOM
  30       Level 2 interface.
  31       <P/>
  32       Sablotron also include an XPath Processor (SXP) working with virtual DOM
  33       objects accessed via user-defined (DOM-like) callback functions. The C
  34       API to SXP is described in a separate <S>SXP Reference</S> guide.
  35       <P/>
  36       A relevant subset of EXSLT extensions is supported by Sablotron. See
  37       <C>.Extensions</C> for details.
  38       <P/>
  39       Third-party libraries Sablotron depends on and libraries that can be
  40       linked by Sablotron optionally are listed in <C>.Dependencies</C>.
  41       <P/>
  42       The latest Sablotron sources can be downloaded from <S>gingerall.org</S>.
  43       For instructions on how to build the sources, refer to the accompanying
  44       INSTALL file. The <S>gingerall.org</S> site also includes links to other
  45       documentation, FAQs, mailing lists, CVS, bugzilla, lxr and other
  46       Sablotron-related resources. Sablotron is an open source project and
  47       everyone is invited to join it.
  48     </DESCRIPTION>
  49     <EXTERNALREF name="XPath 1.0" value="http://www.w3.org/TR/xpath"/>
  50     <EXTERNALREF name="XSLT 1.0" value="http://www.w3.org/TR/xslt"/>
  51     <EXTERNALREF name="DOM Level2" value="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/"/>
  52     <EXTERNALREF name="SXP Reference" value="http://www.gingerall.org/ga/html/sxp/complete-frameset.html"/>
  53     <EXTERNALREF name="gingerall.org" value="http://www.gingerall.org"/>
  54   </ENTRY>
  55
  56   <ENTRY id='.Extensions'>
  57     <TYPE value='.General'/>
  58     <SUMMARY>
  59       Sablotron supports a number of EXSLT extensions.
  60     </SUMMARY>
  61     <DESCRIPTION>
  62       Sablotron recognizes the extension element
  63       <B>funct:script</B> (xmlns:funct="http://exslt.org/functions")
  64       to run ECMAScript (JavaScript) functions as suggested by
  65       <S>EXSLT.org</S>. Extension functions have a read-only DOM access
  66       to the main XML document and to
  67       node-sets passed as arguments. The implementation follows the
  68       ECMAScript/DOM2 Language Binding defined in <S>XSLT 1.1</S>,
  69       Appendix C3, and <S>DOM Level2</S>, Appendix E. See Sablotron
  70       <S>Extensions API Reference</S> guide to get more details on how to use
  71       DOM methods from JS extension functions.
  72       <P/>
  73       Sablotron also supports <B>exsl:document</B> element
  74       (xmlns:exsl="http://exslt.org/common") to produce multiple output
  75       documents.
  76       <P/>
  77       In addition to the standard output methods (xml, html and text), it is
  78       possible to output xhtml. Documents output using this method obey the
  79       XHTML 1.0 rules (in particular, all empty elements are closed).
  80       To choose the method, use <B>xsl:output method='xhtml'</B>.
  81     </DESCRIPTION>
  82     <EXTERNALREF name="Extensions API Reference" value="http://www.gingerall.org/ga/html/jsdom-ref/complete-frameset.html"/>
  83     <EXTERNALREF name="EXSLT.org" value="http://www.exslt.org"/>
  84     <EXTERNALREF name="XSLT 1.1" value="http://www.w3.org/TR/xslt11/"/>
  85     <EXTERNALREF name="DOM Level2" value="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/"/>
  86   </ENTRY>
  87
  88   <ENTRY id='.Known Issues'>
  89     <TYPE value='.General'/>
  90     <SUMMARY>
  91       There are some known minor distinctions from W3C specifications.
  92     </SUMMARY>
  93     <DESCRIPTION>
  94       <B>XPath 1.0</B><BR/>
  95         * id() function not implemented.<BR/>
  96       <P/>
  97       <B>XSLT 1.0</B><BR/>
  98         * embedded stylesheets don't work,<BR/>
  99         * some illegal operations with RTFs are allowed,<BR/>
 100         * case-order attribute of xsl:sort not supported.<BR/>
 101       <P/>
 102       <B>DOM Level2</B><BR/>
 103         * Document.docElementsByTagName not implemented,<BR/>
 104         * Document.docElementsByTagNameNS not implemented,<BR/>
 105         * node name lists may be accessed with the item() function only
 106           not as array items,<BR/>
 107         * NamedNodeMap.getNamedItemsNS not implemented.<BR/>
 108       <P/>
 109       <B>Other issues:</B><BR/>
 110         * the 'xhtml' output method is different from what is suggested
 111       in XSLT 2.0 WD,<BR/>
 112         * all parameters must be passed in utf-8 encoded.<BR/>
 113     </DESCRIPTION>
 114     <EXTERNALREF name="XPath 1.0" value="http://www.w3.org/TR/xpath"/>
 115     <EXTERNALREF name="XSLT 1.0" value="http://www.w3.org/TR/xslt"/>
 116     <EXTERNALREF name="DOM Level2" value="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/"/>
 117   </ENTRY>
 118
 119   <ENTRY id='.License'>
 120     <TYPE value='.General'/>
 121     <SUMMARY>
 122       Sablotron licensing terms and Copyright
 123     </SUMMARY>
 124     <DESCRIPTION>
 125       Sablotron is  subject to the Mozilla Public License Version 1.1
 126       (the <S>MPL</S>). Alternatively, Sablotron may be used under the
 127       terms of the GNU General Public License Version 2 or later (the
 128       <S>GPL</S>), in which case the provisions of the GPL are applicable
 129       instead of those of the MPL.
 130       <P/>
 131       The Sablotron project has been originated and is maintained
 132       by Ginger Alliance. Portions created by Ginger Alliance are
 133       Copyright Ginger Alliance s.r.o. Portions created by other
 134       contributors are Copyright of these contributors.
 135       All rights are reserved.
 136     </DESCRIPTION>
 137     <EXTERNALREF name="MPL" value="http://www.mozilla.org/MPL/MPL-1.1.html"/>
 138     <EXTERNALREF name="GPL" value="http://www.gnu.org/licenses/gpl.html"/>
 139   </ENTRY>
 140
 141   <ENTRY id='.Usage'>
 142     <TYPE value='.General'/>
 143     <SUMMARY>
 144       Examples of how to use the native API of Sablotron.
 145     </SUMMARY>
 146     <DESCRIPTION>
 147       The first example shows the simplest way to run a transformation with
 148       two files. The second example parses trees explicitly and makes them
 149       available for further processing. In this example, the source XML document
 150       and the XSLT stylesheet are already loaded in strings (my_xsl_ptr,
 151       my_xml_ptr). To work with URIs, use <C>SablotParseStylesheet</C> and
 152       <C>SablotParse</C> instead of <C>SablotParseStylesheetBuffer</C> and
 153       <C>SablotParseBuffer</C>.
 154     </DESCRIPTION>
 155     <SYNTAX>
 156 EXAMPLE 1: a simple transformation
 157
 158 SablotSituation S;
 159 SablotHandle proc;
 160
 161 SablotCreateSituation(&amp;S);
 162 SablotCreateProcessorForSituation(S, &amp;proc);
 163
 164 SablotRunProcessorGen(S, proc, "my_sheet.xsl", "my_data.xml", "arg:/out");
 165
 166 char * result;
 167 SablotGetResultArg(proc, "arg:/out", &amp;result);
 168
 169 ...
 170
 171 SablotFree(result);
 172 SablotDestroyProcessor(proc);
 173 SablotDestroySituation(S);
 174
 175 EXAMPLE 2: a transformation with reusable parsed trees
 176
 177 SablotSituation S;
 178 SablotHandle proc;
 179 SDOM_Document xsl, xml;
 180
 181 SablotCreateSituation(&amp;S);
 182 SablotParseStylesheetBuffer(S, my_xsl_ptr, &amp;xsl);
 183 SablotParseBuffer(S, my_xml_ptr, &amp;xml);
 184
 185 SablotCreateProcessorForSituation(S, &amp;proc);
 186 SablotAddArgTree(S, proc, "sheet", xsl);
 187 SablotAddArgTree(S, proc, "data", xml);
 188
 189 SablotRunProcessorGen(S, proc, "arg:/sheet", "arg:/data", "arg:/out");
 190
 191 char * result;
 192 SablotGetResultArg(proc, "arg:/out", &amp;result);
 193
 194 ...
 195
 196 SablotFree(result);
 197 SablotDestroyDocument(xsl);
 198 SablotDestroyDocument(xml);
 199 SablotDestroyProcessor(proc);
 200 SablotDestroySituation(S);
 201     </SYNTAX>
 202   </ENTRY>
 203
 204   <ENTRY id='sabcmd'>
 205     <TYPE value='.General'/>
 206     <SUMMARY>
 207       sabcmd is a command line interface to Sablotron library.
 208     </SUMMARY>
 209     <SYNTAX>
 210 sabcmd [options] &amp;lt;stylesheet&amp;gt; [&amp;lt;input&amp;gt; [&amp;lt;output&amp;gt;]] [assignments]
 211 sabcmd [options] -batch-xml &amp;lt;input&amp;gt; [&amp;lt;stylesheet&amp;gt; [&amp;lt;output&amp;gt;]]+ [assignments]
 212 sabcmd [options] -batch-xsl &amp;lt;stylesheet&amp;gt; [&amp;lt;input&amp;gt; [&amp;lt;output&amp;gt;]]+ [assignments]
 213     </SYNTAX>
 214     <DESCRIPTION>
 215       <B>sabcmd</B> is a command line interface to Sablotron XSLT processor.
 216       You can use is to transform XML files with XSLT stylesheets.
 217       <P/>
 218       The only required parameter is a stylesheet; this is a URI of
 219       an XSLT stylesheet to be used for the transformation process. If you
 220       omit an input file, the standard input is used. In addition, you can
 221       specify an output file. If no output file is given, the output is sent to
 222       the standard output.
 223       <P/>
 224       sabcmd can also run in a batch mode to process single input file with
 225       multiple stylesheets (--batch-xml) or to apply a stylesheet to multiple
 226       input files (--batch-xsl).
 227       <P/>
 228       <B>Assignments</B> allow to pass parameters and named buffers to the
 229       processor. The assignments have always the form of
 230       <C>name1=value1 name2=value2 ...</C>
 231       where name is either an ASCII string for named buffers or an ASCII string
 232       with the leading '$' sign for parameters. (Note that you need to use the
 233       right quotes to prevent the shell interpreter from performing an expansion
 234       of variables).
 235       <P/>
 236       <B>OPTIONS</B>
 237       <BR/>
 238       Option can be of two forms - short or long. If some options have
 239       values, the values are separated with a whitespace for short options
 240       and with a equal sign ('=') for long options.
 241       <C>-L mylog.log</C> is the same as <C>--log-file=mylog.log</C>
 242       <P/>
 243       <B>COMMON OPTIONS</B>
 244       <BR/>
 245       <C>-x, --batch-xml</C> - multiple stylesheets, single input file
 246       <BR/>
 247       <C>-s, --batch-xsl</C> - multiple input files, single stylesheet
 248       <BR/>
 249       <C>-b, --base=NAME</C> - set the hard base URI to NAME
 250       <BR/>
 251       <C>--debug-options</C> - display the information on debugging options
 252       <BR/>
 253       <C>-?, --help</C> - display this help message
 254       <BR/>
 255       <C>-L, --log-file=NAME</C> - set the log file, turns logging on
 256       <BR/>
 257       <C>-m, --measure</C> - measure the time of processing
 258       <BR/>
 259       <C>-v, --version</C> - display the version information
 260       <P/>
 261       <B>DEBUG OPTIONS</B>
 262       <BR/>
 263       <C>--debug</C> - display results of the command line parse
 264       <BR/>
 265       <C>-t, --times=COUNT</C> - run sabcmd the specified number of times
 266       <BR/>
 267       <C>-f, --flags</C> - pass flags given to SablotSetOptions()
 268       <BR/>
 269       <C>-F, --use-SPF</C> - use SablotProcessFiles()
 270       <BR/>
 271       <C>-S, --use-SPS</C> - use SablotProcessStrings(). Give 2 args (stylesheet,
 272       input). Precede each by @.
 273       <BR/>
 274       <C>--use-SPS-on-files</C> - use SablotProcessStrings() on the contents of
 275       the given files.
 276       <P/>
 277       <B>ENVIRONMENT</B>
 278       <BR/>
 279       When the <B>xsl:sort</B> instruction is used without the 'lang' attribute,
 280       common locale related environment variables apply..
 281     </DESCRIPTION>
 282   </ENTRY>
 283
 284   <ENTRY id='.Debugging XSLT'>
 285     <TYPE value='.General'/>
 286     <SUMMARY>
 287       Sablotron can be used as XSLT debugger.
 288     </SUMMARY>
 289     <DESCRIPTION>
 290       Run <C>'sabcmd --debugger'</C> to invoke the debugger. Then, you can trace
 291       execution of your templates. The only point, where the debugger can stop
 292       the execution is the element start.
 293       <P/>
 294     </DESCRIPTION>
 295     <SYNTAX>
 296 These commands can be used from the debugger command line:
 297
 298 Processed data:
 299   data filename        - sets the data file
 300   param name value     - sets the external parameter
 301   P                    - lists all params
 302   PP                   - clears all params
 303   sheet filename       - sets the stylesheet
 304 Breakpoints:
 305   break filename:line  - sets the breakpoint
 306   bstat                - shows breakpoint stats (total/enabled/break)
 307   B                    - lists all breakpoints
 308   condition num cond   - for the breakpoint NUM sets the condition COND
 309   del num              - deletes the breakpoint NUM
 310   disable num          - toggles the breakpoint number NUM
 311   D                    - deletes all breakpoints
 312   ignore num count     - ignores the breakpoint NUM for COUNT times
 313 Execution control:
 314   continue             - continues the execution
 315   finish               - finishes the current node parent
 316   kill                 - stops the processing immediately
 317   next                 - goes to the next sibling
 318   run                  - runs the processor
 319   step                 - continues until the next element
 320   templ                - continues until the next template executed
 321 Evaluation:
 322   eval                 - evaluates the XPath expression
 323   x [list | num]       - examines the current context
 324 Miscellaneous:
 325   batch filename       - loads the command set for file
 326   help                 - prints this help
 327   output               - toggles output on/off
 328   point                - shows where you are
 329   quit                 - quites the debugger
 330     </SYNTAX>
 331     <NOTE>
 332       <B>Abbreviations</B><BR/>
 333       You need to type as few letters to specify the command as is
 334       needed to recognize, what you mean. The most frequent command may
 335       be run with single letter not caring, whether another command
 336       starts with this letter. The `s' abbrev runs the `step' command
 337       rather the `sheet'.
 338       <P/>
 339       <B>Emacs Integration</B><BR/>
 340       There is an Emacs library available. You may use it to debug
 341       your stylesheets in Emacs directly. You need to grab the sabdbg.el
 342       from the Sablotron source tree and to add a couple of lines into
 343       your .emacs file. Look at doc/misc/DEBUGGER file in Sablotron
 344       distribution for more details.
 345     </NOTE>
 346   </ENTRY>
 347
 348   <ENTRY id='.Dependencies'>
 349     <TYPE value='.General'/>
 350     <SUMMARY>
 351       Third-party libraries that must be or can be linked to Sablotron.
 352     </SUMMARY>
 353     <DESCRIPTION>
 354       <S>Expat</S> - an XML parser Sablotron depends on. This is the only
 355       MANDATORY dependence. Sablotron looks for Expat during the
 356       configuration. Expat is a standard part of many operating systems and
 357       is available for all systems where Sablotron can run.
 358       Expat is distributed under a MIT-styled license.
 359       <P/>
 360       <S>Iconv</S> - a GNU encoding library you need if you want to use more
 361       encodings/charsets than these supported by Sablotron internally.
 362       See <C>.Encodings</C> for more details. Sablotron looks for Iconv
 363       during the configuration but it still compiles when not found.
 364       Iconv is a standard part of many operating systems and is available
 365       for all systems where Sablotron can run. Iconv is released under terms
 366       of GNU LGPL license.
 367       <P/>
 368       <S>JavaScript</S> - JS C (SpiderMonkey) engine by Mozilla is needed
 369       to run XSLT extension function. See <C>.Extensions</C> for details.
 370       Linking JavaScript is optional (./configure --enable-javascript).
 371       JS engine is available for all systems where Sablotron can run.
 372       Mozilla's C implementation of JavaScript is distributed under terms
 373       of the MPL license.
 374       <P/>
 375       <S>Readline</S> - a GNU library providing the XSLT debugger with
 376       functions to easily work with the command line. You may want to
 377       link Readline if you compile Sablotron with XSLT debugger
 378       (./configure --enable-debugger --with-readline). Without Readline,
 379       the debugger still works, but you can't use user-friendly features
 380       such as the command-line history.
 381       Readline is distributed under the GNU GPL license, thus you must
 382       use Sablotron under GPL (this is one of two possible alternatives, see
 383       <C>.License</C> for details) if you want to link Readline. Export
 384       SABLOT_GPL=1 environment in order to express your decision.
 385     </DESCRIPTION>
 386     <EXTERNALREF name="Expat" value="http://expat.sourceforge.net"/>
 387     <EXTERNALREF name="Iconv" value="http://www.gnu.org/software/libiconv/"/>
 388     <EXTERNALREF name="JavaScript" value="http://www.mozilla.org/js/"/>
 389     <EXTERNALREF name="Readline" value="http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html"/>
 390   </ENTRY>
 391
 392   <!-- Implementation notes -->
 393   <ENTRY id='.Handlers'>
 394     <TYPE value='.Implementation Notes'/>
 395     <SUMMARY>
 396       It is possible for the user to supply the following handlers to
 397       Sablotron.
 398     </SUMMARY>
 399     <DESCRIPTION>
 400     <B>message handler</B> - to bypass the default way of displaying
 401       error and warning messages and logging,<BR/>
 402     <B>scheme handler</B> - to retrieve documents whose URI use an
 403       unsupported scheme,<BR/>
 404     <B>streaming handler</B> - an expat-like interface to the XML document
 405       which is the result of the processing,<BR/>
 406     <B>encoding handler</B> - to handle an unsupported encoding<BR/>
 407     <B>'miscellaneous' handler</B> - which will probably serve as
 408       a collections of odd callbacks.<P/>
 409
 410       The handlers are set using <C>SablotRegHandler</C>. For details
 411       concerning the interface of these handlers, consult the header
 412       files sablot.h and shandler.h.<P/>
 413
 414     </DESCRIPTION>
 415   </ENTRY>
 416
 417   <ENTRY id='.Encodings'>
 418     <TYPE value='.Implementation Notes'/>
 419     <SUMMARY>
 420       Sablotron supports a number of input/output encodings and charsets;
 421       either internally or through the iconv library.
 422     </SUMMARY>
 423     <DESCRIPTION>
 424       Sablotron handles encoding conversions with the help of iconv library.
 425       As a standard part of glibc, iconv is automatically available on many
 426       Unix-based systems (including Linux). It's available for most other
 427       platforms where Sablotron runs (Windows, Solaris, MacOS X, FreeBSD, etc).
 428       See <C>.Dependencies</C> for more details on iconv.
 429       <P/>
 430       With iconv installed on your system, you can use any encoding it supports
 431       (that is, almost any encoding whatsoever) for both the input and the output
 432       documents.
 433       <P/>
 434       If iconv is not available, encodings may still be supported internally
 435       by Sablotron. At present, the list is of such encodings is rather short:
 436       UTF-8, UTF-16, ASCII, iso-8859-1, iso-8859-2 and windows-1250 on input,
 437       UTF-8 only on output.
 438       <P/>
 439       Lastly, a user has the option to implement a custom encoding conversion
 440       handler, which will be asked to perform any unsupported conversion. See
 441       <C>.Handlers</C> for details.
 442       <P/>
 443       The default input and output encoding is in all cases UTF-8.
 444     </DESCRIPTION>
 445   </ENTRY>
 446
 447   <ENTRY id='.URIs'>
 448     <TYPE value='.Implementation Notes'/>
 449     <SUMMARY>
 450       Sablotron can handle two URI schemes natively: 'file' and 'arg'.
 451     </SUMMARY>
 452     <DESCRIPTION>
 453       Only two URI schemes are built-in: 'file' and 'arg' (see
 454       <C>.Named buffers</C>). Moreover, it is possible to use the function
 455       <C>SablotRegHandler</C> to register an external scheme handler which
 456       will receive requests in all other schemes. See <C>.Handlers</C>
 457       and sablot.h and shandler.h files for details.
 458       <P/>
 459       Relative URI references are resolved in conformance to RFC 2396.
 460       The base URI is well defined when the relative reference appears inside
 461       a XML document; when invoking <C>sabcmd</C>, the base URI is taken to
 462       correspond to the current working directory.
 463       <P/>
 464       When specifying filenames, the following rules are in effect:<BR/>
 465       * specify the "file:" scheme for any standard files, i.e. refer to
 466       stdin as file://stdin etc.<BR/>
 467       * slashes and backslashes work equally fine, in Windows as well as
 468       Linux.<BR/>
 469       * to include a drive letter under Windows (e.g. C:\doc.xml), it is
 470       necessary to say file://c:/doc.xml.<BR/>
 471     </DESCRIPTION>
 472   </ENTRY>
 473
 474   <ENTRY id='.Named buffers'>
 475     <TYPE value='.Implementation Notes'/>
 476     <SUMMARY>
 477       Sablotron can store XML strings and parsed trees to so called
 478       named buffers.
 479     </SUMMARY>
 480     <DESCRIPTION>
 481       Sablotron introduces an URI scheme 'arg:' which enables one to use
 482       strings and parsed trees in named memory buffers. Named buffers are
 483       can be set using <C>SablotAddArgBuffer</C> or <C>SablotAddArgTree</C>
 484       functions. The content of buffers can be accessed with the
 485       <C>document()</C> function or <C>xsl:include/import</C> instructions
 486       (e.g. document('arg:/my_buffer')/root).
 487       <P/>
 488       The buffer names
 489       can have a tree-like structure so that a relative reference from a
 490       document in a buffer can be resolved as pointing to another buffer.
 491       <P/>
 492       For instance, if we invoke Sablotron specifying that a buffer named
 493       <C>/mybuf/1</C> contains the string "&amp;lt;a>contents&amp;lt;/a>",
 494       then the expression <C>document('arg:/mybuf/1')/a</C> has string-value
 495       <C>"contents"</C>. If the document in <C>arg:/mybuf/1</C> contained
 496       a relative URI reference <C>"../theirbuf/2"</C> then this would be
 497       resolved as pointing to <C>"arg:/theirbuf/2"</C>.
 498     </DESCRIPTION>
 499   </ENTRY>
 500
 501   <ENTRY id='.Errors and logs'>
 502     <TYPE value='.Implementation Notes'/>
 503     <SUMMARY>
 504       Sablotron writes error and warning messages to stderr, and does no logging
 505       by default, but this behavior can be changed.
 506     </SUMMARY>
 507     <DESCRIPTION>
 508       The name of the log file to be used can be specified with
 509       <C>SablotSetLog</C>. Besides, you can use <C>SablotRegHandler</C>
 510       to override the default message handling. The handler you register
 511       will receive all messages in a structured form that's easy to process
 512       and filter. For details, see <C>.Handlers</C>.
 513     </DESCRIPTION>
 514   </ENTRY>
 515
 516   <!-- Types -->
 517   <ENTRY id='SablotHandle'>
 518     <TYPE value='Types'/>
 519     <SUMMARY>
 520       Defines the basic abstract handle for manipulation of Sablotron
 521       internals.
 522     </SUMMARY>
 523     <SYNTAX>
 524 typedef void *SablotHandle;
 525     </SYNTAX>
 526     <DESCRIPTION>
 527       Actually this type is the <C>void*</C>, but you should never
 528       rely on this.
 529     </DESCRIPTION>
 530   </ENTRY>
 531
 532   <ENTRY id='SDOM_Document'>
 533     <TYPE value='Types'/>
 534     <SUMMARY>
 535       Handle for manipulation of Sablotron DOM documents.
 536     </SUMMARY>
 537     <SYNTAX>
 538 typedef void *SDOM_Document;
 539     </SYNTAX>
 540     <DESCRIPTION>
 541       You may use this type, if you need to deal with Sablotron
 542       internal representation of the XML data model. There is a
 543       DOM-like set of functions defined for such manipulation in the
 544       sdom.h file.
 545     </DESCRIPTION>
 546   </ENTRY>
 547
 548   <ENTRY id='SablotSituation'>
 549     <TYPE value='Types'/>
 550     <SUMMARY>
 551       Handle for manipulation of the Situation object.
 552     </SUMMARY>
 553     <SYNTAX>
 554 typedef void *SablotSituation;
 555     </SYNTAX>
 556     <DESCRIPTION>
 557       The Situation object is the very basic object you have to deal
 558       with. See the <C>.Usage</C>
 559     </DESCRIPTION>
 560     <SEEALSO value='SablotCreateSituation'/>
 561   </ENTRY>
 562
 563   <!-- Functions -->
 564   <ENTRY id='SablotCreateDocument'>
 565     <TYPE value='Functions'/>
 566     <SUMMARY>
 567       Creates a new DOM document.
 568     </SUMMARY>
 569     <SYNTAX>
 570 int SablotCreateDocument(SablotSituation S,
 571       SDOM_Document *D);
 572       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 573       <PARAM name='D' type='SDOM_Document*'>The new handle goes
 574       here</PARAM>
 575     </SYNTAX>
 576     <DESCRIPTION>
 577       The returned handle may be used to manipulate the internal DOM
 578       document with the set of API defined in the sdom.h file.
 579     </DESCRIPTION>
 580     <SEEALSO value='SDOM_Document'/>
 581   </ENTRY>
 582
 583   <ENTRY id='SablotParse'>
 584     <TYPE value='Functions'/>
 585     <SUMMARY>
 586       Parses a XML file into the internal structure.
 587     </SUMMARY>
 588     <SYNTAX>
 589 int SablotParse(SablotSituation S,
 590       const char *uri,
 591       SDOM_Document *D);
 592       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 593       <PARAM name='uri' type='const char*'>URI of the file</PARAM>
 594       <PARAM name='D' type='SDOM_Document*'>The new handle goes
 595       here</PARAM>
 596     </SYNTAX>
 597     <DESCRIPTION>
 598       Sablotron parses the document given by the URI and sets the D to
 599       a new handle value. Returns FALSE on success.
 600     </DESCRIPTION>
 601   </ENTRY>
 602
 603   <ENTRY id='SablotParseBuffer'>
 604     <TYPE value='Functions'/>
 605     <SUMMARY>
 606       Parses a XML string into the internal structure.
 607     </SUMMARY>
 608     <SYNTAX>
 609 int SablotParseBuffer(SablotSituation S,
 610       const char *buffer,
 611       SDOM_Document *D);
 612       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 613       <PARAM name='buffer' type='const char*'>string to be parsed</PARAM>
 614       <PARAM name='D' type='SDOM_Document*'>The node handle goes here</PARAM>
 615     </SYNTAX>
 616     <DESCRIPTION>
 617       Sablotron parses given string and creates a new document
 618       handle. The last parameter obtains the handle. Function returns
 619       FALSE on success.
 620     </DESCRIPTION>
 621   </ENTRY>
 622
 623   <ENTRY id='SablotParseStylesheet'>
 624     <TYPE value='Functions'/>
 625     <SUMMARY>
 626       Parses a XSLT stylesheet from file.
 627     </SUMMARY>
 628     <SYNTAX>
 629 int SablotParseStylesheet(SablotSituation S,
 630       const char *uri,
 631       SDOM_Document *D);
 632       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 633       <PARAM name='uri' type='const char*'>data URI</PARAM>
 634       <PARAM name='D' type='SDOM_Document*'>The result goes here</PARAM>
 635     </SYNTAX>
 636     <DESCRIPTION>
 637       Does the same as <C>SablotParse</C>, but document parsed with
 638       this function may be used as the stylesheet for the XSLT
 639       processing.
 640     </DESCRIPTION>
 641     <NOTE>
 642       You should not modify a document created by this function, if
 643       you want to use it for the processing. It might (and probably
 644       would) lead to the processor crash.
 645     </NOTE>
 646   </ENTRY>
 647
 648   <ENTRY id='SablotParseStylesheetBuffer'>
 649     <TYPE value='Functions'/>
 650     <SUMMARY>
 651       Parses a XSLT stylesheet from a buffer.
 652     </SUMMARY>
 653     <SYNTAX>
 654 int SablotParseStylesheetBuffer(SablotSituation S,
 655       const char *buffer,
 656       SDOM_Document *D);
 657       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 658       <PARAM name='buffer' type='const char*'>XML string</PARAM>
 659       <PARAM name='D' type='SDOM_Document*'>The result goes here</PARAM>
 660     </SYNTAX>
 661     <DESCRIPTION>
 662       Does the same as <C>SablotParseBuffer</C>, but document parsed with
 663       this function may be used as the stylesheet for the XSLT
 664       processing.
 665     </DESCRIPTION>
 666     <NOTE>
 667       You should not modify a document created by this function, if
 668       you want to use it for the processing. It might (and probably
 669       would) lead to the processor crash.
 670     </NOTE>
 671   </ENTRY>
 672
 673   <ENTRY id='SablotLockDocument'>
 674     <TYPE value='Functions'/>
 675     <SUMMARY>
 676       Lock the document before the processing.
 677     </SUMMARY>
 678     <SYNTAX>
 679 int SablotLockDocument(SablotSituation S,
 680       SDOM_Document D);
 681       <PARAM name='S' type='SablotSituation'>Situation object</PARAM>
 682       <PARAM name='D' type='SDOM_Document'>document to be locked</PARAM>
 683     </SYNTAX>
 684     <DESCRIPTION>
 685       Actually this function doesn't perform any locking in the common
 686       sense of the word, but updates some internal values needed for
 687       the processing.
 688     </DESCRIPTION>
 689     <NOTE>
 690       You SHOULD call this function whenever you changed the DOM
 691       document before the processing. You don't need this, if you just
 692       parsed the document (no modification).
 693     </NOTE>
 694   </ENTRY>
 695
 696   <ENTRY id='SablotDestroyDocument'>
 697     <TYPE value='Functions'/>
 698     <SUMMARY>
 699       Frees the internal document and all resources.
 700     </SUMMARY>
 701     <SYNTAX>
 702 int SablotDestroyDocument(SablotSituation S,
 703       SDOM_Document D);
 704       <PARAM name='S' type='SablotSituation'>Situation object</PARAM>
 705       <PARAM name='D' type='SDOM_Document'>document to be destroyed</PARAM>
 706     </SYNTAX>
 707     <DESCRIPTION>
 708       This function frees the internal document representation and all
 709       resources allocated.
 710     </DESCRIPTION>
 711   </ENTRY>
 712
 713   <ENTRY id='SablotAddParam'>
 714     <TYPE value='Functions'/>
 715     <SUMMARY>
 716       Sets the value of the parameter for the processing.
 717     </SUMMARY>
 718     <SYNTAX>
 719 int SablotAddParam(SablotSituation S,
 720       void *processor_,
 721       const char *paramName,
 722       const char *paramValue);
 723       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 724       <PARAM name='processor_' type='void*'>Processor handle</PARAM>
 725       <PARAM name='paramName' type='const char*'>parameter name</PARAM>
 726       <PARAM name='paramValue' type='const char*'>parameter value</PARAM>
 727     </SYNTAX>
 728     <DESCRIPTION>
 729       Use this function if you need to set the external parameter for
 730       the upcoming processing (for the top-level &lt;xsl:param>).
 731     </DESCRIPTION>
 732     <NOTE>
 733       Currently the parameter value MUST be UTF-8 encoded.
 734     </NOTE>
 735     <SEEALSO value='SablotRunProcessorGen'/>
 736     <SEEALSO value='.Usage'/>
 737   </ENTRY>
 738
 739   <ENTRY id='SablotAddArgBuffer'>
 740     <TYPE value='Functions'/>
 741     <SUMMARY>
 742       Adds a buffer containing the XML data as the named argument.
 743     </SUMMARY>
 744     <SYNTAX>
 745 int SablotAddArgBuffer(SablotSituation S,
 746       void *processor_,
 747       const char *argName,
 748       const char *bufferValue);
 749       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 750       <PARAM name='processor_' type='void*'>Processor handle</PARAM>
 751       <PARAM name='argName' type='const char*'>argument name</PARAM>
 752       <PARAM name='bufferValue' type='const char*'>XML data</PARAM>
 753     </SYNTAX>
 754     <DESCRIPTION>
 755       This API adds the named buffer to the list of arguments maintained
 756       by the processor instance. Named arguments may be used either
 757       while the processed data are specified (e.g. in
 758       <C>SablotRunProcessorGen</C> or in the document() XSLT function.
 759     </DESCRIPTION>
 760     <SEEALSO value='SablotAddArgTree'/>
 761   </ENTRY>
 762
 763   <ENTRY id='SablotAddArgTree'>
 764     <TYPE value='Functions'/>
 765     <SUMMARY>
 766       Adds the pre-parsed tree as the named argument.
 767     </SUMMARY>
 768     <SYNTAX>
 769 int SablotAddArgTree(SablotSituation S,
 770       void *processor_,
 771       const char *argName,
 772       SDOM_Document tree);
 773       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 774       <PARAM name='processor_' type='void*'>Processor handle</PARAM>
 775       <PARAM name='argName' type='const char*'>argument name</PARAM>
 776       <PARAM name='tree' type='SDOM_Document'>tree handle</PARAM>
 777     </SYNTAX>
 778     <DESCRIPTION>
 779       This function adds the named pre-parsed tree to the list of
 780       arguments maintained by the processor instance. Named arguments
 781       may be used either while the processed data are specified
 782       (e.g. in <C>SablotRunProcessorGen</C> or in the document() XSLT
 783       function.
 784     </DESCRIPTION>
 785     <SEEALSO value='SablotAddArgBuffer'/>
 786   </ENTRY>
 787
 788   <ENTRY id='SablotRunProcessorGen'>
 789     <TYPE value='Functions'/>
 790     <SUMMARY>
 791       Runs the processor.
 792     </SUMMARY>
 793     <SYNTAX>
 794 int SablotRunProcessorGen(SablotSituation S,
 795       void *processor_,
 796       const char *sheetURI,
 797       const char *inputURI,
 798       const char *resultURI);
 799       <PARAM name='S' type='SablotSituation'>Sablotron handle</PARAM>
 800       <PARAM name='processor_' type='void*'>Processor handle</PARAM>
 801       <PARAM name='sheetURI' type='const char*'>stylesheet URI</PARAM>
 802       <PARAM name='inputURI' type='const char*'>data URI</PARAM>
 803       <PARAM name='resultURI' type='const char*'>result URI</PARAM>
 804     </SYNTAX>
 805     <DESCRIPTION>
 806       This call runs the processing on the given data. Data are
 807       specified by URIs; what may be either of URI to the file, org
 808       the 'arg:' scheme URI (see <C>SablotAddArg</C>). Other URI
 809       schemes may be recognized if the appropriate handler is
 810       set.<BR/>
 811     </DESCRIPTION>
 812     <SEEALSO value='.Usage'/>
 813     <SEEALSO value='.Handlers'/>
 814     <SEEALSO value='SablotGetResultArg'/>
 815   </ENTRY>
 816
 817   <ENTRY id='SablotRunProcessorExt'>
 818     <TYPE value='Functions'/>
 819     <SUMMARY>
 820       Runs the processor on the external document.
 821     </SUMMARY>
 822     <SYNTAX>
 823 int SablotRunProcessorExt(SablotSituation S,
 824       void *processor_,
 825       const char *sheetURI,
 826       const char *resultURI,
 827       NodeHandle doc);
 828       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 829       <PARAM name='processor_' type='void*'>Processor handle</PARAM>
 830       <PARAM name='sheetURI' type='const char*'>stylesheet URI</PARAM>
 831       <PARAM name='resultURI' type='const char*'>result URI</PARAM>
 832       <PARAM name='doc' type='NodeHandle'>external root node</PARAM>
 833     </SYNTAX>
 834     <DESCRIPTION>
 835       This function acts as the SablotRunProcessorGen does. The
 836       difference is, that the data processed are provided by the
 837       external DOM provider.
 838       <BR/>
 839       See SXP documentation for more details on DOM providers etc.
 840     </DESCRIPTION>
 841     <NOTE>
 842       Currently there is no way to start the processing on an
 843       'ordinary' document and access the external data via some XSLT
 844       function (opposite to the document() function).
 845     </NOTE>
 846     <SEEALSO value='SablotRunProcessorGen'/>
 847   </ENTRY>
 848
 849   <ENTRY id='SablotCreateSituation'>
 850     <TYPE value='Functions'/>
 851     <SUMMARY>
 852       Creates a situation object handle.
 853     </SUMMARY>
 854     <SYNTAX>
 855 int SablotCreateSituation(SablotSituation *sPtr);
 856       <PARAM name='sPtr' type='SablotSituation*'>the result goes here</PARAM>
 857     </SYNTAX>
 858     <DESCRIPTION>
 859       This call creates a situation object. This object servers for
 860       several reasons like error processing, option settings etc. Most
 861       of API functions take the situation handle as their first parameter.
 862     </DESCRIPTION>
 863     <SEEALSO value='.Usage'/>
 864   </ENTRY>
 865
 866   <ENTRY id='SablotSetOptions'>
 867     <TYPE value='Functions'/>
 868     <SUMMARY>
 869       Sets miscellaneous processing options.
 870     </SUMMARY>
 871     <SYNTAX>
 872 int SablotSetOptions(SablotSituation S,
 873       int flag);
 874       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 875       <PARAM name='flag' type='int'>new options</PARAM>
 876     </SYNTAX>
 877     <DESCRIPTION>
 878       Options may be any bitwise combination of following:
 879       <P/>
 880       <C>SAB_NO_ERROR_REPORTING</C> suppresses the invocation of the
 881       messages handler (if registered)
 882       <P/>
 883       <C>SAB_PARSE_PUBLIC_ENTITIES</C> makes parser to resolve public
 884       external entities
 885       <P/>
 886       <C>SAB_DISABLE_ADDING_META</C> suppresses the generation of the
 887       META tag (HTML output method)
 888       <P/>
 889       <C>SAB_DISABLE_STRIPPING</C> suppresses the whitespace stripping
 890       (on data files only)
 891       <P/>
 892       <C>SAB_IGNORE_DOC_NOT_FOUND</C> doesn't consider unresolved
 893       documents (the document() function) to be lethal
 894       <P/>
 895       <C>SAB_FILES_TO_HANDLER</C> do not read 'file' URI internally,
 896       but pass it into the scheme handler
 897     </DESCRIPTION>
 898   </ENTRY>
 899
 900   <ENTRY id='SablotGetOptions'>
 901     <TYPE value='Functions'/>
 902     <SUMMARY>
 903       Get current procesor options.
 904     </SUMMARY>
 905     <SYNTAX>
 906 int SablotSetOptions(SablotSituation S,
 907       int flag);
 908       <PARAM name='S' type='SablotSituation'>Situation handle</PARAM>
 909     </SYNTAX>
 910     <DESCRIPTION>
 911       Options may be any bitwise combination of following:
 912       <P/>
 913       <C>SAB_NO_ERROR_REPORTING</C> suppresses the invocation of the
 914       messages handler (if registered)
 915       <P/>
 916       <C>SAB_PARSE_PUBLIC_ENTITIES</C> makes parser to resolve public
 917       external entities
 918       <P/>
 919       <C>SAB_DISABLE_ADDING_META</C> suppresses the generation of the
 920       META tag (HTML output method)
 921       <P/>
 922       <C>SAB_DISABLE_STRIPPING</C> suppresses the whitespace stripping
 923       (on data files only)
 924       <P/>
 925       <C>SAB_IGNORE_DOC_NOT_FOUND</C> doesn't consider unresolved
 926       documents (the document() function) to be lethal
 927       <P/>
 928       <C>SAB_FILES_TO_HANDLER</C> do not read 'file' URI internally,
 929       but pass it into the scheme handler
 930     </DESCRIPTION>
 931   </ENTRY>
 932
 933   <ENTRY id='SablotClearSituation'>
 934     <TYPE value='Functions'/>
 935     <SUMMARY>
 936       Clears the status of the situation.
 937     </SUMMARY>
 938     <SYNTAX>
 939 int SablotClearSituation(SablotSituation S);
 940       <PARAM name='S' type='SablotSituation'>situation handle</PARAM>
 941     </SYNTAX>
 942     <DESCRIPTION>
 943       Clear all error info stored with the situation.
 944     </DESCRIPTION>
 945   </ENTRY>
 946
 947 <!-- not implemented
 948   <ENTRY id='SablotGetErrorURI'>
 949     <TYPE value='Functions'/>
 950     <SUMMARY>
 951       Gets the last error URI.
 952     </SUMMARY>
 953     <SYNTAX>
 954 const char *SablotGetErrorURI(SablotSituation S);
 955       <PARAM name='S' type='SablotSituation'>situation handle</PARAM>
 956     </SYNTAX>
 957     <DESCRIPTION>
 958       Returns the URI related to the location of the most recent
 959       error. you must not free this string.
 960     </DESCRIPTION>
 961   </ENTRY>
 962
 963   <ENTRY id='SablotGetErrorLine'>
 964     <TYPE value='Functions'/>
 965     <SUMMARY>
 966       Gets the last error line number.
 967     </SUMMARY>
 968     <SYNTAX>
 969 int SablotGetErrorLine(SablotSituation S);
 970       <PARAM name='S' type='SablotSituation'>desc</PARAM>
 971     </SYNTAX>
 972     <DESCRIPTION>
 973       Returns the line number of the most recent error occured.
 974     </DESCRIPTION>
 975   </ENTRY>
 976
 977   <ENTRY id='SablotGetErrorMsg'>
 978     <TYPE value='Functions'/>
 979     <SUMMARY>
 980       Gets the error message.
 981     </SUMMARY>
 982     <SYNTAX>
 983 const char *SablotGetErrorMsg(SablotSituation S);
 984       <PARAM name='S' type='SablotSituation'>desc</PARAM>
 985     </SYNTAX>
 986     <DESCRIPTION>
 987       <C>SablotGetErrorMsg</C>
 988     </DESCRIPTION>
 989   </ENTRY>
 990 -->
 991
 992   <ENTRY id='SablotDestroySituation'>
 993     <TYPE value='Functions'/>
 994     <SUMMARY>
 995       Destroys the situation object.
 996     </SUMMARY>
 997     <SYNTAX>
 998 int SablotDestroySituation(SablotSituation S);
 999       <PARAM name='S' type='SablotSituation'>desc</PARAM>
1000     </SYNTAX>
1001     <DESCRIPTION>
1002       Destroys the situation object. You should call this function as
1003       the very last call.
1004     </DESCRIPTION>
1005   </ENTRY>
1006
1007   <ENTRY id='SablotCreateProcessor'>
1008     <TYPE value='Functions'/>
1009     <SUMMARY>
1010       Creates the processor object.
1011     </SUMMARY>
1012     <SYNTAX>
1013 int SablotCreateProcessor(SablotHandle *processorPtr);
1014       <PARAM name='processorPtr' type='SablotHandle*'>the result goes here</PARAM>
1015     </SYNTAX>
1016     <DESCRIPTION>
1017       This API creates the processor instance. See <C>.Usage</C> for
1018       the details to be done.
1019     </DESCRIPTION>
1020     <NOTE>
1021       This function is slightly obsoleted with
1022       <C>SablotCreateProcessorForSituation</C>, since we suppose you'd
1023       prefer the situation object recently created with
1024       <C>SablotCreateSituation</C>.
1025     </NOTE>
1026   </ENTRY>
1027
1028   <ENTRY id='SablotCreateProcessorForSituation'>
1029     <TYPE value='Functions'/>
1030     <SUMMARY>
1031       Creates the processor instance and associate it with the
1032       situation object.
1033     </SUMMARY>
1034     <SYNTAX>
1035 int SablotCreateProcessorForSituation(SablotSituation S,
1036       void **processorPtr);
1037       <PARAM name='S' type='SablotSituation'>situation handle</PARAM>
1038       <PARAM name='processorPtr' type='void**'>the result goes here</PARAM>
1039     </SYNTAX>
1040     <DESCRIPTION>
1041       Use this function if you want to create a processor instance and
1042       associate it with the given situation object. This call is
1043       preferred over <C>SablotCreateProcessor</C>.
1044     </DESCRIPTION>
1045   </ENTRY>
1046
1047   <ENTRY id='SablotDestroyProcessor'>
1048     <TYPE value='Functions'/>
1049     <SUMMARY>
1050       Destroys the processor object.
1051     </SUMMARY>
1052     <SYNTAX>
1053 int SablotDestroyProcessor(SablotHandle processor_);
1054       <PARAM name='processor_' type='SablotHandle'>Processor handle</PARAM>
1055     </SYNTAX>
1056     <DESCRIPTION>
1057       Destroys processor and all associated resources.
1058     </DESCRIPTION>
1059   </ENTRY>
1060
1061   <ENTRY id='SablotRunProcessor'>
1062     <DEPRECATED/>
1063     <TYPE value='Functions'/>
1064     <SUMMARY>
1065       Runs the XSLT transformation.
1066     </SUMMARY>
1067     <SYNTAX>
1068 int SablotRunProcessor(SablotHandle processor_,
1069       const char *sheetURI,
1070       const char *inputURI,
1071       const char *resultURI,
1072       const char* *params,
1073       const char* *argument);
1074       <PARAM name='processor_' type='SablotHandle'>processor handle</PARAM>
1075       <PARAM name='sheetURI' type='const char*'>sheet URI</PARAM>
1076       <PARAM name='inputURI' type='const char*'>data URI</PARAM>
1077       <PARAM name='resultURI' type='const char*'>result URI</PARAM>
1078       <PARAM name='params' type='const char**'>parameters</PARAM>
1079       <PARAM name='argument' type='const char**'>arguments</PARAM>
1080     </SYNTAX>
1081     <DESCRIPTION>
1082       This API is deprecated and shouldn't be used. Use
1083       <C>SablotRunProcessorGen</C> instead.
1084     </DESCRIPTION>
1085   </ENTRY>
1086
1087   <ENTRY id='SablotGetResultArg'>
1088     <TYPE value='Functions'/>
1089     <SUMMARY>
1090       Gets the result argument.
1091     </SUMMARY>
1092     <SYNTAX>
1093 int SablotGetResultArg(SablotHandle processor_,
1094       const char *argURI,
1095       char* *argValue);
1096       <PARAM name='processor_' type='SablotHandle'>Processor handle</PARAM>
1097       <PARAM name='argURI' type='const char*'>argument name</PARAM>
1098       <PARAM name='argValue' type='char**'>the result goes here</PARAM>
1099     </SYNTAX>
1100     <DESCRIPTION>
1101       This API is used to pull the data output to the 'arg:' scheme URI
1102       location. This happens during the transformation e.g. with
1103       <C>SablotRunProcessorGen</C>
1104       <P/>
1105       This function allocates new buffer for you. You have to free
1106       its memory with <C>SablotFree</C>, after you use it no more.
1107     </DESCRIPTION>
1108   </ENTRY>
1109
1110   <ENTRY id='SablotFreeResultArgs'>
1111     <TYPE value='Functions'/>
1112     <SUMMARY>
1113       Frees all internal result arguments.
1114     </SUMMARY>
1115     <SYNTAX>
1116 int SablotFreeResultArgs(SablotHandle processor_);
1117       <PARAM name='processor_' type='SablotHandle'>processor handle</PARAM>
1118     </SYNTAX>
1119     <DESCRIPTION>
1120       This call frees all memory associated with the output of the
1121       most recent transformation. You don't have to make this call,
1122       destroying the processor takes care as well as new
1123       transformation invocation.
1124     </DESCRIPTION>
1125   </ENTRY>
1126
1127   <ENTRY id='SchemeHandler'>
1128     <TYPE value='Types'/>
1129     <SUMMARY>
1130       This type is used to provide the Sablotron engine with a
1131       callback structure for a scheme handler.
1132     </SUMMARY>
1133     <SYNTAX>
1134       typedef int
1135       SchemeHandlerGetAll(void *userData,
1136           SablotHandle processor_,
1137           const char *scheme, const char *rest,
1138           char **buffer, int *byteCount);
1139
1140       typedef int
1141       SchemeHandlerFreeMemory(void *userData,
1142           SablotHandle processor_,
1143           char *buffer);
1144
1145       typedef int
1146       SchemeHandlerOpen(void *userData,
1147           SablotHandle processor_,
1148           const char *scheme,
1149           const char *rest, int *handle);
1150
1151       typedef int
1152       SchemeHandlerGet(void *userData,
1153           SablotHandle processor_,
1154           int handle, char *buffer, int *byteCount);
1155
1156       typedef int
1157       SchemeHandlerPut(void *userData,
1158           SablotHandle processor_,
1159           int handle, const char *buffer, int *byteCount);
1160
1161       typedef int
1162       SchemeHandlerClose(void *userData,
1163           SablotHandle processor_,
1164           int handle);
1165
1166       typedef struct
1167       {
1168           SchemeHandlerGetAll *getAll;
1169           SchemeHandlerFreeMemory *freeMemory;
1170           SchemeHandlerOpen *open;
1171           SchemeHandlerGet *get;
1172           SchemeHandlerPut *put;
1173           SchemeHandlerClose *close;
1174       } SchemeHandler;
1175     </SYNTAX>
1176     <NOTE>See the shandler.h file for more comments.</NOTE>
1177   </ENTRY>
1178
1179   <ENTRY id='MessageHandler'>
1180     <TYPE value='Types'/>
1181     <SUMMARY>
1182       This type is used to provide the Sablotron engine with a
1183       callback structure for a message handler.
1184     </SUMMARY>
1185     <SYNTAX>
1186       typedef MH_ERROR
1187       MessageHandlerMakeCode(
1188           void *userData, SablotHandle processor_,
1189           int severity, unsigned short facility, unsigned short code);
1190
1191       typedef MH_ERROR
1192       MessageHandlerLog(
1193           void *userData, SablotHandle processor_,
1194           MH_ERROR code, MH_LEVEL level, char **fields);
1195
1196       typedef MH_ERROR
1197       MessageHandlerError(void *userData, SablotHandle processor_,
1198           MH_ERROR code, MH_LEVEL level, char **fields);
1199
1200       typedef struct
1201       {
1202           MessageHandlerMakeCode *makeCode;
1203           MessageHandlerLog *log;
1204           MessageHandlerError *error;
1205       } MessageHandler;
1206     </SYNTAX>
1207     <NOTE>See the shandler.h file for more comments.</NOTE>
1208   </ENTRY>
1209
1210   <ENTRY id='SAXHandler'>
1211     <TYPE value='Types'/>
1212     <SUMMARY>
1213       This type is used to provide the Sablotron engine with a
1214       callback structure for a SAX handler.
1215     </SUMMARY>
1216     <SYNTAX>
1217       typedef SAX_RETURN
1218       SAXHandlerStartDocument(void* userData, SablotHandle processor_);
1219
1220       typedef SAX_RETURN
1221       SAXHandlerStartElement(void* userData, SablotHandle processor_,
1222           const char* name, const char** atts);
1223
1224       typedef SAX_RETURN
1225       SAXHandlerEndElement(void* userData, SablotHandle processor_,
1226           const char* name);
1227
1228       typedef SAX_RETURN
1229       SAXHandlerStartNamespace(void* userData, SablotHandle processor_,
1230           const char* prefix, const char* uri);
1231
1232       typedef SAX_RETURN
1233       SAXHandlerEndNamespace(void* userData, SablotHandle processor_,
1234           const char* prefix);
1235
1236       typedef SAX_RETURN
1237       SAXHandlerComment(void* userData, SablotHandle processor_,
1238           const char* contents);
1239
1240       typedef SAX_RETURN
1241       SAXHandlerPI(void* userData, SablotHandle processor_,
1242           const char* target, const char* contents);
1243
1244       typedef SAX_RETURN
1245       SAXHandlerCharacters(void* userData, SablotHandle processor_,
1246           const char* contents, int length);
1247
1248       typedef SAX_RETURN
1249       SAXHandlerEndDocument(void* userData, SablotHandle processor_);
1250
1251
1252       typedef struct
1253       {
1254           SAXHandlerStartDocument     *startDocument;
1255           SAXHandlerStartElement      *startElement;
1256           SAXHandlerEndElement        *endElement;
1257           SAXHandlerStartNamespace    *startNamespace;
1258           SAXHandlerEndNamespace      *endNamespace;
1259           SAXHandlerComment           *comment;
1260           SAXHandlerPI                *processingInstruction;
1261           SAXHandlerCharacters        *characters;
1262           SAXHandlerEndDocument       *endDocument;
1263       } SAXHandler;
1264
1265     </SYNTAX>
1266     <NOTE>This is not a real SAX interface; think about it as about
1267     a SAX-like interface. See the shandler.h file for more
1268     comments.</NOTE>
1269   </ENTRY>
1270
1271   <ENTRY id='MiscHandler'>
1272     <TYPE value='Types'/>
1273     <SUMMARY>
1274       This type is used to provide the Sablotron engine with a
1275       callback structure for a custom handler.
1276     </SUMMARY>
1277     <SYNTAX>
1278       typedef void
1279       MiscHandlerDocumentInfo(void* userData, SablotHandle processor_,
1280           const char *contentType, const char *encoding);
1281
1282       typedef struct
1283       {
1284           MiscHandlerDocumentInfo     *documentInfo;
1285       } MiscHandler;
1286     </SYNTAX>
1287     <NOTE>See the shandler.h file for more comments.</NOTE>
1288   </ENTRY>
1289
1290   <ENTRY id='EncHandler'>
1291     <TYPE value='Types'/>
1292     <SUMMARY>
1293       This type is used to provide the Sablotron engine with a
1294       callback structure for an encoding handler.
1295     </SUMMARY>
1296     <SYNTAX>
1297       typedef EHDescriptor
1298       EncHandlerOpen(void* userData,
1299           SablotHandle processor_,
1300           int direction, const char *encoding);
1301
1302       typedef EHResult
1303       EncHandlerConv(void* userData, SablotHandle processor_,
1304           EHDescriptor cd, const char** inbuf, size_t *inbytesleft,
1305           char ** outbuf, size_t *outbytesleft);
1306
1307       typedef int
1308       EncHandlerClose(void* userData, SablotHandle processor_,
1309           EHDescriptor cd);
1310
1311       typedef struct
1312       {
1313           EncHandlerOpen      *open;
1314           EncHandlerConv      *conv;
1315           EncHandlerClose     *close;
1316       } EncHandler;
1317     </SYNTAX>
1318     <NOTE>See the shandler.h file for more comments.</NOTE>
1319   </ENTRY>
1320
1321   <ENTRY id='SablotRegHandler'>
1322     <TYPE value='Functions'/>
1323     <SUMMARY>
1324       Registers new handler.
1325     </SUMMARY>
1326     <SYNTAX>
1327 int SablotRegHandler(SablotHandle processor_,
1328       HandlerType type,
1329       void *handler,
1330       void *userData);
1331       <PARAM name='processor_' type='SablotHandle'>processor handle</PARAM>
1332       <PARAM name='type' type='HandlerType'>handler type</PARAM>
1333       <PARAM name='handler' type='void*'>pointer to the handler struct</PARAM>
1334       <PARAM name='userData' type='void*'>user data</PARAM>
1335       </SYNTAX>
1336     <DESCRIPTION>
1337       Registers one of available handlers. The handler type is either
1338       of HLR_MESSAGE, HLR_SCHEME, HLR_SAX, HLR_MISC, HLR_ENC. The
1339       ``handler'' parameter point to the callback structure.
1340       <P/>The stucture format depends on the handler sype specified.
1341       Possible callbacks structures are:<BR/>
1342       <C>SchemeHandler</C>, <C>MessageHandler</C>, <C>SAXHandler</C>,
1343       <C>MiscHandler</C>, <C>EncHandler</C>.
1344
1345       <P/>See <C>.Handlers</C> for more.
1346     </DESCRIPTION>
1347
1348   </ENTRY>
1349
1350   <ENTRY id='SablotUnregHandler'>
1351     <TYPE value='Functions'/>
1352     <SUMMARY>
1353       Unregisters the handler.
1354     </SUMMARY>
1355     <SYNTAX>
1356 int SablotUnregHandler(SablotHandle processor_,
1357       HandlerType type,
1358       void *handler,
1359       void *userData);
1360       <PARAM name='processor_' type='SablotHandle'>processor handle</PARAM>
1361       <PARAM name='type' type='HandlerType'>handler type</PARAM>
1362       <PARAM name='handler' type='void*'>handler</PARAM>
1363       <PARAM name='userData' type='void*'>user data</PARAM>
1364     </SYNTAX>
1365     <DESCRIPTION>
1366       Registers one of available handlers. See <C>.Handlers</C> for more.
1367     </DESCRIPTION>
1368   </ENTRY>
1369
1370   <ENTRY id='SablotSetBase'>
1371     <TYPE value='Functions'/>
1372     <SUMMARY>
1373       Sets base URI.
1374     </SUMMARY>
1375     <SYNTAX>
1376 int SablotSetBase(SablotHandle processor_,
1377       const char *theBase);
1378       <PARAM name='processor_' type='SablotHandle'>processor handle</PARAM>
1379       <PARAM name='theBase' type='const char*'>base URI</PARAM>
1380     </SYNTAX>
1381     <DESCRIPTION>
1382       Sets the base URI. All relatives URIs resolved during the
1383       processing are evaluated against this one.
1384     </DESCRIPTION>
1385   </ENTRY>
1386
1387   <ENTRY id='SablotSetBaseForScheme'>
1388     <TYPE value='Functions'/>
1389     <SUMMARY>
1390       Sets the base URI for given scheme.
1391     </SUMMARY>
1392     <SYNTAX>
1393 int SablotSetBaseForScheme(void *processor_,
1394       const char *scheme,
1395       const char *base);
1396       <PARAM name='processor_' type='void*'>processor handle</PARAM>
1397       <PARAM name='scheme' type='const char*'>desc</PARAM>
1398       <PARAM name='base' type='const char*'>desc</PARAM>
1399     </SYNTAX>
1400     <DESCRIPTION>
1401       <C>SablotSetBaseForScheme</C>
1402     </DESCRIPTION>
1403   </ENTRY>
1404
1405   <ENTRY id='SablotSetLog'>
1406     <TYPE value='Functions'/>
1407     <SUMMARY>
1408       Sets the log filename.
1409     </SUMMARY>
1410     <SYNTAX>
1411 int SablotSetLog(SablotHandle processor_,
1412       const char *logFilename,
1413       int logLevel);
1414       <PARAM name='processor_' type='SablotHandle'>desc</PARAM>
1415       <PARAM name='logFilename' type='const char*'>desc</PARAM>
1416       <PARAM name='logLevel' type='int'>desc</PARAM>
1417     </SYNTAX>
1418     <DESCRIPTION>
1419       The logLevel parameter is currently not used. Pass NULL for
1420       logFilename to turn logging off (default).
1421     </DESCRIPTION>
1422   </ENTRY>
1423
1424   <ENTRY id='SablotProcess'>
1425     <DEPRECATED/>
1426     <TYPE value='Functions'/>
1427     <SUMMARY>
1428       <C>SablotProcess</C>
1429     </SUMMARY>
1430     <SYNTAX>
1431 int SablotProcess(const char *sheetURI,
1432       const char *inputURI,
1433       const char *resultURI,
1434       const char* *params,
1435       const char* *arguments,
1436       char* *resultArg);
1437       <PARAM name='sheetURI' type='const char*'>desc</PARAM>
1438       <PARAM name='inputURI' type='const char*'>desc</PARAM>
1439       <PARAM name='resultURI' type='const char*'>desc</PARAM>
1440       <PARAM name='params' type='const char**'>desc</PARAM>
1441       <PARAM name='arguments' type='const char**'>desc</PARAM>
1442       <PARAM name='resultArg' type='char**'>desc</PARAM>
1443     </SYNTAX>
1444     <DESCRIPTION>
1445       <C>SablotProcess</C>
1446     </DESCRIPTION>
1447   </ENTRY>
1448
1449   <ENTRY id='SablotProcessFiles'>
1450     <DEPRECATED/>
1451     <TYPE value='Functions'/>
1452     <SUMMARY>
1453       <C>SablotProcessFiles</C>
1454     </SUMMARY>
1455     <SYNTAX>
1456 int SablotProcessFiles(const char *styleSheetName,
1457       const char *inputName,
1458       const char *resultName);
1459       <PARAM name='styleSheetName' type='const char*'>desc</PARAM>
1460       <PARAM name='inputName' type='const char*'>desc</PARAM>
1461       <PARAM name='resultName' type='const char*'>desc</PARAM>
1462     </SYNTAX>
1463     <DESCRIPTION>
1464       <C>SablotProcessFiles</C>
1465     </DESCRIPTION>
1466   </ENTRY>
1467
1468   <ENTRY id='SablotProcessStrings'>
1469     <DEPRECATED/>
1470     <TYPE value='Functions'/>
1471     <SUMMARY>
1472       <C>SablotProcessStrings</C>
1473     </SUMMARY>
1474     <SYNTAX>
1475 int SablotProcessStrings(const char *styleSheetStr,
1476       const char *inputStr,
1477       char* *resultStr);
1478       <PARAM name='styleSheetStr' type='const char*'>desc</PARAM>
1479       <PARAM name='inputStr' type='const char*'>desc</PARAM>
1480       <PARAM name='resultStr' type='char**'>desc</PARAM>
1481     </SYNTAX>
1482     <DESCRIPTION>
1483       <C>SablotProcessStrings</C>
1484     </DESCRIPTION>
1485   </ENTRY>
1486
1487   <ENTRY id='SablotProcessStringsWithBase'>
1488     <DEPRECATED/>
1489     <TYPE value='Functions'/>
1490     <SUMMARY>
1491       <C>SablotProcessStringsWithBase</C>
1492     </SUMMARY>
1493     <SYNTAX>
1494 int SablotProcessStringsWithBase(const char *styleSheetStr,
1495       const char *inputStr,
1496       char* *resultStr,
1497       const char *theHardBase);
1498       <PARAM name='styleSheetStr' type='const char*'>desc</PARAM>
1499       <PARAM name='inputStr' type='const char*'>desc</PARAM>
1500       <PARAM name='resultStr' type='char**'>desc</PARAM>
1501       <PARAM name='theHardBase' type='const char*'>desc</PARAM>
1502     </SYNTAX>
1503     <DESCRIPTION>
1504       <C>SablotProcessStringsWithBase</C>
1505     </DESCRIPTION>
1506   </ENTRY>
1507
1508   <ENTRY id='SablotFree'>
1509     <TYPE value='Functions'/>
1510     <SUMMARY>
1511       <C>SablotFree</C> frees the buffer formerly allocated by the engine.
1512     </SUMMARY>
1513     <SYNTAX>
1514 int SablotFree(char *resultStr);
1515       <PARAM name='resultStr' type='char*'>desc</PARAM>
1516     </SYNTAX>
1517     <DESCRIPTION>
1518       Use the <C>SablotFree</C> function whenever you finish a work
1519       with a Sablotron generated API. Typically, do it after the
1520       <C>SablotrGetResultArg</C> is called. Some DOM-access
1521       functions allocate buffers too.
1522     </DESCRIPTION>
1523   </ENTRY>
1524
1525   <ENTRY id='SablotClearError'>
1526     <TYPE value='Functions'/>
1527     <SUMMARY>
1528       Clears the 'pending error' flag.
1529     </SUMMARY>
1530     <SYNTAX>
1531 int SablotClearError(SablotHandle processor_);
1532       <PARAM name='processor_' type='SablotHandle'>desc</PARAM>
1533     </SYNTAX>
1534     <DESCRIPTION>
1535       Clears the 'pending error' flag for this instance of Sablotron.
1536     </DESCRIPTION>
1537   </ENTRY>
1538
1539   <ENTRY id='SablotGetMsgText'>
1540     <TYPE value='Functions'/>
1541     <SUMMARY>
1542       <C>SablotGetMsgText</C> return a constant pointer to the message
1543       for the given error code.
1544     </SUMMARY>
1545     <SYNTAX>
1546 const char *SablotGetMsgText(int code);
1547       <PARAM name='code' type='int'>desc</PARAM>
1548     </SYNTAX>
1549     <DESCRIPTION>
1550       The value returned is typically a format string (contains C
1551       ``printf'' formatting specifiers). You need more info (code
1552       dependent) to get a full message).
1553     </DESCRIPTION>
1554   </ENTRY>
1555
1556   <ENTRY id='SablotSetInstanceData'>
1557     <TYPE value='Functions'/>
1558     <SUMMARY>
1559       <C>SablotSetInstanceData</C> associates user-defined pointer to
1560       the processor instance.
1561     </SUMMARY>
1562     <SYNTAX>
1563 void SablotSetInstanceData(SablotHandle processor_,
1564       void *idata);
1565       <PARAM name='processor_' type='SablotHandle'>desc</PARAM>
1566       <PARAM name='idata' type='void*'>desc</PARAM>
1567     </SYNTAX>
1568     <DESCRIPTION>
1569       You may use this call to store any pointer-like value with the
1570       processor. You may obtain this value later usinf the
1571       <C>SablotGetInstanceData</C>. This is usefull for miscellaneous
1572       wrapper implementations etc.
1573     </DESCRIPTION>
1574   </ENTRY>
1575
1576   <ENTRY id='SablotGetInstanceData'>
1577     <TYPE value='Functions'/>
1578     <SUMMARY>
1579       <C>SablotGetInstanceData</C> reads the user data stored with
1580       processor recently with <C>SablotSetInstanceData</C>
1581     </SUMMARY>
1582     <SYNTAX>
1583 void *SablotGetInstanceData(SablotHandle processor_);
1584       <PARAM name='processor_' type='SablotHandle'>desc</PARAM>
1585     </SYNTAX>
1586     <DESCRIPTION>
1587       <C>SablotGetInstanceData</C>
1588     </DESCRIPTION>
1589   </ENTRY>
1590
1591   <ENTRY id='SablotSetEncoding'>
1592     <TYPE value='Functions'/>
1593     <SUMMARY>
1594       <C>SablotSetEncoding</C> sets the encoding for the output document.
1595     </SUMMARY>
1596     <SYNTAX>
1597 void SablotSetEncoding(SablotHandle processor_,
1598       char *encoding_);
1599       <PARAM name='processor_' type='SablotHandle'>desc</PARAM>
1600       <PARAM name='encoding_' type='char*'>desc</PARAM>
1601     </SYNTAX>
1602     <DESCRIPTION>
1603       The encoding set via the <C>SablotSetEncoding</C> call overrides
1604       a stylesheet-defined value.
1605     </DESCRIPTION>
1606   </ENTRY>
1607
1608   <ENTRY id='.Sablotron DOM'>
1609     <TYPE value='DOM'/>
1610     <SUMMARY>
1611       Sablotron implements <S>DOM Level2</S> API.
1612     </SUMMARY>
1613     <DESCRIPTION>
1614       This book contains a brief description of the implemented interface
1615       only; for more details, please refer to the header file named sdom.h.
1616       <P/>
1617       Sablotron DOM interface includes types (see <C>DOM types</C>) and
1618       functions (see <C>DOM functions</C>). All of the names related to
1619       the DOM interface start with SDOM_ (for Sablot DOM).
1620       <P/>
1621       As Sablotron provides a C API for the object-oriented Document Object Model,
1622       you can't not expect the API follows the DOM specs literally. Instead,
1623       it maps object methods to plain functions, one to one usually.
1624       This arrangement makes it possible to write the specs compliant object
1625       oriented wrappers over the Sablotron DOM API. XML::Sablotron::DOM written
1626       in Perl is the primary example. See <C>.Known Issues</C> for the list
1627       of minor deviations from the DOM Level 2 specs.
1628     </DESCRIPTION>
1629     <EXTERNALREF name="DOM Level2" value="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/"/>
1630   </ENTRY>
1631
1632   <ENTRY id='DOM types'>
1633     <TYPE value='DOM'/>
1634     <SUMMARY>
1635       Types introduced by <C>.Sablotron DOM</C> Level 2 interface.
1636     </SUMMARY>
1637     <DESCRIPTION>
1638       Major new types are <C>SDOM_Document</C> (a DOM tree) and
1639       <B>SDOM_Node</B> (a node of the tree). A document can also be used in
1640       place of a node. This corresponds to the DOM spec, Document is a subclass
1641       of Node. When used in this way, the document represents its own root node
1642       (which is not the same as the `root element' aka 'document element').
1643       <P/>
1644       Other types include:
1645       <P/>
1646       <B>SDOM_char</B>: a DOM character type. Currently, this is just char.
1647       Note that the DOM spec requires that the DOM implementations work with
1648       UTF-16. Sablotron deviates from this by using UTF-8 instead.
1649       <P/>
1650       <B>SDOM_NodeType</B>: a node type enum. Some of the values are
1651       SDOM_ELEMENT_NODE, SDOM_ATTRIBUTE_NODE and SDOM_TEXT_NODE. See sdom.h
1652       for the rest.
1653       <P/>
1654       <B>SDOM_NodeList</B>: a node list returned by some of the functions.
1655       <P/>
1656       <B>SDOM_Exception</B>: DOM exception codes enum, with values such as
1657       SDOM_NOT_FOUND_ERR or SDOM_INVALID_NODE_TYPE. See sdom.h for details.
1658     </DESCRIPTION>
1659   </ENTRY>
1660
1661   <ENTRY id='DOM functions'>
1662     <TYPE value='DOM'/>
1663     <SUMMARY>
1664       Functions introduced by <C>.Sablotron DOM</C> Level 2 interface.
1665     </SUMMARY>
1666     <DESCRIPTION>
1667       The functions listed below are implemented as defined in the
1668       <C>DOM Level 2</C> specification, with two exceptions: their names are
1669       prefixed with SDOM_ and the first argument is always a SablotSituation.
1670       All the functions return a value of SDOM_Exception type. The functions
1671       aren't described in details as they correspond to well known DOM methods.
1672       Please, look to sdom.h for more details.
1673       <P/>
1674       <C>createElement</C>, <C>createElementNS</C>, <C>createAttribute</C>,
1675       <C>createAttributeNS</C>, <C>createTextNode</C>, <C>createCDATASection</C>,
1676       <C>createComment</C>, <C>createProcessingInstruction</C>
1677       <P/>
1678       <C>getNodeType</C>, <C>getNodeName</C>, <C>getNodeNSUri</C>,
1679       <C>getNodePrefix</C>, <C>getNodeLocalName</C>, <C>setNodeName</C>,
1680       <C>getNodeValue</C>, <C>setNodeValue</C>
1681       <P/>
1682       <C>getParentNode</C>, <C>getFirstChild</C>, <C>getLastChild</C>,
1683       <C>getPreviousSibling</C>, <C>getNextSibling</C>, <C>getChildNodeIndex</C>,
1684       <C>getChildNodeCount</C>, <C>getOwnerDocument</C>
1685       <P/>
1686       <C>insertBefore</C>, <C>appendChild</C>, <C>removeChild</C>,
1687       <C>replaceChild</C>
1688       <P/>
1689       <C>cloneNode</C>
1690       <P/>
1691       <C>getAttribute</C>, <C>getAttributeNS</C>, <C>getAttributeNode</C>,
1692       <C>getAttributeNodeNS</C>, <C>getAttributeNodeIndex</C>,
1693       <C>getAttributeNodeCount</C>, <C>setAttribute</C>, <C>setAttributeNS</C>,
1694       <C>setAttributeNode</C>, <C>setAttributeNodeNS</C>, <C>removeAttribute</C>,
1695       <C>removeAttributeNode</C>, <C>getAttributeElement</C>,
1696       <C>getAttributeList</C>
1697       <P/>
1698       Several functions have been added:
1699       <P/>
1700       <C>disposeNode</C> frees all memory used by the given node.
1701       <P/>
1702       <C>cloneForeignNode</C> clones a node from a different document.
1703       <P/>
1704       <C>docToString</C> serializes the document, returning the resulting string.
1705       <P/>
1706       <C>nodeToString</C> serializes a node (and its descendants), returning
1707       the resulting string.
1708       <P/>
1709       <C>xql</C> performs an XPath query on the DOM tree, returning a list of the
1710       nodes satisfying the query.
1711       <P/>
1712       In addition, there are some functions used to manipulate the node lists
1713       returned by xql and getAttributeList functions. These include
1714       <C>getNodeListLength</C>, <C>getNodeListItem</C> and <C>disposeNodeList</C>.
1715       <P/>
1716       Finally, there are functions to extract DOM exception-related information
1717       from the situation object, namely <C>getExceptionCode</C>,
1718       <C>getExceptionMessage</C> and <C>getExceptionDetails</C>.
1719     </DESCRIPTION>
1720   </ENTRY>
1721
1722 </API>