Re: [office] Restoring examples in OpenFormula spec

["David A. Wheeler" <dwheeler@dwheeler.com>]

Robert Weir:
>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.

Agree.  To my knowledge, that is already true except for YEARFRAC, which we
are working hard to fix.  If there are other holes, please let me know;
it is our intent to have NO differences.  The number of comments has
gone down drastically over time; implementors are busy implementing
the few pieces they hadn't already done, instead of protesting bad definitions.
I think that's a good sign.

> So, in theory they should not be necessary. But in practice they may be
>useful.

I think they are.  It's especially helpful for the ones that aren't traditional
math operators.  Let's face it, the key thing to know about SIN is that
the parameter is in radians (which we clearly state).  There's more to it,
of course, but for other functions, examples are really helpful.

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

For functions, I think it's very important to put the examples of each function
_immediately_ adjacent to the function definition.  That way, you can see the
formal definition, and examples to help you understand what that means
in practice.

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

Ah, in that case we're WAY ahead.  We took both all the definitions we could find,
AND developed a number of examples and from ALL of that developed the
definitions.   So, while it is _possible_ that a definition does not match
an example, it's fairly unlikely.

But a review through the examples would be a good idea.  In fact, it'd
be a good last-minute check to make sure that the definitions are sufficiently
clear.


Patrick Durusau:
> No, they were voted out, as I recall, because they were "normative." 

Okay.  So, "non-normative" examples are a different beast, then.
So, let's talk about non-normative examples.

> Are you saying that despite its many faults (which I agree are true) 
> that OXML is as a justification for including examples in ODF? ;-)

OXML has a ridiculous number of faults, but its faults are not my point.
We had examples for over a year before the OXML project got started,
and then we got cold feet about including that information in the spec.

One of the few things the OXML spec does _right_ is including examples, because
examples help people understand the specification.  We have them in the
hidden text; instead of hiding them, let's expose them to the reader, so
they can help readers understand the spec.

Now, one of the things they do terribly WRONG is that they do a terrible
job of fully and accurately defining their functions.  Yes, it's hard,
and I'm sure anything can be improved, but I think we've done a
better job.  But even if the definitions are perfect, examples are still
valuable to increase understanding.

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

Okay, so everyone agrees that examples are useful in understanding a spec.
Yes?

Now the only thing we're discussing is whether it should be part of the
spec being delivered, or part of some "non-normative" version.  Right?.

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

I don't think examples make a spec "bulked up".  Re-exposing the
examples restores material that many have found useful in understanding
the spec.

> I am not interested in going for length.

Me neither.  I think the measure should be "maximum clarity", and then
let the page count be whatever it is.  Let's agree on that measure, and
then discuss if examples aid or subtract from maximum clarity.

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

I think we SHOULD have a non-normative version with lots of detailed
rationale, etc.  But examples are so helpful in understanding material that
I'd prefer to re-insert examples of each function, right next
to their definitions, in even the short version.  A spec that is accurate,
but hard to understand, is less likely to be useful to its readers
than a spec that is both accurate
AND easy to understand.  Examples help with the latter.

> 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?

Sounds good, but I keep getting told that we can't submit dynamic documents to ISO.
OpenDocument can support them, and the OpenFormula spec ALREADY has hidden sections
(for the various rationales, etc.).   We haven't worked as much on the hidden parts;
I was specifically told that we had to remove all that material (automatically)
before even sending it to ISO.

Instead of trying to fight the whole mindset about dynamic documents, it'd be
easier to just include the examples.  Then the _primary_ thing that people would
"add" would already be there.

--- David A. Wheeler