RE: [chairs] New rule on which document wins when there is ambiguity

["David RR Webber \(XML\)" <david@drrw.info>]

Matthew,

The reverse is the case.  Prudent technical editors minimize the physical schema code quoted in the specification document - and refer to external files as the normative.  Use annotations in the schema themselves.  Use conceptual documentation in the specification to talk to the schema and stay at the high level so the specification addresses the "what to do" rather than the specific "how to" detail that is in the schema.  Similarly XML examples should be external.

Notice that OASIS postings to the docs.oasis-open.org strongly encourages this too - as URLs to normative schemas are persistent - so you really want to control all this so versions are managed sensibly and not all cluttering up the root directory of your docs.oasis-open.org location.

Plus don't include any documentation in the specification that people can automatically generate off the schemas for themselves using their tool of choice.

BTW - aside - please manually edit schemas so they DO NOT contain advertizements from the editing tool vendor in the file header.

Thanks, DW

-------- Original Message --------
Subject: RE: [chairs] New rule on which document wins when there is
ambiguity
From: Matthew Dovey <m.dovey@jisc.ac.uk>
Date: Sat, August 08, 2009 2:55 pm
To: "Eduardo.Gutentag@Sun.COM" <Eduardo.Gutentag@Sun.COM>,
"chairs@lists.oasis-open.org" <chairs@lists.oasis-open.org>
Cc: Mary McRae <mary.mcrae@oasis-open.org>

> Adding to Robin's explanation: you need to look at the context in which this
> rule was formulated.

<snip>

This explanation makes a lot of sense. However, I think the rule needs rewriting to properly capture the motivation and intention.

There is a more important technology question - surely it can't be beyond the wit of technology to include such external text files in the editorial versions of the spec such that the content of the text file can be slurped into the published specs when a PDF version is generated (rather than manually trying to keep both up to date). Would investigating tools to do this be something OASIS could investigate? (or are these already there, and I've just not noticed)?

Matthew