[relax-ng] Compact syntax div/a:documentation

[James Clark <jjc@jclark.com>]

I like the ## syntax proposed by John Cowan for a:documentation, and the
bare braces for <div> is quite intuitive, but I don't think the play well
together.  Imagine something like this

<grammar>

<div>
<a:documentation>Inline elements</a:documentation>

<div>
<a:documentation>Emphasis</a:documentation>

<define name="em">...</define>
<define name="strong">...</define>

</div>

<div>
<a:documentation>Technical</a:documentation>
<define name="code">...</define>
...
</div

</div>

<div>
<a:documentation>Block elements</a:documentation>

<define name="p">...</define>
...
</div>
</grammar>


Using the current syntax this would become:

## Inline elements
[] {

## Emphasis
[] {
em = ...
strong = ...

}

## Technical
[] {
code =...
...
}

}

## Block elements
[] {

p = ...

}

This seems pretty ghastly to me.  I would prefer to write something

#* Inline elements

#** Emphasis

em = ..
strong = ...

#** Technical

code = ..

#* Block elements

p = ...


In other words, # followed by N or more "*" characters (N > 1) starts an
N-level heading.  An N-level heading is a <div> with an <a:documentation>
that extends up to the next heading of level <= N.  (This would also work
nicely with outline mode in Emacs.)

You would still use "##" for comments that attach to something other than
div, and you would still use {} for divs with annotations other than
a:documentation.

I think <a:documentation> on <div> is at least as important as other uses of
<a:documentation>.  In many DTDs there are more comments that conceptually
apply to a <div> than comments that conceptually apply to a single
declaration.

James