[relax-ng] a:documentation compact syntax

[James Clark <jjc@jclark.com>]

I have been implementing the ## syntax for a:documentation and have run into
a couple of issues:

1. What is the relative order of ## comments wrt to other annotations? For
example, is it

(a)

[a:defaultValue ="foo"]
## doc
attribute foo { text }

or

(b)

## doc
[a:defaultValue="foo"]
attribute foo { text }

?  I prefer (b) and see no need to allow (a).

2. What about comments on the implicit top-level <grammar> element?  For
example,
## doc
start = element foo { empty }

will naturally turn into

<grammar>
  <start>
    <a:documentation>doc</a:documentation>
    <element name="foo"><empty/></element>
  </start>
</grammar>

i.e. the ## comment ends up on the <start> element rather than the <grammar>
element.

How do you specify a:documentation so it applies to the implicit <grammar>
element?

Possible answers include:

(a) If you need this, make the grammar explicit:

## doc on grammar
grammar {
  ## doc on start
  start = element foo { empty }
}

(b) Use a:documentation annotation:

namespace a = http://relaxng.org/ns/compatibility/annotations/1.0";
a:documentation [ "doc on grammar" ]
## doc on start
start = element foo { empty }


(c) If there are declarations, then ## comments before the declarations turn
into a:documentation on the grammar:

## doc on grammar
namespace x = "whatever"
## doc on start
start = element foo { empty }

(d) Introduce some specific syntax for this.

(e) Make

## doc
start = element foo { empty }

produce an a:documentation on the <grammar> element and use

## doc on grammar
[]
## doc on start
start = element foo { empty }

to get the the a:documentation on the <start> or <define> element. (This
implies allowing option (a) of issue 1.)

I am not entirely happy with any of these.  Although (c) is natural, it is
bad that it fails when there are no namespace or datatype declarations. (a)
seems about the best choice; if we adopt (a), we should probably take a
similar view wrt annotation attributes on the grammar element and require

[xml:lang = "en"] grammar {
  start = ...
  ...
}

instead of allowing

xml:lang = "en"
start = ...
...

James