RE: [office] Using pictures and examples in the spec

[robert_weir@us.ibm.com]

<office@lists.oasis-open.org> wrote on 04/02/2013
05:00:28 PM:

> Subject: RE: [office] Using pictures and examples in the spec
> Sent by: <office@lists.oasis-open.org>
> 
> I think this all depends on exactly what 'pictures' are suggested.
I
> find that examples often give the impression of that it is clear what
> the intended meaning is, when it is really just an illustration of
a
> single situation and slightly different situations may still be unclear.
> 
> I can imagine as many misleading or useless illustrations as useful
> ones. 
> 

I think of the old old saying, "Never go to sea
with two compasses, because if they disagree you don't know which is right".
  Better to have one compass, or three, or even a GPS.  Even
without figures, even in just prose specification,  we avoid saying
the same thing twice in different terms.  We try to say things once,
clearly.

But it is certainly possible to use a diagram in the
specification, just as we can use mathematical equations or formal notations
like RelaxNG or EBNF.  

One way is to have a normative diagram that is the
a core part of the specification.  It defines something core, like
the mathematical equations in OpenFormula do.  It is giving the unambiguous
definition of a term, for example.

Another approach is to have "informative",
which is to say "non-normative" diagrams or examples in the text.
 I've heard various opinions on the value and wisdom of this, but
it can be done in a way that avoids contradiction and formal redundancy
if it is explicitly marked "Informative" in the specification.

Another approach, and one I'd love to get to someday,
is to keep the actual standard tight and small, but then find a way to
wiki-fy it or hypertext-fy it in a way that allows us to associated additional
information with each clause or even element, such as examples, test documents,
implementation notes, additional explanatory material, etc.  Think
of Stroustup's "Annotated C++ Reference Manual", but done for
the 21st century using RDF to guide generation of hypertext.

Regards,

-Rob

> Andreas
> 
> On Tue, 2013-04-02 at 11:34 -0600, Dennis E. Hamilton wrote:
> > I don't think the problem is one of being exemplary.  That
is 
> always a concern in a specification.   I think what is called
for in
> the situation Regina raises, consistent with Rob's comment, is the
> essential provision of a diagram in support of unambiguous specification.
> > 
> > For example, in the geometric provisions in the draw: and dr3d:
> feature sets, it is near-impossible to know what the coordinate axes
> are, what the 0-point and direction of rotation is, and from where
> is the geometry being observed (i.e., with respect to orientation
of
> the relevant axes and planes).
> > 
> > I challenge anyone to unambiguously determine where the "back"
of 
> an extrusion or rotation is and which is the "front" by
consultation
> of the specification alone.  Where does the described motion
start 
> (front or back) and where does it end (back or front)?  Which
value 
> (positive or negative) of the amount of motion brings an extrusion
> toward and away with respect to how the geometry is observed.
> > 
> > Diagrams are significant in the specification of such details.
 
> (Knowing that the right-hand rule applies is helpful but still 
> insufficient, apparently.)
> > 
> > Another place where the specification would benefit with a drawing
> is for the identification of measure-line characteristics in 
> drawings (i.e.,<draw:measure>).  
> > 
> > Then the matter of (default) units (radians, degrees, etc.) can
be
> dealt with.  
> > 
> >  - Dennis
> > 
> > -----Original Message-----
> > From: office@lists.oasis-open.org [mailto:office@lists.oasis-open.org
> ] On Behalf Of Hanssens Bart
> > Sent: Monday, April 01, 2013 23:38
> > To: robert_weir@us.ibm.com; Regina Henschel
> > Cc: ODF member
> > Subject: RE: [office] Using pictures and examples in the spec
> > 
> > > But we can certainly use illustrations to specify things.
 In 
> some cases this is the most appropriate way to do it. 
> > 
> > +1 on adding illustrations to clarify some parts of the specification
> > (actually, "19.15.1<chart:chart>, <chart:series>"
already contains
> examples of chart types,
> > so it's not unprecedented...)
> > 
> > 
> > Best regards
> > 
> > Bart 
> > 
> > ---------------------------------------------------------------------
> > To unsubscribe from this mail list, you must leave the OASIS
TC that 
> > generates this mail.  Follow this link to all your TCs in
OASIS at:
> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> > 
> > 
> > ---------------------------------------------------------------------
> > To unsubscribe from this mail list, you must leave the OASIS
TC that 
> > generates this mail.  Follow this link to all your TCs in
OASIS at:
> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> > 
> 
> -- 
> Andreas J. Guelzow, PhD FTICA
> Professor of Mathematical & Computing Sciences
> Concordia University College of Alberta
> [attachment "signature.asc" deleted by Robert Weir/Cambridge/IBM]