From owner-incits-v1@incits-v1.org Tue Jun 19 11:59:56 2007
MIME-Version: 1.0
Content-type: text/plain; charset=us-ascii
Date: Tue, 19 Jun 2007 14:59:12 -0400
From: Rex Jaeschke <rex@RexJaeschke.com>
Subject: RE: INCITS-V1: NoteExampleConfusion-Durusau-3
In-reply-to: <200706182101.l5IL1OQg236487@jurassic-x4600.sfbay.sun.com>
Sender: owner-incits-v1@incits-v1.org
To: incits-v1@incits-v1.org
Reply-to: incits-v1@incits-v1.org
Organization: C#, VB, .NET, C, C++, Java Seminars and Consulting
Content-language: en-us
Thread-index: Acex6+iHeIwoqUh+RkyAG6hYoD/3vQAsJ3AQ
X-PMX-Version: 5.2.0.264296

I think the real question to consider regarding this comment is, 

   "What is the material impact of not making such a change?"


Part 1, Clause 7, "General Description", states: "Examples are provided to
illustrate possible forms of the constructions described. Notes are provided
to give advice or guidance to implementers or programmers." and "Except for
whole clauses or annexes that are identified as being informative,
informative text that is contained within normative text is indicated in the
following ways:

1. [Example: code fragment, possibly with some narrative ... end example]
2. [Note: narrative ... end note]
..."

Blocks of informative text do not nest; that is, a marked example should not
contain a separately marked note, and vice versa. As a result, text marked
at an example might contain an example plus text that, considered on its
own, might be placed in a note, and vice versa. 

In any event, examples and notes are informative. As such, they are intended
to provide expository material that is useful, but not necessary, for
conformant implementation of the standard. 

If the contents of a specific example might better be described as a note,
or vice versa, a comment along those lines might be appropriate. However,
saying that "there are many of these" without citing the instances
specifically, or citing a pattern, seems to me unlikely to result in the
supposedly desired outcome, especially if no justification is given for the
request. (I certainly don't buy the claim that readers will be confused.)

Patrick gave two examples:

A. "2.9.6 lvl (Numbering Level Override Definition) which has an
[Example...end
example] followed immediately by a [Note: ...end note] with no discernible
difference between the two."

Given that both annotations contain note text and an example, I think it's
subjective as to which should be used. (As stated earlier, a note can
contain examples, and an example can contain notes.)

B. "2.7.3.18 styles (Style Definitions), where an [Example...end example]
occurs that is clearly a note, at least in the ISO sense of the word."

I think that Note is a better fit here. (Patrick, could you please point me
to the definition of "the ISO sense of the word" 'note'?)

The lack of such a change as proposed is not seen by this editor as an
obstacle to adoption of the standard, but rather, a somewhat subjective
editorial refinement. 

Rex

----------------
Rex Jaeschke   http://www.RexJaeschke.com   Skype: RexJaeschke
2051 Swans Neck Way, Reston, VA, 20191-4023, USA
Phone: +1 703 860-0091, Fax: +1 703 860-3008


> -----Original Message-----
> From: owner-incits-v1@incits-v1.org [mailto:owner-incits-v1@incits-
> v1.org] On Behalf Of jon.bosak@sun.com
> Sent: Monday, June 18, 2007 5:01 PM
> To: incits-v1@incits-v1.org
> Subject: INCITS-V1: NoteExampleConfusion-Durusau-3
> 
> Responding to Patrick's repeated requests that we try to get some
> of this discussion done by mail, I am (at last) trying to catch up
> with his comments.  I regret that other work has prevented me from
> getting to this till now.
> 
> In his comment Durusau-3, Patrick notes that "there appears to be
> no consistent editorial principle applied to distinguish between
> notes and examples in the text. Text that looks like examples
> appear in notes and what are probably notes appear in examples
> with no distinguishable principle for the use of one over the
> other."
> 
> I agree with Patrick that this confusion is inappropriate in an
> ISO Standard.  It should be corrected before the specification is
> given that status.
> 
> Since resolution of this issue is straightforward (if tedious),
> there should be no delay in assenting to Patrick's proposed
> change.
> 
> Jon
> 




