RE: [office] Restoring examples in OpenFormula spec

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

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