[PATCH v3 01/24] Feature test macros overhaul: sys/features.h

[Corinna Vinschen]

On Mar 17 12:09, Craig Howland wrote:
> On 03/17/2016 04:44 AM, Yaakov Selkowitz wrote:
> >On 2016-03-16 11:36, Craig Howland wrote:
> >>      This all makes things more consistent (which is sorely needed),
> >>but it seems to be lacking one major aspect:  documentation in the
> >>source.  The email points to FEATURE_TEST_MACROS(7), but the newlib
> >>developers and users are in the dark as to how to properly use this new
> >>method--the man page is not mentioned anywhere in a file, for example.
> >
> >feature_test_macros(7) only covers the public side of this, and while it
> >is a nice explanation of the various standards, it is not strictly
> >necessary in order to know how to use it.  If you want more extensive
> >documentation, then the proper public macro(s) should be mentioned in the
> >SYNOPSIS of each function, as is done in throughout the Linux man-pages.
> I agree, the usage should be in the synopsis sections.  That would cover
> what I've been calling the user aspect of documenting this. It is something
> that is presently missing; not a fault with this patch but one that has been
> brought to light by it.  (And while it's not fair to expect it, you're
> probably the one in the best position to add this information, since you had
> to have used it to generate all the new gating information.  Do you have
> summary notes on this that you could include in an email to be a starting
> point for someone else to use if you don't have time to be able to do it
> yourself?)

Shortening the discussion here somewhat since I think this is going a
bit beyond the current scope of the patches.  Documentation would be a
really nice bonus, granted, but you don't get that much in terms of
documentation in glibc either.

What you get in glibc is a single line per __USE_* macro in the head
comment of features.h in the first place.  These __USE_* macros are
glibc's equivalent to our __*_VISIBLE macros.

> One specific example is _DEFAULT_SOURCE.  It's said to deprecate _BSD_SOURCE
> and _SVID_SOURCE, but why?  And what does it really mean?  The description
> given for it is "POSIX-1.2008 with BSD and SVr4 extensions".  But if you
> look at POSIX, there is no such thing.  Where should one look to know what
> it is?  Is it a Newlib invention?

Didn't we discuss this in the previous thread about these changes?
_DEFAULT_SOURCE is the default in glibc.  I don't get your point,
though.  "POSIX-1.2008 with BSD and SVr4 extensions".  What's unclear
about that?  We have the matching _*_VISIBLE macros for that.

So here's my attempt at finding a compromise:

Yaakov, the patch is ok to apply with just a single addition.  Please add
oneliners to the main comment in features.h to explain the _*_VISIBLE
macros, along the lines of glibc with their __USE_* macros:

  These are defined by this file and are used by the
  header files to decide what to declare or define:


    __USE_ISOC11         Define ISO C11 things.
    __USE_ISOC99         Define ISO C99 things.
    [...and so on...]


Hope that's ok,
Corinna

-- 
Corinna Vinschen
Cygwin Maintainer
Red Hat
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/newlib/attachments/20160317/d1d39fa5/attachment.sig>