RE: [office] Restoring examples in OpenFormula spec

["Mary McRae" <mary.mcrae@oasis-open.org>]

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

> -----Original Message-----
> From: Patrick Durusau [mailto:patrick@durusau.net]
> Sent: Friday, May 09, 2008 10:30 AM
> To: mary.mcrae@oasis-open.org
> Cc: dwheeler@dwheeler.com; office@lists.oasis-open.org
> Subject: Re: [office] Restoring examples in OpenFormula spec
> 
> 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.
> >
> > <personalOpinion>
> >   Personally, I would rather see a large document set (which could be
> split into
> > multiple parts) with examples, sample code, etc. inline rather than a
> separate
> > document that requires me to cross-reference between two or more
> > files/documents. I also think that a specification with examples is
> easier to
> > review/understand. I've never read ISO 8879 but I constantly referred to
> > Goldfarb.</personalOpinion>
> >
> > Regards,
> >
> > Mary
> >
> >
> >
> >
> >
> >
> >> -----Original Message-----
> >> From: Patrick Durusau [mailto:patrick@durusau.net]
> >> Sent: Friday, May 09, 2008 8:44 AM
> >> To: dwheeler@dwheeler.com
> >> Cc: office@lists.oasis-open.org
> >> Subject: Re: [office] Restoring examples in OpenFormula spec
> >>
> >> David,
> >>
> >> Cutting to the part where we still differ:
> >>
> >> David A. Wheeler wrote:
> >> <snip>
> >>
> >>>> 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.
> >>>
> >>>
> >>>
> >> This is where I disagree, not that examples aren't helpful but that they
> >> are necessary in 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.
> >>
> >> There are parts of the graphics section in ODF that are at least as
> >> difficult to explain in prose as any of your functions. Should we take
> >> that to mean that we should have a graphic illustration of every aspect
> >> of graphics or charts?
> >>
> >> The point being that we could easily see a 1,500 to 2,000 page ODF
> >> standard that is mostly *non-normative* examples.
> >>
> >> Besides, examples are really a very small part of what would really be
> >> helpful.
> >>
> >> If you really wanted to be helpful why not include code from one or more
> >> project that implement these functions and capabilities in the standard?
> >> That would certainly be more helpful than any examples that you want to
> >> include with the functions. You could actually use the code in an ODF
> >> application.
> >>
> >> Make no mistake, I agree that examples are useful. I simply want them to
> >> be useful somewhere away from the normative version of the standard.
> >>
> >>>> 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.
> >>>
> >>>
> >>>
> >> Sigh, this has nothing to do with or without a mindset against dynamic
> >> documents.
> >>
> >> What I am proposing is that we create a static, normative ODF standard
> >> that has no examples, no working code from open source projects, no XSLT
> >> stylesheets, no small applications, no case studies, included with the
> >> normative text.
> >>
> >> At the same time, we can have at the OASIS site, either multiple static
> >> expanded versions of the ODF standard that add whatever you would like
> >> to see in a *expanded* version of the standard, such as examples,
> >> working code, XSLT stylesheets, small applications, case studies, etc.,
> >> right along with the normative text. Or if OASIS would host the
> >> technology, we could produce those versions on the fly.
> >>
> >> What part of that is so hard to understand?
> >>
> >> One, the normative one, is a reasonable sized standard.
> >>
> >> The others (note the plural) are just as reasonable (although not in
> >> size) but they are *not* limited to the normative text of the standard.
> >>
> >> My point being that unlike before, we don't simply have to chose one or
> >> the other. We can have a normative text that can be read in a reasonable
> >> finite amount of time and yet have other versions that are better for
> >> other purposes.
> >>
> >> Hope you are looking forward to a great weekend!
> >>
> >> Patrick
> >>
> >>
> >>
> >>> --- 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)
> >>
> >>
> >> ---------------------------------------------------------------------
> >> 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)