Lists Home |
Date Index |
- From: Ronald Bourret <firstname.lastname@example.org>
- To: "email@example.com" <firstname.lastname@example.org>
- Date: Mon, 8 Feb 1999 12:41:43 +0100
Tim Bray wrote:
> And as regards the namespace spec, I think that some people on this
> list are substantially full of shit, and are wilfully refusing to see
> how simple it is because it does not meet their own design prejudices.
> I think that spec is *way* better than the XML spec.
I've quoted this out of order because I think it is a very important point
and one that has bothered me during this whole discussion. Tim is
absolutely correct here -- the namespaces spec is *way* better than the XML
spec. There is absolutely no comparison, both from an organization and a
writing (sentence-level) point of view.
I think there are three other things to remember with respect to the
namespaces spec. First, no matter how you cut them, namespaces turned out
to be far more difficult than any of us could have imagined. We didn't, as
is the case in most programming languages, simply get them for free based
on where we declared our variables -- we had to decorate variables
ourselves. Thus, I think the discussion has often confused frustration
about technology with frustration about spec writing.
Second, watching a spec evolve is not always the best way to judge how good
it is. Throughout this discussion, I have wondered how I would have felt
about the namespaces spec had I seen it for the first time in its completed
form. No doubt I would have had some confusion, but I also would not have
been carrying pre-conceived notions from one version to the next, which is
where a lot of my confusion about the relation between attributes and
namespaces came from.
Finally, we have to remember that namespaces appear to work -- I have yet
to hear any examples on this list where they don't. Until such examples
arise, I think we have more to gain by agreeing to use namespaces than by
going off in our own directions.
> This group is notably and vocally dissatisfied with the specs, I
> am watching with attention for concrete suggestions as to how
> to make future specs better - the one premise that seems to get
> consensus, in this group at least, is "more examples". (Hmm, the
> namespace spec has tons).
OK. Enough being nice. Here's the brickbats :)
1) One idea, one term. The namespaces spec uses three terms (XML
namespace, traditional namespace, and namespace) for two ideas -- XML and
traditional namespaces. This can lead to confusion, as mail between Mark
Birbeck and me shows -- he interprets standalone "namespace" (for example,
see the definition of "declared") to mean traditional namespace while I
interpret it to mean XML namespace. (Interestingly, the spec can be read
using either definition, but it does lead to different conclusions.) A
more egregious example is the use of "entity" to mean "general entity" in
the XML spec -- this might work for the initiated, but is very confusing
for first-time readers.
2) Include negative truths as well as positive truths. In the namespaces
spec, an example would be to state that unprefixed attributes are not in
any (XML) namespace. Although this can be determined from the fact that
there are no statements saying that they *are* in a namespace, it is much
easier for the spec to say this than for the reader to work it out
themself. The reason this is important is that the definition of an XML
namespaces sets the readers expectations by stating that they include
attribute names. As another example of negative truths, non-goals are
often as useful as goals in setting the reader's expectations.
3) Be explicit about goals. Although the namespaces spec describes its
goals in general form in the motivation section, I think spelling these out
might have helped a lot. In particular, it would have saved us from having
to write "Unique names. Really. Just unique names. Nothing more.
Really." in email over and over and over.
4) Organization counts. Organization it is often harder than the writing
itself and many writing problems stem from organizational problems. The
namespaces spec is very good in this respect. The XML spec is a nightmare.
Some easy examples:
a) The definition of a document is tucked away in a section on
b) DTDs are introduced in the same section as prologs and version numbers,
but otherwise spread across the spec, including such things as putting
Conditional Sections in section 3 (Logical Structures).
c) Section 2.8 tells us that attribute-list declarations in the internal
subset take precedence over those in the external subset. This information
either belongs in, should be repeated, or should be referenced from the
section on attribute list declarations, but is not.
5) Headings matter. They set the reader's expectation for what is to come,
and if the section doesn't answer the questions raised in the reader's mind
by the heading, the result is confusion even if the section is
well-written. Except for Appendix A, the namespace spec does a good job
here. My favorite mis-leading heading in the XML spec is "Documents"
(section 2), which would have better been titled "Miscellany".
6) Include cross references. Again, the namespaces spec is very good and
the XML spec is a nightmare -- trying to find an EBNF definition and the
corresponding text when it is not in front of your face is almost
impossible without hypertext.
7) As appropriate, include motivation. Admittedly, this is thinner ice, but
it can be useful. For example, the motivation for namespace defaults is
presumably to reduce the number of prefixed elements. Including this
information gives the user something they can immediately grab on to.
Similarly, the motivation for allowing namespace declarations on any
element is presumably the ability to assemble a document from fragments, as
well as the ability to redeclare defaults. Stating this motivation
deflects the reader from wondering why on earth anybody would want to keep
changing their prefixes.
8) Restate when necessary. This is more thin ice. Succinct statements are
useful, but often overly loaded with meaning and difficult to interpret.
Maybe I'm just dense, but when I read the statement, "...default
namespaces do not apply to directly to attributes", my first reaction was
"Huh?" This statement includes two important concepts, neither of which
was immediately obvious to me.
The first is that:
a) The lack of a prefix on an element means it is in the default namespace,
if there is one.
b) Attributes can also lack a prefix.
c) Because attributes can lack a prefix, we are explicitly stating that
they behave differently from elements and do not automatically belong in a
The second is that:
a) Elements can be in an XML namespace.
b) According to the XML spec, elements implicitly have a traditional
namespace for their attribute names.
c) Thus, defaults apply to attributes indirectly in that they give the
(XML) namespace of the element containing the attribute (traditional)
Thus, although the statement is concise and correct, a clarifying sentence
or three that restated the same thing would have been very helpful.
9) Emphasize the important stuff; cover the obscure stuff. A spec has an
obligation to be thorough, so it must cover everything, no matter how
infrequently something is used. However, how it is organized and how much
is devoted to each topic strongly influences the reader's perspective.
As an example of misleading organization, the XML spec discusses such
things as comments, PIs, white space, and CDATA sections before it ever
tells us what an element looks like. This gives the impression that these
are more important. To the average reader, XML is about elements and
attributes and declaring them; white space can be forward-referenced and
the rest can be relegated to a later part of the spec without harm.
Similarly, the namespace spec could tell us how to use prefixes before
telling us how to declare them. This motivates the reader to see the
usefulness of namespaces and makes them think, "Cool! Now how do I declare
these prefix thingies?"
Quantity devoted to a subject can also be misleading. For example, the
last example in section 5.2 is the largest in the namespace spec. As a
reader, this leads me to believe it is very important, when in fact it
covers a seldom-used case. Section 2.12 (Language Identification) is
similarly misleading, although the authors in that case might have had good
reason to believe it would be more widely used than it has.
> Having said all that, people who write specs always have to try to
> do a better job next time, so this recent discourse is very very useful.
Thanks for listening. I hope this has been helpful.
-- Ron Bourret
xml-dev: A list for W3C XML Developers. To post, mailto:email@example.com
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To (un)subscribe, mailto:firstname.lastname@example.org the following message;
To subscribe to the digests, mailto:email@example.com the following message;
List coordinator, Henry Rzepa (mailto:firstname.lastname@example.org)