Re: [relax-ng] compact syntax: feedback from RelaxNGCC

[James Clark <jjc@jclark.com>]

> The primary reason of this is that we need to quote all PCDATAs inside
> elements.

The obvious solution to this is to provide an additional string syntax that 
either uses a multi-character delimiter or a user-specified delimiter.  For 
example, Perl has the sh here syntax:

<<END
Any number of
lines ending with a line containing what follows <<
END

> The difference of the order of annotations/RELAX NG elements is another
> reason. With the XML syntax, you write
>
> <element name="foo">
>   <cc:java>code();</cc:java>
>   <empty/>
> </element>
>
> which makes it clear that the code will be executed *after* <foo> is
> seen.
>
> With the compact syntax, you write as
>
> [ cc:java ["code();"] ]
> element foo {}
>
> and this obfuscates the abovementioned order relationship.

Part of the problem here is that RELAX NG has rather unstructured approach 
to element annotations.  It simply says you can have annotations in these 
places without saying what they are annotations on.  This has a number of 
negative conssequences.  One is that it is difficult for an implementation 
to doing anything useful with annotations in a generic way.  Another is 
that it is hard to design an alternative syntax.  I found I had to make 
some assumptions about what annotation elements were on in order to design 
the compact syntax for annotations.  I chose to follow the example of the 
one annotation element we have standardized, namely a:documentation. Thus 
initial a:documentation children are treated as supplying information about 
their parent element.

Unfortunately, this assumption is not correct in the case of cc:java, so, 
as you point out, the syntax does not work well in this case.

However, I think cc:java is inherently a difficult case.  Imagine trying to 
do it with a:annotation in W3C XML Schema.  The difficulty is that, if I 
have a understood it correctly, it is not an annotation on a pattern, but 
rather an annotation on a transition between patterns, which has no 
explicit representation in the syntax.  There is some support for this case 
already in the form of ">>" but this really works only for transitions out 
of a pattern.  We don't have any way to annotate a transition into a 
pattern.   We could adopt syntax like

element foo {
  cc:java [ "code();" ] >> empty
}

(I don't yet know whether that specific syntax could be made to work.)

> This makes me wonder what the use of annotation syntax is. We know two
> use of RELAX NG annotation, ooRelax and RelaxNGCC; both don't work quite
> well with the compact syntax.

ooRelax isn't a use of RELAX NG annotation.

Your point about the potential awkwardness of the string literal syntax is 
I think a general one, and one we could solve if we wanted to.

Your point about cc:java is specific to RelaxNGCC (and applications with a 
similar function). It doesn't apply to any application which wishes only to 
put annotations on patterns/name classes/grammar components; I suspect such 
applications are in the majority.

> Does this merely mean that those two applications are exceptions? Or is
> there any room for the improvement?

I think it is inevitable that annotations will be relatively more awkward 
in the compact syntax.  In the XML syntax, RELAX NG and annotations are 
syntactic equals: they are both equally painful/verbose.  However, in the 
compact syntax, RELAX NG is syntactically privileged -- it has a syntax 
designed specifically for RELAX NG -- whereas annotations are using a 
generic syntax.  The most user-friendly compact syntax for something like 
RelaxNGCC would be achieved not by using annotations but by designing a 
special purpose extension to the compact syntax.  For example, ideally with 
RelaxNGCC I shouldn't have to quote Java at all: the syntax would know 
about the lexical conventions of Java.

James