Re: Defining "public interfaces" in specifications

On 30 Oct 2002, Eric van der Vlist wrote:

> Not quite, or at least not every snippet of a spec as the same ability
> of being used as a reference (or public interface).

Every normative snippet should have the ability of being used as a
reference. If it does not have such an ability, it is a spec bug.

> Let's take some examples from XML 1.0.
>
> "[Definition: A Name is a token beginning with a letter or one of a few
> punctuation characters, and continuing with letters, digits, hyphens,
> underscores, colons, or full stops, together known as name characters.]"
>
> This one, explicitely marked as a "Definition" is obviously something on
> which other specs may rely. But these "interfaces" are not always marked
> as such and the following sentence:
>
> "Names beginning with the string "xml", or any string which would match
> (('X'|'x') ('M'|'m') ('L'|'l')), are reserved for standardization in
> this or future versions of this specification."
>
> is obviously in the same category.
>
> These statements could be formally identified as "XML Name definition"
> and "XML reserved names".

OK. So seems like there are no problems with the above two
definitions.

> On the other extrimity, a sentence such as:
>
> "In editing XML documents, it is often convenient to use "white space"
> (spaces, tabs, and blank lines) to set apart the markup for greater
> readability."
>
> is obviously something which other specs will rely on.

Not sure how one can rely on the above statement. It does not impose
any requirement. If it meant to define "white space", the definition
is obviously not precise enough to be used for any practical purpose.
But, again, the above sounds like non-normative text which we should
ignore in the context of this discussion: we should only be interested
in normative text.

> Between these two opposite cases, there are grey areas for which it's
> more fuzzy to know if they are things you can rely on or not.

What makes them opposite? Being normative versus being informal? Since
we do not care about informal text, you need to give an example of a
normative snippet that cannot be used as a public interface.

> The fact to identify the sections on which one can rely (and giving them
> identifiers) would IMO facilitate the work of people refering to the
> specs and also the tracking of interdependences between specs.

Sure, but identifying normative snippets is already a SpecGL MUST. You
are proposing something new (a "public interface") and a global
W3C-managed registry of public interfaces. So far, I fail to see how
"public interface" differs from normative text in a SpecGL-compliant
spec and how the registry would solve any problems.

> > It is an implied
> > assumption behind virtually every spec that future versions of the
> > spec will be "backword compatible" if it makes sense to support such
> > compatibility or "explicitely deprecated" if it does not.
>
> I don't think so either. When a spec is completely rewriten and
> restructured (like between XPath 1.0 and XPath 2.0), there is no
> assumption that the definitions found in the both versions will be
> easy to match.
>
> If the definitions were formally identified, this match would be trivial
> to perform.

Looks like you are talking about identifying normative text in a spec.
IIRC, this is already covered by SpecGL. If it is not, it must be a
general requirement, but there is no need to introduce a yet another
"framework" like "public interface".

> What I mean is that when you develop a lot of "small" specs like the
> W3C XML related specs, they become a nightmare to maintain if you
> need to publish new editions of the whole collection each time one
> of them is edited and that seems to become the case with the example
> of XML 1.1.

You need to explain why those new editions are needed to be published,
and how naming a normative snippet "public interface" would solve the
problem. So far, you have been talking about the need for new
editions, but it is not clear to an XML non-guru why those editions are
needed. In your explanation, please assume that all specs in question
are SpecGL-compliant.

> My proposal tend to replace the need for publishing new editions with
> the need of eventually doing certifications of specs. In this case,
> XPath 1.0 would need to be "certified" with XML 1.1 to check that
> nothing is broken which is different from needing a new edition.

I do not understand. If certification says that nothing is broken,
then there is no need for the new edition. If certification says
otherwise, a new edition is needed. How is that different from the
current situation where a spec editor or WG should do their own
"certification" (same work, but they would not call it certification)
to figure out whether they need a new edition?

> > If XML 1.1 is backward compatible with XML 1.0, there should be no
> > reason to update 80% of X* specs. If it is not backward compatible, a
> > careful rewrite would be required anyway. Note that "backward
> > compatible" status may depend on a particular context/way in which an
> > X* spec is using XML 1.0.
>
> XML 1.1 is not backward compatible with XML 1.0. but a rewriting of
> XPath 1.0 (to keep this exampe) isn't necessary since the new definition
> of a "XML name" is compatible (AFAIK) with the syntax of XPath.

So where is the problem then? If XPath refers to XML 1.0 (as it
should), the current XPath spec is fine. WG may publish a note saying
that XPath 1.0 works fine with XML 1.1 if they wish. If XPath refers
to XML without mentioning its version, no note is needed.

XPath WG may release XPath 1.1 that uses both XML 1.0 and XML 1.1 if
they want to, of course. Such edition would be trivial if XML 1.1 is
backward compatible with XML 1.0 in XPath context. If it is not
compatible (in XPath context), a major edition would be required.

Moreover, XPath WG may release XPath 1.1 that says that XPath is using
any version of XML where "XML name" is defined as in XML 1.0. That
would be fine too (if XML name is the only point of contact between
XPath and XML).


Again, I do not see how declaring XML name a "public interface" would
significantly improve the situation in the case with XPath or in
general. With "public interfaces" or without them, the WG needs to
evaluate whether or how they should react on the appearance of new
spec versions for the specs they refer to. No way around that unless
you want to prevent spec authors from breaking backward compatibility
(which would be a very different issue).

Thanks,

Alex.

-- 
                            | HTTP performance - Web Polygraph benchmark
www.measurement-factory.com | HTTP compliance+ - Co-Advisor test suite
                            | all of the above - PolyBox appliance

Received on Wednesday, 30 October 2002 11:24:41 UTC