Conformance Section on Ruby

Dear Ruby editors,

Thank you for the clarity of your specification on Ruby which is very 
easy to read.

How-to improve your specification?

+ Mandatory:

  Please, could you add a conformance section to your specification?
I encourage you to add a section 4. in your document with conformance 
checkpoints.
	Conformance for documents
	Conformance for authoring tools
	Conformance for viewers
	etc.

	See a good example of a conformance section in 
http://www.w3.org/TR/SVG/conform.html

+ Suggestions:

  - Could you define testable assertions in your document. By testable 
assertion, I mean a formal definition (for example for an element) 
that is testable and can help test suite builders to create tests?

  - I know that Ruby is intended to be a part of the whole XHTML 
modularization package and as you have written in 2. "Some 
familiarity with the XHTML Modularization framework, in particular 
the "Modularization of XHTML" [XHTMLMOD] specification, is assumed."

But Imagine you're a developper who is trying to implement the Ruby 
specification. In 2.1, Abstract definition of ruby elements... you 
have created a very useful tables.

I want to implement the ruby element, I see that the attributes are 
Common... ok but what Common means? So, I continue to read the 
specification. In 2.2, at the end of the section, I can read:

"The ruby element has common attributes only. Examples of common 
attributes include: id, class or xml:lang. Common attributes depend 
on the markup language with which ruby annotations are used. In the 
case of [XHTML 1.1], these are defined in XHTML Modularization, 
Section 5.1 [XHTMLMOD]."

So I click on the XHTML Modularization to find section 5.1, I have to 
look for the Common attributes. And I can see 4 sets of attributes... 
and I need to click again... for example Core...
And it said in a table: , an
	Core: class(NMTOKENS), id (ID), title (CDATA)

to know what's a NMTOKENS for example, I click again and finally have

	NMTOKENS: One or more white space separated NMTOKEN values

but the definition of NMTOKEN is given just above as

	NMTOKEN: A name composed of only name tokens as defined in XML 1.0

with a link to the reference of XML spec, and finally a link to the 
XML spec and not the place where tokens are defined in the XML spec.

Don't worry about this particular example, it's just illustrative how 
it could be difficult for a developper to implement one of our 
specifications.

Our specifications need to be normative and serious, but also easy to 
read and implement for developpers if we want to have better 
implementations, so better use of our technologies.

So, if you could find a way to summarize the information in a 
developper point of view it could be useful.






-- 
Karl Dubost - http://www.la-grange.net/
Près de vous, madame, oubliant les cieux,
L'astronome étonné se trouble;
C'est dans l'éclat caressant de vos yeux,
Qu'il avait cru trouver l'étoile double.

Received on Tuesday, 15 May 2001 05:22:09 UTC