Re: [office] Restoring examples in OpenFormula spec

[Patrick Durusau <patrick@durusau.net>]

David,

David A. Wheeler wrote:
> The OpenFormula spec has examples, but they were voted out, so
> I've hidden them in the official version.  The current plan is to strip them
> out of the file entirely, using an automated tool.  Presumably, they were
> voted out because of concern that ISO wouldn't accept them.
>
>   
No, they were voted out, as I recall, because they were "normative." 
That is, if my application provides the results mandated by the example, 
then it "conforms" to the standard.

Unless we are willing to legally warrant that if you conform to the 
examples, then you conform to the standard, we can't have normative 
examples. (full stop)

That was the basis for the original decision (or at least my argument 
for the original decision) and, I think equally compelling, the reason 
why ISO standards generally don't have examples. (see more on that issue 
below)
> Yet it turns out that the OXML specification includes examples for each function,
> and ISO accepted it.  OXML includes them by labelling them as
> "Examples" and placing "[...]" around the examples (to make it clear
> that they are non-normative).  I think examples are
> valuable (that's why we had them in the first place).  Rather than remove
> them entirely, how about restoring them by using the same approach
> used by OXML?  That is, after the spec of each function, say
> [ Examples (non-normative)
>  ... the examples would go here
> ]
>
>   
Are you saying that despite its many faults (which I agree are true) 
that OXML is as a justification for including examples in ODF? ;-)

Tsk, tsk.

I have heard the "Jack/Jill got to ....." sort of arguments but it was a 
very long time ago.

I happen to agree that examples are useful, very useful in some cases, 
which I why I think there should be a *non-normative* version of ODF 1.2 
that is replete with examples. I have gone so far as to insert markers 
in the main text to support the creation of such for all the elements 
and attributes.

What I resist is the notion that we should ask members of the TC, or of 
OASIS or of any national body to read a bulked up version of ODF.

We should be clever enough to use markup in the production of a markup 
standard.

I am not interested in going for length. However impressed some 
overworked project manager might be with those sort of numbers, they 
don't really move me.

> I think including examples would make the spec MUCH easier to understand,
> and by clearly labelling them as non-normative and using the approach
> of OXML, it'd be hard to argue that they weren't acceptable
> ("you already accepted that approach!"). I even suggest adding the phrase
> "(non-normative)" to make that point abundantly clear.
>
>   
So, what about a non-normative version with the examples and other 
materials? That would allow not only some examples but as many as you 
care to insert.

Perhaps even a dynamic version where if I really want chart examples but 
no formula examples, I can have those. Or drawing examples and not 
charts. Or documents with heavy metadata examples, thinking of Bruce and 
publishers here, and not so much for formulas? Or, heaven forbid, 
someone from the Excel team who wants the examples only for the formula 
part? ;-)

We keep telling people about the advantages of markup for their 
documents. How about displaying just a bit of that for one of our own?

What do they call that? Eating your own dog food?

Hope you are having a great day!

Patrick

PS: I just got back from supper and saw Rob's reply in my inbox. +1 to 
the verified example line. I too am willing to contribute examples, 
albeit I will be more willing the more non-normative the edition in 
which they appear. It is about time that standards organizations that 
purport to be interested in markup standards did more than pay lip 
service to the use of markup. (And no, use of XHTML doesn't qualify as 
using a markup language, not this many years after the creation of XML.)



> --- David A. Wheeler
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  You may a link to this group and all your TCs in OASIS
> at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
>
>
>   

-- 
Patrick Durusau
patrick@durusau.net
Chair, V1 - US TAG to JTC 1/SC 34
Convener, JTC 1/SC 34/WG 3 (Topic Maps)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)