This is the mail archive of the newlib@sourceware.org mailing list for the newlib project.
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
Other format: | [Raw text] |
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
Attachment:
signature.asc
Description: PGP signature
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |