Misuse of XML namespaces; call for help in marshalling arguments

[Simon North]

I feel a bit like a traitor for posting an XML question here, but no-one in
comp.text.xml
seems to be bothered by my concerns, and this group is a more likely place
for
markup purists ... so, with excuses, the following

I am documenting C++ classes. We have created an authoring environment and
the developers write the text themselves.

I edit and output the XML instances. I've created my own code (DTD,
schema,
XSLT stylesheet and CSS stylesheet) and then I pump it into RoboHelp. Works

pretty well. So far, so good.

However, IMNSHO, the XML instances are awful. The developer responsible has
used namespace prefixes as if they were a cute part of the element name
syntax. An abbreviation of the parent element name becomes the namespace
prefix for its children. The instances therefore look something like this:

<IT:IT xmlns:IAE="IAE" xmlns:IAEA="IAEA" xmlns:IAER="IAER" xmlns:IME="IME"
xmlns:IMEPV="IMEPV" xmlns:IT="IT">
<IT:N> ... </IT:N>
...
<IT:IME>
<IME:IME>
<IME:Name>...</IME:Name>
...
</IME:IME>
...
</IT:IME>
</IT:IT>

This is just a fraction; the nesting goes pretty deep.

Apart from finding this inherently ugly, my gut feeling tells me that this
is an
example of something you should NOT do with namespaces. Before I go back
and
complain, I'm appealing for help. Am I just being pedantic? ... but if I
am
right, what are the convincing arguments why this practice is wrong?

Thanks,

Simon North
technical writer



Quintiq Application Software BV
's Hertogenbosch, The Netherlands

[Peter Flynn]

Post by Simon North
I feel a bit like a traitor for posting an XML question here, but no-one
in comp.text.xml seems to be bothered by my concerns, and this group is
a more likely place for markup purists ... so, with excuses, the following

I haven't seen your post in c.t.x. But c.t.s is probably inhabited by no
greater percentage of purists than c.t.x -- just that they are probably
more knowledgeable and experienced by virtue of having done this stuff for
longer.

WARNING: crossposted to c.t.x. Followups set to c.t.x

Post by Simon North
I am documenting C++ classes. We have created an authoring environment and
the developers write the text themselves.
I edit and output the XML instances. I've created my own code (DTD,
schema, XSLT stylesheet and CSS stylesheet) and then I pump it into
RoboHelp. Works pretty well. So far, so good.
However, IMNSHO, the XML instances are awful. The developer responsible
has used namespace prefixes as if they were a cute part of the element
name syntax. An abbreviation of the parent element name becomes the
namespace prefix for its children. The instances therefore look something
<IT:IT xmlns:IAE="IAE" xmlns:IAEA="IAEA" xmlns:IAER="IAER" xmlns:IME="IME"
xmlns:IMEPV="IMEPV" xmlns:IT="IT">
<IT:N> ... </IT:N>
...
<IT:IME>
<IME:IME>
<IME:Name>...</IME:Name>
...
</IME:IME>
...
</IT:IME>
</IT:IT>
This is just a fraction; the nesting goes pretty deep.
Apart from finding this inherently ugly, my gut feeling tells me that this
is an example of something you should NOT do with namespaces. Before I go
back and complain, I'm appealing for help. Am I just being pedantic? ...
but if I am right, what are the convincing arguments why this practice is
wrong?

No, you are perfectly correct, and this is a fine example of a ludicrous
abuse of namespaces. It's unfortunately rather common among people who have
come to XML by way of e-commerce and schemas, rather than by way of SGML and
documents. Many e-commerce (data) users have good reasons for doing this
kind of thing where a document is composed of discrete data structures each
with their own provenance. In the case of text documentation this is almost
certainly not the case.

I prefic these comments by an acknowledgment that I obviously don't
know the precise circumstances of the genesis of this markup, so what
I say may be entirely wrong for a given value of "markup", and may
need to be taken with the proverbial grain of salt. IANAL.

1. XML systems already provide for inheritance by way of descent, so
imposing it via namespaces is singularly pointless.

2. Namespaces provide a convenient way of attributing ownership of a
data structure: in this case they appear to do nothing of the sort
(although those acronyms may perhaps have a hidden meaning).

3. The value of a namespace attribute must be a URI. An acronym may well
be a local, relative URI, but it is not sufficiently meaningful for
practical use.

4. Short element type names were fine in the days of SGML when files were
punched onto cards and keystroke minimisation was important. The XML
Spec, however, makes it clear that terseness is of minimal importance.
I read this to mean that descriptive names have a semantic value which
outstrips their length.

5. If you are documenting computer procedures, then use DocBook. It was
written specifically to do exactly that. It's not perfect, but it's
very good, reliable, stable, well-supported, and easy to use. IMHO
anyone who uses anything else is either smater than Norm Walsh et al
or seriously needs their head examining.

Go tell your colleague to learn something about XML for text documents
first, and then pick a suitable DTD or Schema afterwards. Reinventing
the wheel -- and badly -- is not generally recommended approach for the
beginner.

Convert your existing instances into DocBook and retrain your authors
to use it -- there are copious amounts of software, stylesheets and
support available. Then if your colleague insists on retaining the
above format for some exogenous reason, write an XSLT transformation
to output it.

WARNING: there are many people out there who will disagree violently
with what I have said, and may be able to adduce good arguments for
retaining the namespaces (such as the need to segment the processing).
YMMV. FAQ: http://www.ucc.ie/xml/

///Peter Flynn