Updating NEWS for 2.26

  On Wed, 5 Jul 2017, Zack Weinberg wrote:

> On Tue, Jul 4, 2017 at 10:40 AM, Carlos O'Donell <carlos@redhat.com> wrote:
> > On 07/04/2017 10:36 AM, Zack Weinberg wrote:
> >>
> >> Given the variety of changes in this release I think some more
> >> organization of NEWS would be helpful, as well.  I'm thinking
> >> subsections for changes to build requirements, new features,
> >> deprecated and/or removed features, important bugfixes.
> >
> > Sure, I'll see what kind of logical groups the changes fall into.
> >
> > If you have a change in mind, please just checkin rough text and I'll
> > wordsmith it later.
> 
> This is done now; please feel free to make further changes as you see fit.

Should we use those subject headings as standard for future releases?  So, 
change the template for the NEWS section for a new release cycle at 
<https://sourceware.org/glibc/wiki/Release> to include all those headings, 
on the basis that if a particular release doesn't have anything under one 
of the headings, we'll remove that section during the freeze.

> I am wondering whether we really need a comprehensive list of all the
> TS 18661-3 macros and functions.  It's a giant wall of text and it may
> make people think they're done reading, when the very important
> "deprecated and removed features" section is just below.

We should indicate in some way what the features are, at least, even 
without a full list.  That is, a minimum is to indicate the general naming 
patterns (cf. the GCC 7 release notes, where I didn't try to give a full 
list of every possible macro or built-in function for these types, just to 
indicate the patterns); that they apply to all non-obsolescent interfaces 
that we have for long double, whether standard or not; that the support 
does not include those TS 18661-3 interfaces that aren't float128 versions 
of interfaces for other types.  (We may not want to say specifically what 
exactly counts as obsolescent, but maybe note that there is no 
printf/scanf support for the type, with the strfromf128 / strtof128 
functions being expected to be used instead.)  I wonder if we should also 
mention the need for nondefault feature test macros to make these features 
visible, either _GNU_SOURCE or __STDC_WANT_IEC_60559_TYPES_EXT__.

Also: there's a statement "Support for more architectures will be added in 
future releases.".  I intend to enable support for _FloatN/_FloatNx 
functions in future *where they are aliases of functions for existing 
types*, but I'm still wary of making statements in NEWS about features to 
be added in future releases.  I don't think support for float128 
functions, specifically, is that likely to be added on more architectures 
where they aren't aliases for long double (the only glibc architecture 
with long double != float128, no float128 support in glibc, but float128 
support in current GCC, is hppa, where the GCC float128 support exists but 
is for HP-UX only.  (As noted in passing, I can envisage adding _Float16 
support in future, which would be completely new function implementations, 
however.)

I've applied this patch to say "GNU C Library" consistenly in NEWS items 
rather than the shorthand "glibc".
  

On Wed, Jul 5, 2017 at 9:48 AM, Joseph Myers <joseph@codesourcery.com> wrote:
>
> Should we use those subject headings as standard for future releases?  So,
> change the template for the NEWS section for a new release cycle at
> <https://sourceware.org/glibc/wiki/Release> to include all those headings,
> on the basis that if a particular release doesn't have anything under one
> of the headings, we'll remove that section during the freeze.

I would like to see that happen, yes.

>> I am wondering whether we really need a comprehensive list of all the
>> TS 18661-3 macros and functions.  It's a giant wall of text and it may
>> make people think they're done reading, when the very important
>> "deprecated and removed features" section is just below.
>
> We should indicate in some way what the features are, at least, even
> without a full list. [...]

I think that most of what you describe is too much detail for someone
reading NEWS, who wants one- or two-sentence summaries of _all_ the
new features, not a dive on any one particular feature.  It would be
better to relegate all of this verbiage about TS 18661-3 to a separate
file that would be progressively updated as support for it becomes
more complete.

(I'd suggest a top-level FLOAT128 file but that would exacerbate the
existing problem of top-level ALLCAPS files where it's unclear how old
it is and whether it's even vaguely relevant to the present release.)

> Also: there's a statement "Support for more architectures will be added in
> future releases.".  I intend to enable support for _FloatN/_FloatNx
> functions in future *where they are aliases of functions for existing
> types*, but I'm still wary of making statements in NEWS about features to
> be added in future releases.  I don't think support for float128
> functions, specifically, is that likely to be added on more architectures
> where they aren't aliases for long double

Hmm, I didn't know that.  Please go ahead and take that statement back
out, then.

> I've applied this patch to say "GNU C Library" consistenly in NEWS items
> rather than the shorthand "glibc".

I don't like this; it sounds pompous and makes several sentences
harder to read.  For instance

> -  - glibc will now detect when /etc/resolv.conf has been modified and reload
> -    the changed configuration.  The new resolver option “no-reload”
> -    (RES_NORELOAD) disables this behavior.
> +  - The GNU C Library will now detect when /etc/resolv.conf has been
> +    modified and reload the changed configuration.  The new resolver option
> +    “no-reload” (RES_NORELOAD) disables this behavior.

changing this from a simple noun to a noun phrase means that an
already-complicated sentence now has a garden-path problem as well.

zw
  

On Wed, 5 Jul 2017, Zack Weinberg wrote:

> >> I am wondering whether we really need a comprehensive list of all the
> >> TS 18661-3 macros and functions.  It's a giant wall of text and it may
> >> make people think they're done reading, when the very important
> >> "deprecated and removed features" section is just below.
> >
> > We should indicate in some way what the features are, at least, even
> > without a full list. [...]
> 
> I think that most of what you describe is too much detail for someone
> reading NEWS, who wants one- or two-sentence summaries of _all_ the
> new features, not a dive on any one particular feature.  It would be
> better to relegate all of this verbiage about TS 18661-3 to a separate
> file that would be progressively updated as support for it becomes
> more complete.

I think the appropriate length depends on the size of the feature.  
Typically we'd expect to list the new interfaces (which may sometimes be 
quite a long list, e.g. the TS 18661-1 functions in 2.25), but in this 
case a briefer description in terms of how they relate to existing 
features for other types should suffice.

> (I'd suggest a top-level FLOAT128 file but that would exacerbate the
> existing problem of top-level ALLCAPS files where it's unclear how old
> it is and whether it's even vaguely relevant to the present release.)

I think in general those files should be avoided and merged into other 
documentation etc. where possible - the manual already documents the 
individual float128 interfaces.

> > I've applied this patch to say "GNU C Library" consistenly in NEWS items
> > rather than the shorthand "glibc".
> 
> I don't like this; it sounds pompous and makes several sentences
> harder to read.  For instance

It's previously been stated that the manual (as opposed to comments) 
should not use abbreviations such as "glibc" or "GNU libc".  I'd consider 
NEWS entries as formal documentation like the manual.

https://sourceware.org/ml/libc-alpha/2012-02/msg00539.html

Entries that are not about e.g. building glibc as a whole could reasonably 
say something like "the resolver" instead.
  

On Wed, 5 Jul 2017, Joseph Myers wrote:

> I think the appropriate length depends on the size of the feature.  
> Typically we'd expect to list the new interfaces (which may sometimes be 
> quite a long list, e.g. the TS 18661-1 functions in 2.25), but in this 
> case a briefer description in terms of how they relate to existing 
> features for other types should suffice.

Specifically, the following seems like a reasonable length for this 
feature to me.

* On ia64, powerpc64le, x86-32, and x86-64, the math library now implements
  128-bit floating point as defined by ISO/IEC/IEEE 60559:2011 (IEEE
  754-2008) and ISO/IEC TS 18661-3:2015.  Contributed by Paul E. Murphy,
  Gabriel F. T. Gomes, Tulio Magno Quites Machado Filho, and Joseph Myers.

  To compile programs that use this feature, the compiler must support
  128-bit floating point with the type name _Float128 (as defined by TS
  18661-3) or __float128 (the nonstandard name used by GCC for C++, and for
  C prior to version 7).  _GNU_SOURCE or __STDC_WANT_IEC_60559_TYPES_EXT__
  must be defined to make the new interfaces visible.

  The new functions and macros correspond to those present for other
  floating-point types (except for a few obsolescent interfaces not
  supported for the new type), with F128 or f128 suffixes; for example,
  strtof128, HUGE_VAL_F128 and cosf128.  Following TS 18661-3, there are no
  printf or scanf formats for the new type; the strfromf128 and strtof128
  interfaces should be used instead.
  

On Wed, Jul 5, 2017 at 12:55 PM, Joseph Myers <joseph@codesourcery.com> wrote:
>
> * On ia64, powerpc64le, x86-32, and x86-64, the math library now implements
>   128-bit floating point as defined by ISO/IEC/IEEE 60559:2011 (IEEE
>   754-2008) and ISO/IEC TS 18661-3:2015.  Contributed by Paul E. Murphy,
>   Gabriel F. T. Gomes, Tulio Magno Quites Machado Filho, and Joseph Myers.
>
>   To compile programs that use this feature, the compiler must support
>   128-bit floating point with the type name _Float128 (as defined by TS
>   18661-3) or __float128 (the nonstandard name used by GCC for C++, and for
>   C prior to version 7).  _GNU_SOURCE or __STDC_WANT_IEC_60559_TYPES_EXT__
>   must be defined to make the new interfaces visible.
>
>   The new functions and macros correspond to those present for other
>   floating-point types (except for a few obsolescent interfaces not
>   supported for the new type), with F128 or f128 suffixes; for example,
>   strtof128, HUGE_VAL_F128 and cosf128.  Following TS 18661-3, there are no
>   printf or scanf formats for the new type; the strfromf128 and strtof128
>   interfaces should be used instead.

This also looks reasonable to me.