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

[Richard Sandiford <rdsandiford at googlemail dot com>]

"Maciej W. Rozycki" <macro@codesourcery.com> writes:
>> --------------------------------------------------------------------------
>> 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.  "At the beginning"
seemed important if the source file also has a ".nan".

>> > +@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".
(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.

>> 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.

> +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...

OK with those changes, thanks.

Richard