Re: [PATCH] MIPS: IEEE 754-2008 NaN encoding features

["Maciej W. Rozycki" <macro at codesourcery dot com>]

On Thu, 11 Jul 2013, Richard Sandiford wrote:

> >> --------------------------------------------------------------------------
> >> This option indicates whether the source code uses the IEEE 2008
> >> NaN encoding (@option{-mnan=2008}) or the original MIPS encoding
> >> (@option{-mnan=legacy}).  It is equivalent to adding a @code{.nan}
> >> directive to the beginning of the source file.  @xref{MIPS NaN Encodings}.
> >> 
> >> @option{-mnan=legacy} is the default if no @option{-mnan} option or
> >> @code{.nan} directive is used.
> >> --------------------------------------------------------------------------
> >
> >  Quite a bit sorter!  However the directive does not have to be at the 
> > beginning (the setting cannot be flipped so the last one wins).  I have 
> > therefore removed "the beginning of".  I have shortened the index entry 
> > too, to follow our usual format.
> 
> Hmm, but I suggested that because I thought any ".nan" in the source
> code would override the command-line option.

 Yes, ".nan" overrides the corresponding command-line options (any number 
of them), however it does not operate like ".set foo" does, only taking 
effect from its location on.  As the last ".nan" setting ultimately wins, 
the description could say:

"It is equivalent to adding a @code{.nan} directive to the end of the 
source file."

and would still be accurate.  However I've thought this would be an 
overkill and too confusing ("Why do I need to add it at the end?").  The 
usual and expected scenario is to put one ".nan" somewhere in a source 
file, typically within the ".attribute", ".abicalls", etc. stuff at the 
beginning, but not necessarily on the first line.  This is I believe 
roughly implied by the wording I chose:

"It is equivalent to adding a @code{.nan} directive to the source file."

-- in common understanding I believe this implies "... where there wasn't 
one before."  Whereas I think:

"It is equivalent to adding a @code{.nan} directive to the beginning of 
the source file."

does not necessarily imply there must not be an opposite ".nan" setting 
later on.

>  "At the beginning"
> seemed important if the source file also has a ".nan".

 I can't comprehend it, sorry, can you please reword it/elaborate?

> >> > +@cindex MIPS IEEE 754 NaN data encoding selection
> >> > +@kindex @code{.nan legacy}
> >> > +@kindex @code{.nan 2008}
> >> > +These directives control the encoding of the special not-a-number (NaN)
> >> > +IEEE 754 floating-point symbolic data.
> >> 
> >> IMO "values" reads better than "symbolic data".  (IEEE754 itself refers
> >> to them as "values".)
> >
> >  You may not like the wording, which I think is a matter of personal 
> > taste, but you're wrong as to IEEE 754:
> >
> > "2.1.35 NaN: not a number -- a symbolic floating-point datum. [...]"
> >
> > (in the Definitions section) and the document seems to carefully avoid the 
> > use of "value" in the context of NaNs (quite understandingly, as these 
> > entities are the opposite of values).
> >
> >  Also:
> >
> > "2.1.27 format: A set of representations of numerical values and symbols, 
> > perhaps accompanied by an encoding."
> >
> > -- i.e. the standard makes a clear distinction between values and symbols 
> > and I think our documentation should follow the formal standard.
> 
> Perhaps I put too much store by NaNs being listed under "Sets of values".

 This is "3.3 Sets of floating-point data" now I believe.  This looks like 
an area that got changed/clarified compared to the 1985 version then 
(which I don't have readily available).

> (At least in the 1985 version.  I didn't want to pay for a copy of the
> 2008 version just to review this patch.)  Let's go for plain "data"
> instead then.

 Understood.  Plain "data" is fine with me.

> >> But we can't really start the section like this, because the @kindex
> >> lines only insert index entries.  Nothing appears inline.  I'd suggest:
> >
> >  I can see this:
> >
> > "
> > 9.27.9 Directives to mark IEEE 754 NaN data encoding
> > ----------------------------------------------------
> >
> > These directives control the encoding of the special not-a-number (NaN)
> > IEEE 754 floating-point symbolic data.
> > "
> >
> > in output -- you may or may not like it, but I think that's a matter of 
> > personal taste.  What's wrong with that that makes you assert that "we 
> > can't really start the section like this?"
> 
> Well, "these directives" sounds like the reader should already know what
> the directives are, whereas they're only named further down.

 Hmm, the sentence sort of repeats the section title -- perhaps you're 
right after all this is a bit unfortunate.

> > +The command-line options @option{-mnan=legacy} and @option{-mnan=2008}
> > +can be used instead of @samp{.nan 2008} and @samp{.nan legacy}
> > +respectively.
> 
> You didn't notice my other typo: these two are the wrong way around.
> I was almost going to send a follow-up, but I was sure you would
> correct me...

 Well, nobody's perfect -- which is why we need these reviews in the first 
place.  Fixed now, thanks.

> OK with those changes, thanks.

 Are we settled with "the beginning" issue above?

  Maciej