Patrick Durusau:
> do have a general comment:
>
> From page 1:
>
> > *Note:* This is the /annotated/ version of this specification, which
> > includes /non-normative/ information (notes, rationales, and
> > TODO/TBD). These annotations will not be printed in the final official
> > specification, but they will be available to implementors as guidance
> > (as hidden text).
> >
> As a general matter, standards don't have "hidden text." Either the
> material is included in the standard or it is not.
The annotations (notes, rationales, etc.) would NOT be in the standard, if by "in the standard" you mean "printed or considered part of the specification".
My vision is that the TC maintains one database (file), from which it produces two documents:
* A formal specification. No hidden text is printed or considered as part of the specification.
* An informal "rationale" document (ISO etc. have done rationales before). The hidden text is printed and included.
Many older systems cannot generate both documents from a single source without some preprocessing. But now that ODF supports hidden text, we can make creation of standards and rationale a much more reasonable document processing process: Start from a single master document, and generate both. That way there's no problem of the formal specification getting out-of-sync with the informal rationale document.
If the idea of "hidden text" embedded in the submitted document is anathema, then you could use an XSLT program to strip it out. If you do that, I strongly recommend ONLY producing PDF files from that stripped version. The problem is that once a stripped-out editable document exists, some foolish person will then start editing that stripped-out document... making it impractical to have a CURRENT rationale.
When we didn't have today's document tools, we had to live with their limitations. But things have changed; let's use the new capabilities when they help us. Let's have a single file with both the normative and the rationale material (where the rationale is next to the normative material). Why? Because then we can completely eliminate the 'out-of-sync' problems that have plagued earlier rationales. You can then extract from the single file BOTH the normative spec, AND the informal rationale.
> One possible way to handle such non-normative material would be to
> create a separate report of notes, rationales, etc., that are keyed to
> the normative text. Implementers or users can consult those if they wish
> but conformance is to the normative text of the standard. I suspect the
> equivalent would be a Technical Report (TR) in an ISO context.
Yes, I've had to USE those turkeys, and find them painful ("Ada Rationale", anyone?). When I read a specification to IMPLEMENT something (as opposed to idle curiosity), I want to read what the normative text for topic X, AND why it's done that way (and hints on how to do it), at the SAME TIME.
Typical rationale documents involve lots of cross-references that are wrong, are subtly incorrect because one document was changed when the other one wasn't, and are really annoying for people to use (they have to keep hopping back & forth). And because they're a pain to maintain, they do NOT get maintained when the spec is changed, even marginally; so they soon because useless.
> Ideally the standard is clear enough that it can be implemented without
> reference to any material outside the standard or that is not cited by
> the standard, such as a reference to Unicode for character encoding
> issues, etc.
Oh, if it can't be UNDERSTOOD without the notes, then there's a serious problem. But there's lots of text that should NOT be normative, but is REALLY helpful to implementors:
* WHY was it done this way? What were the alternatives? Why were they abandoned? This is ESPECIALLY helpful for new reviewers. Read it yourself - you'll see that as you review, the Rationales really help you understand why we did something. And hopefully, it'll mean we have to answer fewer questions :-).
* What's the "easy" or "best" way to implement something? Sometimes the 'obvious' implementation turns out to be wrong, e.g., it's easy to implement matrix multiply in a way that works on many cases, but fails in others. You do NOT want to constrain implementors to a particular implementation approach... they may have a better way! But if there's some bits of wisdom, or words of advice, it's very helpful to have it someone. Nobody can be creative EVERYWHERE.
> Hope everyone is having a great day!
Yes, thanks for your time! We know that there are important TBDs left here, but getting your feedback NOW is extremely helpful in getting this ready. Thanks again.
--- David A. Wheeler