[Java Spec Report] RE: [metadata-jsr] General editorial remark

Josh,

I'm sure that was your intent but actually "note that" is used in
several  apparently normative contexts in the spec.  Here are the
contexts that as far as I can see are normative; I suggest the words
"note that" are simply elided from these sections.  

In the hope that these edits might actually make it into the final spec,
I've listed each specific context below along with a brief summary of
why the text is apparently normative.

(All other statements beginning "note that" do indeed seem to be
deducible from other normative text, and can therefore be left as they
are.)

Roly

Roly Perera
[email protected]

+------------------------------------------------------------------+
+ Ergnosis Ltd                  www.ergnosis.com                   +
+ Third Floor                                                      +
+ 14 King Square                CTRL + ALT + PARADIGM SHIFT        +
+ Bristol BS2 8JJ, U.K.         www.ergnosis.com/employment        +
+ +44 117 924 8915 (telephone)  Java Spec Report:                  +
+ +44 870 421 1389 (fax)        www.ergnosis.com/java-spec-report  +
+------------------------------------------------------------------+



II. Declaring annotation types

"Note that defaults are applied dynamically..."

(As originally raised by Paul.)

III. Annotations

"Note that null is not a legal element value..."

I don't believe this is already implied in the case when the
ElementValue is a ConditionalExpression.

"Note that it is legal to use single-element annotations for annotation
types with multiple elements..."

This isn't implied by the (informal, somewhat underspecified)
description of "single-element annotation" which preceeds it.  This
needs to be construed as normative text, I believe, although the same
effect could probably be better achieved by more accurately specifying
"single-element annotation".

IV. Standard Meta-Annotation Types

"Note that this meta-annotation type has no effect if the annotation
type is used annotation anything other than a class."

If we don't treat this as normative then the behaviour is undefined in
this situation, as far as I can see.

"Note also that this meta-annotation only causes annotations to be
inherited from superclasses..."

Ditto.

V. Other Standard Annotation Types

"Note that the set of warnings suppressed in a given element is a
superset..."

Once again this applies a constraint which would otherwise not apply.

VII. Library Support

"Note that the detail message associated with cause is not automatically
incorporated..."

Ditto; the word "automatically" should also be removed.  (Depending on
the intent an alternative change would be to drop the entire sentence.)


> -----Original Message-----
> From: [email protected] 
> [mailto:[email protected]] On Behalf Of Joshua Bloch
> Sent: 05 May 2004 14:37
> To: [email protected]; [email protected]
> Subject: Re: [metadata-jsr] General editorial remark
> 
> 
> Paul,
> 
>    Generally speaking, when I use the phrase "note that" I do 
> mean that 
> this is an implication of something that I've already said.  In this 
> case I probably goofed.  (I don't have the spec in front of me.)  I'm 
> happy to remove the offending phrase.
> 
>               Regards from the Eurostar,
> 
>               Josh
> 
> >The posted version of the JSR-175 Public Draft Specification 
> uses the 
> >phrase "Note that" pervasively.  I strongly suggest that you revise 
> >these uses before the next published version of these 
> materials.  The 
> >easiest revision is simply to eliminate the phrase "note 
> that" wherever 
> >it appears.
> >
> >The problem is that the phrase literally means something along the 
> >lines of either "make a note to yourself that...", which is rather 
> >condescending, or "as you can see from what you've read so 
> far".  The 
> >latter meaning is simply wrong in the case of sentences like this
> >
> >   "Note that defaults are applied dynamically at the time 
> annotations 
> >    are read; default values are not compiled into annotations."
> >
> >Nothing that I can see in the text up to that point implies 
> this, and 
> >the reader is left to face his own stupidity at not being able to 
> >deduce it out of thin air.
> >
> >As far as I can see, all the sentences that start "Note that" in the 
> >current text could be shorn of these first two words without 
> affecting 
> >their meaning or clarity, crisping up the text at some 
> savings in space 
> >and reader temper.
> >
> >Paul Hilfinger
> >_______________________________________________
> >metadata-jsr mailing list
> >[email protected]
> >http://altair.cs.oswego.edu/mailman/listinfo/metadata-jsr

---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.590 / Virus Database: 373 - Release Date: 16/02/2004
 



------------------------ Yahoo! Groups Sponsor ---------------------~-->
Buy Ink Cartridges or Refill Kits for your HP, Epson, Canon or Lexmark
Printer at MyInks.com.  Free s/h on orders $50 or more to the US & Canada.
http://www.c1tracking.com/l.asp?cid=5511
http://us.click.yahoo.com/mOAaAA/3exGAA/qnsNAA/5cFolB/TM
---------------------------------------------------------------------~->

To unsubscribe from this mailing list, send an email to:
[email protected]
 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
     http://groups.yahoo.com/group/java-spec-report/

<*> To unsubscribe from this group, send an email to:
     [email protected]

<*> Your use of Yahoo! Groups is subject to:
     http://docs.yahoo.com/info/terms/