This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: Updating NEWS for 2.26
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.
--
Joseph S. Myers
joseph@codesourcery.com