Re: [office] Restoring examples in OpenFormula spec

[robert_weir@us.ibm.com]

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

Regards,

-Rob