There is nothing wrong with what you are doing with a:attr/a:description. You are not straying too far.

As you probably already know, step #1 (4.1) of simplification is to discard foreign elements and attributes. As far as a conforming RELAX NG processor is concerned, foreign elements and attributes just go hasta la bye-bye.

The <a:documentation> element may not have children and that very likely will not change in the future, but you could use XHTML or DocBook or SmartDoc or whatever you want. As I recall our discussions on <a:documentation>, the committee decided not to get into the business of providing more elaborate documentation markup because there are other, more familiar vocabularies that are readily available.

I believe that the reason why an annotation must be a child is that when foreign elements are discarded in step #1, it discards child elements as well, so that if <define> were a child of an annotation, it would disappear at validation time as well. However, you can use <rng:div> for wrapping annotations; in fact, that's its main purpose. For example, this should work.

<rng:div a:contains="label"> <a:attr label="Title"> <a:description>A text title</a:description> </a:attr> <rng:define name="title.attr"> <rng:attribute name="title"> <rng:data type="token"/> </rng:attribute> </rng:define> </rng:div>

Hope this helps.

Mike