My response on xsl-list:

You're right about the duplicate mention of modes. 

Regarding keys, the introductory sentence of 3.6.3 is factually correct when it says that the section discusses keys; the last paragraph also states that keys are different in some ways from other components. They have three peculiarities: one is that the reference to a key is always dynamic rather than static (but this is also true of accumulators); the second is that multiple declarations within a package are cumulative (but this is also true of attribute sets), and the third is that the visibility is always private. The latter constraint is one that in principle could be relaxed, but we considered that allowing key definitions to be overridden would only cause confusion.

Further response:

I should add that we could have decided to allow keys to be final, so they can be referenced in a using package, but not overridden. But I think keys should probably be regarded as an implementation detail. A package should expose the functionality of keys using a public function such as

<xsl:function name="get-customer-with-id" as="element(customer)" visibility="public">
  <xsl:param name="customer-doc" as="document-node(element(customers))"/>
  <xsl:param name="id" as="xs:string"/>
  <xsl:sequence select="key('cust-id-key', $id, $customer-doc)"/>
</xsl:function>

so that the decision to implement this using keys, or maps, or by relying on the optimizer, becomes an implementation decision that can easily be changed.

Michael Kay

Thank you for clarifying this. I still believe that mentioning keys in a list of other types of components, all of which can be exposed (except) keys, brings confusion and it isn't easy to notice that keys are not like any other component type in this list.

I believe that removing keys from that list would significantly raise the clarity and understandability of the document. Certainly, the discussion about keys and their private visibility still belongs to this section.

Dimitre Novatchev

If xsl:key is a named component that can only be private, it seems to make sense to remove it from the list of named components, just like other "named components" (quotes are deliberate), like xsl:decimal-format and xsl:character-map, that are not considered "real" named components.

Perhaps it is better if we make a clearer distinction here. The term "named components" seems too general and feels like any named declaration. We currently have:

Named components:
- xsl:accumulator
- xsl:attribute-set
- xsl:function
- xsl:key
- xsl:mode
- xsl:param
- xsl:template
- xsl:variable

Named declarations, but not components:
- xsl:character-map
- xsl:decimal-format
- xsl:output

Unnamed declarations:
- xsl:import
- xsl:import-schema
- xsl:include
- xsl:namespace-alias
- xsl:preserve-space
- xsl:strip-space

Declarations not categorized as declarations:
- xsl:expose
- xsl:global-context-item
- xsl:use-package

One suggestion I can think of is a term like "exposable components" or "overridable components". This would deal with the issues with xsl:param (not overridable, either always private or always public) and xsl:key (not overridable). It would also make the other named declarations to be named components, but not overridable (character-map, decimal-format and output). Unnamed components (including the unnamed mode) are never overridable (but some have special rules with packages, like strip/preserve-space).

The difference between xsl:key and (say) xsl:decimal format and xsl:character-map is that xsl:key can contain outbound references to functions, templates, and global variables, and these are therefore subject to the binding rules. It's only special in that it can't have inbound references from another package.

I completely agree with Abel Braaksma's comment.

The most important information in the section is which types of components can be exposed to a using package -- not which components are discussed. In the current version of the document it is not easy to find what are the types of components that can be exposed.

Starting the section with a statement that provides this most important information -- by enumerating all exposable component types, will make the document much more readable and understandable.

Dimitre Novatchev

A belated comment that the WG considered this bug on 20 November; the minutes record: "Scope for editorial improvement suggested in Comment 3 in the bug;
the editor will use his discretion for the actual change."

I have made editorial changes which will hopefully make these distinctions clearer.

The start of the section now reads as follows:

<p>This section discusses the use of named components in packages.</p>  

<p diff="chg" at="S-27340">The components which can be declared in one package and referenced in another are:  <termref def="dt-stylesheet-function">functions</termref>,  <termref def="dt-named-template">named templates</termref>, <termref def="dt-attribute-set">attribute sets</termref>,  <termref def="dt-mode">modes</termref>, <termref def="dt-accumulator">accumulators</termref>, and <termref def="dt-global-variable">global variables</termref> and <termref def="dt-stylesheet-parameter">parameters</termref>.</p>  

<p diff="chg" at="S-27340">In addition, <phrase diff="add" at="P-bug22877"><termref def="dt-key">keys</termref></phrase> are classified as named components because they can contain references to components in another package, even though they cannot themselves be referenced from outside the package.</p>    

<p diff="chg" at="S-27340">Named and unnamed <termref def="dt-mode">modes</termref>, come within the scope of this section, but there are differences noted in <specref ref="modes-and-packages"/>.</p>  

<p>Not all <termref def="dt-declaration">declarations</termref> result in <termref def="dt-component">components</termref>:</p>  

<ulist> <item><p diff="chg" at="S-27340">Named <termref def="dt-declaration">declarations</termref> that can neither be referenced from outside their containing package, nor can contain references  to components in other packages (examples are <elcode>xsl:output</elcode>, <elcode>xsl:character-map</elcode>,  and <elcode>xsl:decimal-format</elcode>) are not considered to be components and are therefore outside the scope of this section.</p></item> 

<item><p>Some declarations, such as <elcode>xsl:decimal-format</elcode> and <elcode>xsl:strip-space</elcode>,  declare aspects of the processing context which are not considered to be components as defined here.</p></item> 

<item><p><termref def="dt-template-rule">Template rules</termref>  (<elcode>xsl:template</elcode> with a <code>match</code> attribute) are  also not considered to be components for the purposes of this section, which is concerned  only with components that are bound by name. However, when an <elcode>xsl:template</elcode>  has both a <code>match</code> attribute and a <code>name</code> attribute, then it establishes  both a template rule and a <termref def="dt-named-template">named template</termref>, and  in its role as a named template it comes within the scope of this discussion.</p></item> 

<item><p>A named declaration, for example a named template, a function, <phrase diff="add" at="M">an accumulator,</phrase> <phrase diff="del" at="P-bug22747">an attribute set,</phrase> or a global  variable, may be overridden within the same package by another like-named declaration  having higher <termref def="dt-import-precedence">import precedence</termref>. When a  declaration is overridden in this way it can never be referenced or invoked either from  within its containing package or from outside that package; it is effectively dead code,  and it therefore does not result in the creation of any component, which means that it  plays no part in the component binding process.</p></item> 

<item><p diff="add" at="P-bug22747">In the case of <elcode>xsl:attribute-set</elcode> and <elcode>xsl:key</elcode>  declarations, several declarations combine to form a single component.</p></item>  </ulist>  <p>The section is largely concerned  with details of the rules that affect references from one component to another by name, whether  the components are in the same package or in different packages. The rules are designed to  meet a number of requirements:</p>