LC74c proposed resolution

Heylas,

LC74c [1] raises issues related to internationalization of
documentation elements, and proposes a solution.  Excerpted:

a) The <documentation> element require an xml:lang attribute. 
   The attribute may be empty (xml:lang="")
b) The <documentation> element be allowed to be repeated, 
   provided the xml:lang attributes in each of the elements be unique.

I think that this is more than is necessary, on examination.

I recommend that we do only the following:

c) add maxOccurs="unbounded" to the reference to wsdl:documentation in
the definition of DocumentedType.

We make no statements about how multiple documentations may relate to
one another, if present, although the use case presented above is
feasible and even likely.  We neither require xml:lang, nor require it
to be unique (multiple documentation elements could, in theory, share
the same xml:lang attribute value).

*Optionally*, we could make xml:lang a required attribute.  However,
I'm not convinced that this is useful.  In my experience, much
documentation seems to be written in Klingon, or possibly in the
private languages of twins.  Permitting the recurrence of the
documentation element permits proper internationalization (and
potentially other use cases involving multiple documentation elements,
such as an ASCII presentation versus an algorithm in MathML, perhaps,
or different authorities for different documentation blocks); if it
allows xml:lang, we're done.

Unfortunately, we do not allow attribute extension on a document
element.  *sigh*  So, we should *also* add anyAttribute
(namespace="##other") to the DocumentationType definition.

In short: change the recurrence of wsdl:documented in DocumentedType to
*, add attribute extensibility DocumentationType, let usage of multiple
documentation elements be determined in practice.

[1: http://www.w3.org/2002/ws/desc/4/lc-issues/#LC74c]

Amy!
-- 
Amelia A. Lewis
Senior Architect
TIBCO/Extensibility, Inc.
alewis@tibco.com

Received on Thursday, 19 May 2005 17:41:24 UTC