OASIS Open Document Format for Office Applications (OpenDocument) TC

Expand all | Collapse all

Restoring examples in OpenFormula spec

  • 1.  Restoring examples in OpenFormula spec

    Posted 05-08-2008 20:52
    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.
    
    --- David A. Wheeler
    


  • 2.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-08-2008 22:28

    "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


  • 3.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-08-2008 22:46
    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)
    
    


  • 4.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 03:49
    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
    


  • 5.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 12:44
    David,
    
    Cutting to the part where we still differ:
    
    David A. Wheeler wrote:
    


  • 6.  RE: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 13:31
    Hi everyone,
    
      I think it's important to realize that one set of files will become an OASIS
    Standard. That set of files must not have "hidden content" in the underlying XML
    as it would be impossible to determine exactly what makes up the standard
    itself. Hidden content would not have been subject to public review unless the
    reviewer knew how to access it.
    
      There can be only one Standard. Creating a separate document set and calling
    it "expanded" would not be allowed. It would have to have a different name, and
    in order to have any official standing would be subject to the same review
    process as any other TC document. 
    
      The TC *could* create separate documents containing examples that can be
    linked back to the specification, but if you want to produce a version of the
    standard that contains all of the examples, etc. then that needs to be the
    version that goes out for member review and is voted upon.
    
    
    
    Regards,
    
    Mary
    
    
    
    
    
    > 


  • 7.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 14:31
    Mary,
    
    I find it amazing that you cite the one example of a "standard" that I 
    would use as an example of what I would like to see done.
    
    The Goldfarb handbook is precisely the sort of thing that I would like 
    to see done with ODF.
    
    Yes, fine, we won't call the version with examples, code, etc. a 
    "standard."
    
    We will call it "The ODF Missal" or some such and say that it includes 
    parts of the ODF standard.
    
    The "standard" parts are no less parts of a standard because they are 
    decorated with non-normative material.
    
    That is in line with your example.
    
    Hope you are having a great day!
    
    Patrick
    
    Mary McRae wrote:
    > Hi everyone,
    >
    >   I think it's important to realize that one set of files will become an OASIS
    > Standard. That set of files must not have "hidden content" in the underlying XML
    > as it would be impossible to determine exactly what makes up the standard
    > itself. Hidden content would not have been subject to public review unless the
    > reviewer knew how to access it.
    >
    >   There can be only one Standard. Creating a separate document set and calling
    > it "expanded" would not be allowed. It would have to have a different name, and
    > in order to have any official standing would be subject to the same review
    > process as any other TC document. 
    >
    >   The TC *could* create separate documents containing examples that can be
    > linked back to the specification, but if you want to produce a version of the
    > standard that contains all of the examples, etc. then that needs to be the
    > version that goes out for member review and is voted upon.
    >
    > 
    >
    > Regards,
    >
    > Mary
    >
    >
    >
    >
    >
    >   
    >> 


  • 8.  RE: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 15:04
    Hi Patrick,
    
      Yes, that was exactly the point I was trying to make - I think it would be
    *useful* to a particular constituency to have an "annotated" spec that has a
    unique title, that doesn't claim to *be* the specification, and that explicitly
    refers to the specification itself at each appropriate spot for the normative
    version. And I'd even like to see them hyperlinked across documents :-) And even
    better, since our Standards are freely available, we wouldn't have to worry that
    people wouldn't have access to the official version.
    
    Regards,
    
    Mary
    
    > 


  • 9.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 20:32
    Patrick Durusau:
    > This is where I disagree, not that examples aren't helpful but that they 
    > are necessary in the normative text.
    
    They wouldn't be normative, they'd be adjacent to the normative text.
    
    > There may be a very limited number 
    > of cases and the directives so concede where examples may be necessary.
    > 
    > HOWEVER, it is clear from your response that you are taking this as an 
    > opportunity to insist on having examples for every function. I really 
    > don't think anyone needs an example of the "+" function, for example. Or 
    > a large number of others, assuming that we do our job correctly as a 
    > committee and write really good prose and/or notation.
    
    Ah, so THAT'S the issue, you don't want to see them with EVERY function.
    
    We _could_ expose examples on only selected functions.
    The trick would be deciding which ones, then.  Sadly, making that
    decision on a case-by-case basis would obviously take additional time;
    I don't know if we have that kind of time.
    
    I want the spec to be superior to OXML in every way (a very low bar indeed).
    The only thing I can see that's better about OXML is that it includes examples.
    We HAVE them, but we have removed ours from view, because we believed
    that ISO wouldn't accept a spec with lots of examples.  Clearly that's not so.
    Indeed, why _is_ OXML acceptable? It includes function examples.
    
    > The point being that we could easily see a 1,500 to 2,000 page ODF 
    > standard that is mostly *non-normative* examples.
    
    It's not too bad with the OpenFormula spec; even displaying all hidden text it's
    not THAT many pages.
    
    --- David A. Wheeler
    


  • 10.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 22:23
    David,
    
    Expand your focus just a bit!
    
    David A. Wheeler wrote:
    


  • 11.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 20:58
    David A. Wheeler wrote:
    
    > Sounds good, but I keep getting told that we can't submit dynamic documents to ISO.
    
    Yes, ISO is using only dead-trees and PDF for publication and
    distribution of their standards. Working documents can be also provided
    in HTML and DOC, but I don't think you want convert ODF spec into DOC
    for ISO purposes ;-)
    
    > 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.
    
    I think that informative examples will be useful and also acceptable for
    national bodies.
    
    -- 
    ------------------------------------------------------------------
       Jirka Kosek      e-mail: jirka@kosek.cz      http://xmlguru.cz
    ------------------------------------------------------------------
            Professional XML consulting and training services
       DocBook customization, custom XSLT/XSL-FO document processing
    ------------------------------------------------------------------
      OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
    ------------------------------------------------------------------
    
    


  • 12.  Re: [office] Restoring examples in OpenFormula spec

    Posted 05-09-2008 07:26
    David, all,
    
    Patrick Durusau wrote:
    > David,
    > 
    [...]
    > 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 this is a good idea, and I also see not problems with 
    maintaining this. We currently have an editable version of the formula 
    spec which contains the examples and we remove them using XSLT when we 
    publish documents. That's one option.
    
    For the main specification we currently have a version that does not 
    contain cross references but we add them automatically based on 
    information from the schema. We don't do that once, but dynamically for 
    every draft. So keeping the examples separate and inserting them then a 
    non-normative version if requested should work as well.
    
    ODF + RNG + XSLT is powerful enough to do all that.
    
    Michael
    > 
    
    
    -- 
    Michael Brauer, Technical Architect Software Engineering
    StarOffice/OpenOffice.org
    Sun Microsystems GmbH             Nagelsweg 55
    D-20097 Hamburg, Germany          michael.brauer@sun.com
    http://sun.com/staroffice         +49 40 23646 500
    http://blogs.sun.com/GullFOSS
    
    Sitz der Gesellschaft: Sun Microsystems GmbH, Sonnenallee 1,
    	   D-85551 Kirchheim-Heimstetten
    Amtsgericht Muenchen: HRB 161028
    Geschaeftsfuehrer: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
    Vorsitzender des Aufsichtsrates: Martin Haering