Re: [office] Formula draft: notes, rationales

[Michael Brauer - Sun Germany - ham02 - Hamburg <Michael.Brauer@Sun.COM>]

David,

first of all I would like to thank SC for the hard work on the 
specification. I hope I will find the time to have a deeper look at it 
in the next couple of days.

Regarding the annotations:

David A. Wheeler wrote:
> 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.
> 

OASIS has some rules about the formats in which specifications have to 
be provided. They say that there must be a PDF version, a XHTML version, 
and an editable version. The later in our case is OpenDocument, what is 
reasonable, since we are the OpenDocument TC:-)

Since we have to deliver all three formats, I think we should start 
working towards the XSLT solution. We are already using this to extract 
the RNG schemas from the specification, so the XSLT itself should not be 
a large issue. The only requirement is that those paragraphs that have 
to be removed have styles assign that allow to differ them from 
paragraphs that should remain in the specification.

I actually don't see the issue that someone may edit the stripped 
version, since it is actually only us and ISO who will ever edit the 
document.

Having that said: It's fine for me personally if the start by providing 
annotations in an annotated specification. In the long term, I think we 
should consider to move them into a separate informative document, since 
this simplifies the process of creating and maintaining the 
specification, and adds some flexibility.

Michael

-- 
Michael Brauer, Technical Architect Software Engineering
StarOffice/OpenOffice.org
Sun Microsystems GmbH             Nagelsweg 55
D-20097 Hamburg, Germany          michael.brauer@sun.com
http://sun.com/staroffice         +49 40 23646 500
http://blogs.sun.com/GullFOSS

Sitz der Gesellschaft: Sun Microsystems GmbH, Sonnenallee 1,
	   D-85551 Kirchheim-Heimstetten
Amtsgericht Muenchen: HRB 161028
Geschaeftsfuehrer: Marcel Schneider, Wolfgang Engels, Dr. Roland Boemer
Vorsitzender des Aufsichtsrates: Martin Haering