ORA-XQ-093-E: Please explain the grammar note and whitespace rule conventions

SECTION 2.6.5: pragmas

Rule [1] "Pragma" is followed by a C-style comment
/* gn:parens */.  I think this is the first rule in the specification
with such a comment.  What does this mean?  I expected to find a 
section near the beginning of the specification, possibly called
"Conventions" or the like, to explain your metalanguage.  
I see that XML 1.0 did something similar with their
VC and WFC notes, which was never explained as a convention 
either, but at least they put the specification of the 
validity constraint or well-formedness constraint shortly
after the occurrence of the VC or WFC note.
In your case, it turns out that you have placed all the 
/* gn: ... */ in one place, in Appendix A.1.1. "Grammar 
notes".  Similarly the /* ws:... */ comments are collected
in Appendix A.2.1 "White space rules".  It would help the reader
to have a conventions section near the beginning to explain
this convention.  Perhaps your reply is that you already have 
hot links on these things.  That is fine for people reading the
document on the web, but not everyone wants to read the spec
in a browser.  The problem with browsers is that it is difficult
to flip back and forth between sections, which is fairly easily
done in hardcopy with sticky notes, or just a finger or pen stuck 
between pages.  Hot links do not justify never explaining your
conventions.

- Steve B.

Received on Tuesday, 17 February 2004 11:16:23 UTC