OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

office message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [office] Restoring examples in OpenFormula spec

"David A. Wheeler" <dwheeler@dwheeler.com> wrote on 05/08/2008 04:52:02 PM:

> 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.
> 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
> ]
> 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.

A few principles we need to uphold.  First the definitions should be complete enough by themselves that the function is well-defined. The examples should not be adding any clarity that isn't already there.  So, in theory they should not be necessary.  But in practice they may be useful.  Whether they are in-line, or in an Annex ("informative illustrations of formula use") is an open question to me.  I think this is a similar question to how we place our schema fragments.

But one thing we should certainly ascertain, is whether the answers in these examples were calculated from a reliable source.  I'm finding cases in OOXML where the mathematical definition is flawed, but the examples given in OOXML seem to totally ignore the definitions give in the standard.  So the examples given are just dumps of Excel's calculations.  So there is really no checking of results.  

So if we do include example test cases, we should calculate each one, from the definition provided in the function, using a trustworthy calculation engine, like an HP calculator, or Mathematica or something like that.  Knowing that Excel, OpenOffice, KSpread, etc, all share the same answer for a formula doesn't say anything whether our text is correct.  Think clean room.  Given the standard, a calendar, a calculator, and a copy of Abramowitz and Stegun, what value do you get for each example?  Do this first, and then check with Excel.  If there is a discrepancy, then we add to the list to investigate.

If we do this, I think we will have done an exemplary check of our definitions as well as our examples.   If we do this, I'll certainly volunteer to do my share of the work.



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]