XML Accessibility guidelines (29 Aug): section 4.9

The example for the guideline 4.9 seems to be rather unfortunate.
While I would agree with the guideline, I don't agree at all with the
example.



the "wrong" example says of 

   <element name="paragraph">
    <xsd:annotation>
    <xsd:documentation>paragraph</xsd:documentation>

Here the element name has been described using the element name only,
which adds no semantic value.

and suggests replacing the documentation with 

   <xsd:documentation>The lowest level block container.
    </xsd:documentation>


However "paragraph" does have long established semantic as a construct
in the grammar of natural languages, and that semantic is _not_ 
"block container". 

The author of this section presumably had the html p element in mind.
unfortunately it is true that html p has semantic of "lowest level block
container" but most other document types this is not true.

For example the sematic of a docbook <para> element  is precisely as in
your "wrong" example; it denotes a paragraph. It explicitly is _not_ the
lowest level block container, paragraphs contain sentences, and
sentences often contain block elements such as displayed lists and
formulae.

Even in XHTML, I understand (from a comment on the public spec-prod list)
that the HTML working group is looking into ways of improving the
content model of <p> so that it allows displayed lists. Adding <ol> and
<ul> to the content model of p, would be consistent if p had been
documented as "paragraph", but would be an incompatible change if it had been
documented as the lowest level block.


An example where the element name didn't have any inherent meaning, or
might be construed to have the wrong meaning might be better.

One example from my own area: MathML's <sin/>

documenting this as "sin" might lead the unsuspecting to think
mathematicians are not honest.

documenting it as 

<description>
					<p>This element represents the sin function as described 
in Abramowitz and Stegun, section 4.3. It takes one argument. </p>
				</description>

(which is the definition copied from appendix C of the MathML spec) is
clearer....



David

_____________________________________________________________________
This message has been checked for all known viruses by Star Internet
delivered through the MessageLabs Virus Scanning Service. For further
information visit http://www.star.net.uk/stats.asp or alternatively call
Star Internet for details on the Virus Scanning Service.

Received on Thursday, 4 October 2001 04:39:51 UTC