[relaxng-user] Teaching Relax NG

[James Clark]

J. David Eisenberg wrote:

> 1) Should instructors emphasize the XML syntax or the compact syntax? The
> XML syntax _is_ the official version, and it's the one used by W3C for
> SVG, but compact is, well, more compact.

I don't really have an answer.  The compact syntax is an OASIS committee 
spec, so it's official too, although it hasn't started on any ISO 
standardization path (yet).  If you do emphasize the compact syntax, I 
think it's important to mention the XML syntax and teach how to get the 
XML syntax from the compact syntax. Apart from that, I would suggest 
emphasizing whichever you think your audience will understand more easily.

> 2) If you look at the lecture notes, you'll see that my indenting style is
> remarkably schizoid - I was developing my own personal style as I wrote 
> the notes. Are there any "Official Relax NG Compact Syntax
> Indenting Guidelines"?

No. You can use trang to indent your RNC by using RNC input and RNC 
output.  I put a fair amount of effort into making trang's RNC output 
indent in a reasonable and systematic way.

The overall objective is to produce a readable schema.  Indentation is 
just one factor that contributes to readability.  I find compact schemas 
easier to read when they are relatively flat.  I prefer schemas that 
follow the following rules:

- always have an implicit top-level grammar

- no nested element patterns; move nested element patterns into separate 
definitions

- any closing ( on the same line as the opening ); if this makes the 
line too long or the expression hard to read, then factor part of the 
expression out into another definition

- closing } either on the same line as the opening { or on a line by 
itself aligned with the start of the keyword before the opening {

James