This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.
Since we are approaching CR for XSLT 3.0, I had a look at the fn:transform function and had a few observations / suggestions / improvements (mainly w.r.t. XSLT 3.0): 1) there should only be one of stylesheet-location/-text/-node present 2) stylesheet-base-uri can be made relative to the current base-uri in scope, or relative to the stylesheet-location or -node. 3) base-output-uri should be allowed to be a relative URI, as most processors currently take it as defaulting to the current stylesheet-base-uri. This can also be the default if absent. 4) source-node, text says "required unless initial-template is defined", it is also not required if initial-function is defined. 5) source-node: is defined as node(), but can (in XSLT 3.0) be any item, or even sequence of items. Perhaps combine with initial-match-selection (see below)? 5) initial-mode: if supplied, initial-template *and* initial-function must be absent 7) initial-template: if supplied, initial-mode *and* initial-function must be absent 8) initial-function: if supplied, initial-mode *and* initial-template must be absent and source-node will be ignored. 9) if *none* of initial-mode/-template/-function is supplied, and if a source-node is supplied, initial-mode is the #unnamed mode, or the mode defined on the outermost stylesheet element in [xsl:]default-mode. If no source-node is supplied, initial-template is xsl:initial-template (these rules follow the rules in XSLT 3.0, xsl:initial-template is meant to be the "int main()" of the stylesheet). 10) package-version: this is currently xs:decimal, but should be a string. XSLT 3.0 has a production for how the string is allowed to be created. It can take a fixed version or a range. Valid are 1.1+, 2.3-alpha, 1.0-3.1 etc 11) package-version: if not supplied, default to "*" 12) package-name: if supplied, stylesheet-location/-node/-text should all be absent and package-node must be present. 13) package-node: add a package-location and package-text similar to stylesheet-location and stylesheet-text? At least one of those must be present if package-name is specified. 14) packages, general. Since used packages are recognized by name (URI) it is probably good to allow a parameter to set a map with key/value pairs for URI + version number vs location. 15) packages: they can be precompiled or not. If not precompiled, it should be made possible to set their static params (which are private to the package and can collide). 16) initial-match-selection: it is now possible to have a different initial match selection than a global context item. By default, they should (probably) be set to source-node. The initial-match-selection can be any sequence of items of any type, and can be empty. It only makes sense to specify it with initial-mode. As an after-thought, perhaps we can add a required option that specifies the requested type of invocation. For instance: invocation-type: mode | template | function. And instead of initial-template/-function/-mode we could settle with initial-component, which, if absent defaults to the defaults of that component (#unnamed mode, xsl:initial-template, function invocation has no default).
Some comments (but without proposals, yet): 2 & 3: It is clearer to use absolute URIs for stylesheet-base-uri and base-output-uri (leaving the definition as it is, rather than allowing relative URIs) because defaults for the base URIs are not standard or obvious. - Points related to invocation - 1, 4, 6, 7, 8, 9: I agree with the points made, the rules for combinations of options (which of them are mutually exclusive, etc.) should be updated and clarified. 5 & 16: indeed, another option initial-match-selection with type item()* (which can be used instead of source-node) should be introduced. - Points related to packages - 10-15: Generally agree with points made; also raise issues still to think about (e.g. how much should be explicitly specified, and what can be left to options provided by implementations). Note that package-name should be allowed to be used on its own - the intention is for a processor to use this to access a precompiled package (in an implementation defined way). - Final after-thought - i.e. options invocation-type and initial-component (instead of initial-template/-function/-mode) I think this is an interesting idea, and perhaps what you'd use if you were just writing this function straight from the XSLT 3.0 spec. But since this is not the case, I think it makes sense (and is easier for users) to build from the options already defined for XSLT 2.0, as the options currently do. Yes this means clarifying the invocation rules, and it'll be useful to state more explicitly out how defaults can be used.
Created attachment 1625 [details] Proposed presentation for option combination rules
I propose separating the rules for combinations of options from the table of meanings. This can also be done for the XSLT 1.0/2.0 case. Then most of the meanings can stay the same for 2.0 and 3.0 (exceptions are delivery-format, and source-node), while the rules are updated. Rather than a list of rules (describing which options are mutually exclusive, etc.), Mike suggested using some more visual presentation. The hope is that this is also more useful for people actually using the function, when deciding which options to use. See the attached html for a suggested presentation using tables. The list of XSLT 1.0/2.0 option meanings should be edited to remove any combination rules (i.e. for stylesheet-location, source-node, initial-mode, initial-template). We are proposing that for XSLT 3.0, the option initial-match-selection is added to replace the source-node option (i.e. source-node is no longer a valid option for XSLT 3.0, initial-match-selection and/or global-context-item should be used instead). So updates for the list of XSLT 3.0 options are: package-version - required type is xs:string not xs:decimal: Defaults to "*". initial-match-selection - required type item()*: The initial match selection, as defined in XSLT 3.0. Note that in XSLT 3.0, for the Call Template invocation, the option initial-template is no longer required, instead it has the default xsl:initial-template. (I’m not sure if it’s necessary to add a note (also relating to Abel’s point 9), that for the apply templates invocation, initial-mode defaults to #unnamed, or the [xsl:]default-mode if specified in the stylesheet.) Returning to Abel’s “final after thought” (about an alternative “invocation-type” option), Mike suggested that rather than being required, a new optional option could be added, which can be used to help make the invocation method explicit. See the html. Mike also noted that the following assumption should be added to the text: If the top level stylesheet or package invoked makes reference to other stylesheet modules or packages via xsl:include/import/use-package then the way these references are resolved is not under the control of this API (vendors may add additional parameters to control this).
Comments to the proposed specification, as defined for fn:transform2 in the editor's draft of F+O: 1. Don't forget to update the required type of package-version from xs:decimal to xs:string, with default "*". 2. I think initial-mode should be removed from the lists 2.d and 3.d, as I believe it is only relevant for apply-templates invocation (but correct me if I'm wrong). 3. In 3.c.ii. (the call-template invocation under XSLT 3.0) I think initial-template should also be optional (not mandatory), with default "xls:initial-template". Otherwise, it all looks very good to me. In particular, I note that the description of source-node has been updated to clarify its use with global-context-item, so that it can be kept as an alternative to initial-match-selection when invoking XSLT 3.0 processing. This is very helpful.
I really like the new write-up of this, it's way clearer than it used to be. I have, however, a few remarks / questions / suggestions (and I agree to Debbie's) (apologies, while typing, the list grew and grew...): 1) What happens when "serialization" is chosen for the result and the serialized tree cannot be represented by the calling execution environment, for instance because XML 1.1 is serialized, JSON is chosen in xsl:output and contains values not representable directly as an xs:string, or an implementation-defined type is serialized (jpg, other). 2) Should we allow users to specify additional stylesheets, i.e. for the ones referenced in by xsl:import? If the stylesheet as a whole is generated dynamically, the base-stylesheet-uri option will not be sufficient. 3) Can we predefine names for other options of the dynamic and static context, i.e. timezone, date, collation, collection? Currently these would go into vendor-options, but standardizing these as key names for the map will make implementation-independent calls easier, even if such parts of the context are not supported (which could be an error, a default, or ignored). 4) It would be nice if there's some way to distinguish the phase of the returned result in error scenarios. I.e., a dynamic error in a use-when expression (static compilation phase) should be distinguishable from a dynamic error during evaluation or priming. But I'm not sure how this could be made workable. 5) I'm slightly ambivalent about "stylesheet-location", since it is technically not a location. 6) Under 2.d, "initial-mode" is repeated (it is already under 2.c) 7) the entry for "source-node" is under-defined. For XSLT 1.0 it must be a document node, for XSLT 2.0, it can be any node. The second part of this sentence refers only to XSLT 3.0, but this is not specified. 7a) the type for "source-node" can be "node()?", XSLT 2.0 (not sure about 1.0) allows it to be empty. 8) typo "Theese" --> "These" (under serialization-params). 9) Serialization params requires a QName as key, should we specify that the xsl:output params exist in no namespace? 10) If "saved" is the delivery format, is it an error if the document cannot be saved? 11) On the same token, the transformation may succeed, but errors may be raised after the transformation (i.e., saving the result). In such cases it may be beneficial to have a result set *and* the reported errors (as opposed to just blowing up). 12) XSLT 3.0 defaults to "xsl:initial-template" if not initial match selection or template is provided (i.e., with call-template invocation). I think this should be reflected by the options by allowing this as default if "initial-template" is not provided and no "source-node" or "initial-match-selection" is given. 13) Is "function-params" required? With an initial function that takes no params, this could be optional, right? 14) XSLT 3.0 with packages, it looks as if "package-version" is only allowed with "package-name". Is that intentional? 15) XSLT 3.0: delivery format should probably not default to "document", since "raw" can be selected in xsl:output and otherwise that default won't work. 16) XSLT 3.0: "static-params" is not mentioned as allowed optional entry 17) Determinism: I think fn:transform will by definition be non-deterministic with XSLT 3.0 and streaming. Though this is not possible with nodes in maps, it can be achieved with xsl:stream. 18) Talking of streaming, perhaps we should mention this in the notes starting with "Where nodes are passed to or from the transformation" 19) Currently, only an available node can be passed to the fn:transform function, I assume this is deliberate? If not, can we add "source-location" to the mix? 20) A further improvement in the text structure could be to write it up such: 1. For invocation of an XSLT 1.0 processor, the supplied options must include all of the following and nothing else: a. A version of 1.0, by setting xslt-version to 1.0 b. A source item, by setting source-node to a document node c. A stylesheet, by setting one of the following: [...] d. Other options, by providing zero or more of the following [...] The idea being: naming each of a, b, c, d makes it a bit clearer, at least to me, what *must* be provided and what these things are.
PS: about determinism, if we want fn:transform to behave deterministic, we probably should say specifically what happens when repeated calls to fn:transffm are made with the same arguments, but with xsl:stream / xsl:merge etc inside the stylesheet. Likewise, we may need to say something if the global-context-item must be streamed, or the initial-match-selection must be streamed. Not an issue per se (if a supplied node is not streamed, a streaming transformation will succeed normally), but worth mentioning, I think.
Sorry, few more: 21) base-output-uri: is optional, but we do not say what it defaults to. It makes sense to default it to stylesheet-base-uri, which is common with commandline processors dealing with relative uris in xsl:result-document. 22) stylesheet-base-uri, I thought/hoped we would make this relative. There can be situations where the stylesheet path is not known, but library stylesheets are located relative to the current stylesheet, i.e. "../imports". 23) initial-mode: we should perhaps mention it defaults to #unnamed if absent.
A revised version of the function specification has been agreed by the XSL and XQuery working groups. The change has been applied to the spec.