OASIS Open Document Format for Office Applications (OpenDocument) TC

 View Only

  • 1.  Using pictures and examples in the spec

    Posted 04-01-2013 22:49
    Hi all, there are a lot of problems in the specification of graphic objects. It is often difficult to describe unambiguous, how a shape must look. The specification of SVG solves this problems by giving examples and pictures how this example looks. In addition there exists a large set of tests. The specification of ECMA Office Open XML has some illustrations too in its normative part and some in its informative appendix L. What do you think about using XML snippets and pictures in the ODF specification? Kind regards Regina


  • 2.  Re: [office] Using pictures and examples in the spec

    Posted 04-01-2013 23:55
    <office@lists.oasis-open.org> wrote on 04/01/2013 06:48:42 PM: > > Hi all, > > there are a lot of problems in the specification of graphic objects. It > is often difficult to describe unambiguous, how a shape must look. The > specification of SVG solves this problems by giving examples and > pictures how this example looks. In addition there exists a large set of > tests. > > The specification of ECMA Office Open XML has some illustrations too in > its normative part and some in its informative appendix L. > > What do you think about using XML snippets and pictures in the ODF > specification? > Generally there is a preference for defining clearly things rather than giving examples, where at all possible.  Specifying something and then giving examples is a practice that has the potential for introducing additional ambiguities.  You can also run into situations where the examples and the specification contradict each other.  OpenXML had that issue in their formula spec, for example. But we can certainly use illustrations to specify things.  In some cases this is the most appropriate way to do it. A good reference for things like this is "ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards": http://isotc.iso.org/livelink/livelink?func=ll&objId=4230456&objAction=browse&sort=subtype 6.6.5.1 says "Figures should be used when they are the most efficient means of presenting information in an easily comprehensible form" and then goes on to give additional guidance. Regards, -Rob > Kind regards > Regina > > --------------------------------------------------------------------- > 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 >


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

    Posted 04-02-2013 06:38
    > 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


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

    Posted 04-02-2013 17:35
    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


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

    Posted 04-02-2013 21:00
    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. 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


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

    Posted 04-03-2013 20:05
    <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


  • 7.  Re: [office] Using pictures and examples in the spec

    Posted 04-02-2013 17:43
    Am 02.04.2013 01:55, schrieb robert_weir@us.ibm.com: > Generally there is a preference for defining clearly things rather than > giving examples, where at all possible. Specifying something and then > giving examples is a practice that has the potential for introducing > additional ambiguities. You can also run into situations where the > examples and the specification contradict each other. Appeared to me that the removal of the examples in draft stage caused semantic loss because a natural language lacks precision. Adding precision to language adds new ambiguities while a single example could illustrate expected interpretation. No need to be as more precise as long as the examples were there. Leaves the task to verify carefully a semantic loss in the spec, case of the sort, for instance an example with a negative value demonstrates that a negative value is permitted, but you don't always find that specified. --- A


Related Content