* Introduction As we are approaching the 1.0 release, it is a good time to summarize subtle (more or less) changes and new features introduced in the past time. These note may be classified as either interface changes or features not covered in the XSLT specification. This file should be a primary source of information, for those interested in Sablotron specific features, and/or for people using Sablotron native interfaces. The most recent changes are described as well as a bit older issues, which was not yet described in this way, or there is need to put things together. * Specification Conformance Since the version number of 0.95 almost complete XSLT 1.0 specification is covered (and mostly well tested). There are just few minor issues, the id() function support and embedded stylesheets are the most important ones. Although we'd like to meet this requirements too, this is not sure, we will do it prior the 1.0 release, since we'll aim our efforts to bug fixing and code cleanup. issues: - id(), - embedded stylesheets, - some possible operations with RTF that should disabled, - case insensitive sorting ** Ambiguities There are few issues, where the specifications allows more then one solution. Sablotron processor respects a set of options, that control the behavior in such cases. See ``API and Architecture'' for more. ** Specification Leaks We found several minor specification leaks. The most important of them is the namespace output and namespace aliasing. The spec says, that the XSLT namespace must not be output for XSLT literal result elements. This brings a problem, when the XSLT namespaces is marked as a target namespace for the xsl:namespace-alias. Sablotron bypasses this issue and outputs this namespace, if specified in as the namespace alias. ** The XHTML Output Mode Although this mode is not described in the spec, it is defined in XSLT 1.1 and surely will be a part of the 2.0 spec. Sablotron supports xhtml mode, but it doesn't exactly what newer spec. version say. in any case it is useful and works fine. * Extensions ** Multiple Document Output The multiple document output is fully supported as described by exslt.org initiative (what is actually based on XSLT 1.1 working draft). We tested this on pretty huge piece of data (Definitive Guide to DocBook), and it seems to work fine. See <http://www.exslt.org/exsl/elements/document/index.html> for more details. ** JavaScript Embedding The exslt.org scripting is supported (based on XSLT 1.1 again). See <http://www.exslt.org/func/elements/script/index.html> for more. Implementation specific topics: *** JS Engine The Mozilla Spider Monkey engine is used. We alway use the standalone library, nobody tried to link against library brought by Mozilla. *** Language Supported The 'language' attribute of the 'func:script' extension element may be either of 'javascript' or 'ecmascript' (case insensitive). *** Inline Scripts On contrary to the exslt specification, the 'src' attribute is not mandatory. If it is not present, the content of the 'func:script' is used. it allows the script to be inlined in the stylesheet. It is not error, if both of the element content and the 'src' attribute are present. The attribute wins in such a case. *** DOM Support Almost all DOM2 functions and classes are supported. The whole DOM model is read only (it fits the spec). Any write attempt will raise the NOT_SUPPORTED_ERR exception. Just few functions are missing. issues: - Document.docElementsByTagName, - Document.docElementsByTagNameNS, - node name lists may be accessed with the item() member function only, not as the array items. - NamedNodeMap.getNamedItemsNS *** Type Mapping and the Context object Should be OK. *** Accessing Other Documents Currently is not possible to access another document as given in the Context object or passed in the function as a parameter. Some support of document() function at the script level would be nice. ** More Sablotron Specific Features *** Sablotron Version and the system-property() The system-property() function return the Sablotron version. The QName to be used is ga:version, where the 'ga' prefix is bound to 'http://www.gingerall.org/sablotron/extension'. * Command-line interface ** Batch Mode Thanks to Stefan Behnel, the sabcmd command allows the batch processing, when single XML document is processed with multiple XSL sheets, or several XML document are processed with single sheet. See the manpage for details. ** Processing Options Processing options may be passed into the sabcmd using the --flags switch. * SXP and Processing on External Documents Sablotron supports the XPath evaluation on external documents as well as XSLT processing of these documents. An application may register a set of callbacks and provide nodes (abstract opaque handles to them) to the engine. There is detailed documentation here: <http://www.gingerall.org/ga/html/sxp/sparse-frameset.html> Currently it is slightly out-of-date, please always check the sxpath.h file. If you want to process an external document, use the SablotRunProcessorExt. * API and Architecture ** Constant Pointers Recently we changed the type of all (char*) passed in to (const char*). we hope it won't bring much troubles, but we wanted to do it before 1.0. Sorry for any inconvenience. ** Old vs. New Interface The ancient versions of Sablotron introduced a couple of API functions, like SablotProcess, SablotProcess etc. They still works (and will), but are obsoleted and shouldn't be used. Here is the list of function to be used (in alphabetical order) SablotAddArgBuffer SablotAddArgTree SablotAddParam SablotClearSituation SablotCreateDocument SablotCreateProcessor SablotCreateProcessorForSituation SablotCreateSituation SablotDestroyDocument SablotDestroyProcessor SablotDestroySituation SablotFree (*) SablotFreeResultArgs (*) SablotGetErrorLine SablotGetErrorMessage SablotGetErrorURI SablotGetInstanceData (*) SablotGetResultArg (*) SablotParse SablotParseBuffer SablotParseStylsheet SablotRegHandler (*) SablotRunProcessorExt SablotRunProcessorGen SablotSetBase (*) SablotSetBaseForScheme (*) SablotSetEncoding (*) SablotSetInstanceData (*) SablotSetLog (*) SablotUnregHandler (*) Function marked (*) do not take a situation handle as a parameter, since they are older by design. we won't fix this issue (unless we redesign the processor vs. situation ownership - see ``What Next?'' A better documentation will be provided soon. ** Parameter Encoding All parameters must be passed in utf-8 encoded. This is an issue. ** Memory Allocations Any memory allocated by a calling application must be freed by this application and any memory allocated by Sablotron (and returned to application) must be freed using an appropriate SablotDestroy* call. String values (the most frequent case) must be disposed with SablotFree. * Perl Extension The Perl extension supports most of Sablotron features. Including the DOM2 (almost complete) interface to native Sablotron trees. See XML::Sablotron and XML::Sablotron::DOM for more details. * What Next? ** Specification Conformance We must beat all unsupported features. id(), embedded documents and case insensitive sorting are the most important ones. ** Extensions *** EXSLT More exslt stuff, namely func:function, func:result, exsl:node-set(), exsl:object-type *** JavaScript and the document() function As stated above, JavaScript users should be allowed to access any document (even not-yet-parsed) *** XHTML Output Method The xhtml output method should be checked to match recommendations. ** Documentation The API documentation should be redesigned (use ApiDoc). The SXP documentation should be updated. ** API Changes and Enhancements *** Situation vs. Processor Some stuff registered currently with the processor (handlers, base uri), should be registered to the situation object. This is not an critical issue, but would make the architecture more compact. *** Parameter Encoding Some way, parameters (SablotAddParam) might be recoded would be VERY nice. Actually this is one of the most important things to be done.