Re: [office-formula] Grammar (Rationales, etc.)

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

robert_weir@us.ibm.com wrote:
>
> "David A. Wheeler" <dwheeler@dwheeler.com> wrote on 03/12/2006 
> 07:54:47 PM:
>
>
> > Below is a new draft for formula syntax.  What do you think?
>
>
> Open question -- to what extent do we want to final standard to 
> contain the comments comparing the specified behavior to OpenOffice 
> and Excel?  Is this necessary or even desired?
I think the final FORMAL standard should NOT contain much (if any) 
comments on
specific implementations. A small non-normative section about them 
would, I think, be fine,
but not a lot, and certainly not a lot interspersed throughout the document.

Yet if we want to finish this year, I think we NEED to include a lot of 
information about
real implementations throughout the document. Otherwise, we'll spend all
our time repeating to each other why things were done in a certain way, 
instead
of getting things actually done.  And if we want implementations
to implement all this stuff correctly, we need to include relevant 
information
about actual implementations, hints at "good" vs. "bad" algorithms, etc.
For example, the "obvious" implementation of STDEV() you'd get by coding in
your college text's algorithm will NOT work on many real datasets.
Trying to write a separate "rationale" document later would miss the 
point... we
need to capture the information NOW, and intersperse it throughout the 
document,
so that we can justify our choices to each other, make that information 
easy to
find, and when we make changes, we know what the constraints are.

There's a trivial solution to doing BOTH, which OpenFormula used: define 
special
styles/templates for "Notes", "Discussion", "Rationale", and so on, 
where all of this
implementation-specific stuff is placed.  Then, when you want to print
the "official" specification, you just set those particular sections to 
be invisible,
and they won't be included in the final document.
All the text with a green background in the HTML and ODF files was, in
the original MediaWiki file, generated by a single template... editing the
template would suddenly cause all that text to disappear or reappear.
So, to print the "real" OpenFormula spec, you'd actually disable all the
green-background material.
If you're an implementor, you can turn that stuff back on, and get all the
goodies on WHY things are the way they are, as well as implementation hints.


 > Excel and OpenOffice do not have normative formula specifications.

True, and that's the problem we're trying to fix.
But a vast amount of the semantics are actually stable
across all spreadsheet implementations, even though they've
never been formally specified.  If users depend on a
particular behavior, and it's a reasonable behavior, then
it should be specified.

This is really a lot like many other programming language
specification efforts.  We have a poorly-defined language
("Spreadsheet formulas"?) with many minor variants, and we're
just trying to specify it enough so users can create
portable files. I don't expect "+" to suddenly do subtractions
any time soon, in anyone's implementation.  I think it's
reasonable to look at existing implementations when defining
a standard for a given language!

> So, I wonder if we want to keep the rationales and vendor comparisons 
> out of the specification and save them for another venue.  For 
> example, they might work better as a standalone article/paper, or even 
> a value add in a book, "The Annotated ODF Specification".
The problem is that we need that information shared among us NOW in 
order to create a good spec.  So, I think it's better to develop the 
rationale text in parallel, intersperse it where it's relevant, and 
release both the specification and "annotated specification".

The problem that we're having now is that we still don't have a Wiki, 
and we're trying to work by email.  Straight email text doesn't have a 
simple way to template this.

--- David A. Wheeler


P.S.  The front cover of OpenFormula as this green-background text:  
"Note: You are viewing the annotated version of this specification, 
which includes notes, rationales, discussion items, and TBD markers. The 
annotations are not normative, but may be very helpful to specification 
users."

Then OpenFormula, in the section "Document Conventions", says the following:

Information within a Rationale:, Note:, or Discussion: section is not 
normative:

    * Rationale explains why a part of the specification is defined that 
way.
    * Notes provide other information, such as tips for implementation 
or information on what various existing implementations do.
    * Discussion describes the pros and cons for a decision yet to be made.

It is expected that there will eventually be an unannotated version of 
this document, without this information, and an annotated version with 
this information.

Rationale: Throughout the document rationales are included to prevent 
questions from being asked repeatedly during development and to aid 
implementors in avoiding common mistakes. Much discussion about existing 
implementations is included; where practical, existing implementations 
should help guide any standard, and these additional notes should help 
ensure that this is true.