libsablot/doc/misc/NOTES

   1 * Introduction
   2
   3 As we are approaching the 1.0 release, it is a good time to summarize
   4 subtle (more or less) changes and new features introduced in the past
   5 time.
   6
   7 These note may be classified as either interface changes or features
   8 not covered in the XSLT specification.
   9
  10 This file should be a primary source of information, for those
  11 interested in Sablotron specific features, and/or for people using
  12 Sablotron native interfaces.
  13
  14 The most recent changes are described as well as a bit older issues,
  15 which was not yet described in this way, or there is need to put
  16 things together.
  17
  18 * Specification Conformance
  19
  20 Since the version number of 0.95 almost complete XSLT 1.0 specification
  21 is covered (and mostly well tested). There are just few minor issues, the id()
  22 function support and embedded stylesheets are the most important ones.
  23
  24 Although we'd like to meet this requirements too, this is not sure, we
  25 will do it prior the 1.0 release, since we'll aim our efforts to bug
  26 fixing and code cleanup.
  27
  28 issues:
  29         - id(),
  30         - embedded stylesheets,
  31         - some possible operations with RTF that should disabled,
  32         - case insensitive sorting
  33
  34 ** Ambiguities
  35
  36 There are few issues, where the specifications allows more then one
  37 solution. Sablotron processor respects a set of options, that control
  38 the behavior in such cases. See ``API and Architecture'' for more.
  39
  40 ** Specification Leaks
  41
  42 We found several minor specification leaks. The most important of them
  43 is the namespace output and namespace aliasing.
  44
  45 The spec says, that the XSLT namespace must not be output for XSLT
  46 literal result elements. This brings a problem, when the XSLT
  47 namespaces is marked as a target namespace for the
  48 xsl:namespace-alias.
  49
  50 Sablotron bypasses this issue and outputs this namespace, if specified
  51 in as the namespace alias.
  52
  53 ** The XHTML Output Mode
  54
  55 Although this mode is not described in the spec, it is defined in XSLT
  56 1.1 and surely will be a part of the 2.0 spec.
  57
  58 Sablotron supports xhtml mode, but it doesn't exactly what newer
  59 spec. version say. in any case it is useful and works fine.
  60
  61 * Extensions
  62
  63 ** Multiple Document Output
  64
  65 The multiple document output is fully supported as described by
  66 exslt.org initiative (what is actually based on XSLT 1.1 working
  67 draft).
  68
  69 We tested this on pretty huge piece of data (Definitive Guide to
  70 DocBook), and it seems to work fine.
  71
  72 See <http://www.exslt.org/exsl/elements/document/index.html> for more
  73 details.
  74
  75
  76 ** JavaScript Embedding
  77
  78 The exslt.org scripting is supported (based on XSLT 1.1 again).
  79 See <http://www.exslt.org/func/elements/script/index.html> for more.
  80
  81 Implementation specific topics:
  82
  83 *** JS Engine
  84
  85 The Mozilla Spider Monkey engine is used. We alway use the standalone
  86 library, nobody tried to link against library brought by Mozilla.
  87
  88 *** Language Supported
  89
  90 The 'language' attribute of the 'func:script' extension element may be
  91 either of 'javascript' or 'ecmascript' (case insensitive).
  92
  93 *** Inline Scripts
  94
  95 On contrary to the exslt specification, the 'src' attribute is not
  96 mandatory. If it is not present, the content of the 'func:script' is
  97 used. it allows the script to be inlined in the stylesheet.
  98
  99 It is not error, if both of the element content and the 'src'
 100 attribute are present. The attribute wins in such a case.
 101
 102 *** DOM Support
 103
 104 Almost all DOM2 functions and classes are supported. The whole DOM
 105 model is read only (it fits the spec). Any write attempt will raise the
 106 NOT_SUPPORTED_ERR exception.
 107
 108 Just few functions are missing.
 109
 110 issues:
 111         - Document.docElementsByTagName,
 112         - Document.docElementsByTagNameNS,
 113         - node name lists may be accessed with
 114           the item() member function only,
 115           not as the array items.
 116         - NamedNodeMap.getNamedItemsNS
 117
 118 *** Type Mapping and the Context object
 119
 120 Should be OK.
 121
 122 *** Accessing Other Documents
 123
 124 Currently is not possible to access another document as given in the
 125 Context object or passed in the function as a parameter.
 126
 127 Some support of document() function at the script level would be nice.
 128
 129 ** More Sablotron Specific Features
 130
 131 *** Sablotron Version and the system-property()
 132
 133 The system-property() function return the Sablotron version. The QName
 134 to be used is ga:version, where the 'ga' prefix is bound to
 135 'http://www.gingerall.org/sablotron/extension'.
 136
 137 * Command-line interface
 138
 139 ** Batch Mode
 140
 141 Thanks to Stefan Behnel, the sabcmd command allows the batch
 142 processing, when single XML document is processed with multiple XSL
 143 sheets, or several XML document are processed with single sheet. See
 144 the manpage for details.
 145
 146 ** Processing Options
 147
 148 Processing options may be passed into the sabcmd using the --flags
 149 switch.
 150
 151 * SXP and Processing on External Documents
 152
 153 Sablotron supports the XPath evaluation on external documents as well
 154 as XSLT processing of these documents.
 155
 156 An application may register a set of callbacks and provide nodes
 157 (abstract opaque handles to them) to the engine.
 158
 159 There is detailed documentation here:
 160
 161 <http://www.gingerall.org/ga/html/sxp/sparse-frameset.html>
 162
 163 Currently it is slightly out-of-date, please always check the sxpath.h
 164 file.
 165
 166 If you want to process an external document, use the
 167 SablotRunProcessorExt.
 168
 169 * API and Architecture
 170
 171 ** Constant Pointers
 172
 173 Recently we changed the type of all (char*) passed in to (const
 174 char*). we hope it won't bring much troubles, but we wanted to do it
 175 before 1.0. Sorry for any inconvenience.
 176
 177 ** Old vs. New Interface
 178
 179 The ancient versions of Sablotron introduced a couple of API
 180 functions, like SablotProcess, SablotProcess etc. They still works
 181 (and will), but are obsoleted and shouldn't be used.
 182
 183 Here is the list of function to be used (in alphabetical order)
 184
 185 SablotAddArgBuffer
 186 SablotAddArgTree
 187 SablotAddParam
 188 SablotClearSituation
 189 SablotCreateDocument
 190 SablotCreateProcessor
 191 SablotCreateProcessorForSituation
 192 SablotCreateSituation
 193 SablotDestroyDocument
 194 SablotDestroyProcessor
 195 SablotDestroySituation
 196 SablotFree (*)
 197 SablotFreeResultArgs (*)
 198 SablotGetErrorLine
 199 SablotGetErrorMessage
 200 SablotGetErrorURI
 201 SablotGetInstanceData (*)
 202 SablotGetResultArg (*)
 203 SablotParse
 204 SablotParseBuffer
 205 SablotParseStylsheet
 206 SablotRegHandler (*)
 207 SablotRunProcessorExt
 208 SablotRunProcessorGen
 209 SablotSetBase (*)
 210 SablotSetBaseForScheme (*)
 211 SablotSetEncoding (*)
 212 SablotSetInstanceData (*)
 213 SablotSetLog (*)
 214 SablotUnregHandler (*)
 215
 216 Function marked (*) do not take a situation handle as a parameter,
 217 since they are older by design. we won't fix this issue (unless we
 218 redesign the processor vs. situation ownership - see ``What Next?''
 219
 220 A better documentation will be provided soon.
 221
 222 ** Parameter Encoding
 223
 224 All parameters must be passed in utf-8 encoded. This is an issue.
 225
 226 ** Memory Allocations
 227
 228 Any memory allocated by a calling application must be freed by this
 229 application and any memory allocated by Sablotron (and returned to
 230 application) must be freed using an appropriate SablotDestroy*
 231 call. String values (the most frequent case) must be disposed with
 232 SablotFree.
 233
 234 * Perl Extension
 235
 236 The Perl extension supports most of Sablotron features. Including the
 237 DOM2 (almost complete) interface to native Sablotron trees.
 238
 239 See XML::Sablotron and XML::Sablotron::DOM for more details.
 240
 241 * What Next?
 242
 243 ** Specification Conformance
 244
 245 We must beat all unsupported features. id(), embedded documents
 246 and case insensitive sorting are the most important ones.
 247
 248 ** Extensions
 249
 250 *** EXSLT
 251
 252 More exslt stuff, namely func:function, func:result, exsl:node-set(),
 253 exsl:object-type
 254
 255 *** JavaScript and the document() function
 256
 257 As stated above, JavaScript users should be allowed to access any
 258 document (even not-yet-parsed)
 259
 260 *** XHTML Output Method
 261
 262 The xhtml output method should be checked to match recommendations.
 263
 264 ** Documentation
 265
 266 The API documentation should be redesigned (use ApiDoc). The SXP
 267 documentation should be updated.
 268
 269 ** API Changes and Enhancements
 270
 271 *** Situation vs. Processor
 272
 273 Some stuff registered currently with the processor (handlers, base
 274 uri), should be registered to the situation object. This is not an
 275 critical issue, but would make the architecture more compact.
 276
 277 *** Parameter Encoding
 278
 279 Some way, parameters (SablotAddParam) might be recoded would be VERY
 280 nice. Actually this is one of the most important things to be done.
 281