Re: [PATCH 3/3] manual: Add new header and standards annotations.

[Rical Jasan <ricaljasan@pacific.net>]

On 11/23/2016 09:42 AM, Joseph Myers wrote:
> On Tue, 22 Nov 2016, Rical Jasan wrote:
> 
>> 	The "???" placeholder is used for anything not obvious from a
>> 	cursory survey of the glibc sources.
> 
> All argp facilities should be documented as GNU.  Likewise mcheck.h 
> features.  Likewise getauxval.

Thank you!

> The correct standard for posix_fallocate64 is LFS (well, really the 
> combination of both LFS and POSIX.1-2001 enabled, however you denote 
> POSIX.1-2001 && LFS).

OK.

> XOPEN2K is generically an unhelpful name.  In the headers it actually 
> means POSIX.1-2001; the X/Open version is __USE_XOPEN2KXSI.  Likewise 
> __USE_XOPEN2K8 means POSIX.1-2008 and the X/Open version is 
> __USE_XOPEN2K8XSI.  So anywhere you say XOPEN2K because the headers use 
> __USE_XOPEN2K, say POSIX.1-2001 in the manual instead; likewise 
> POSIX.1-2008 for XOPEN2K8.

I'm glad you mention this.  Have you seen the related discussion on
libc-help? [1]  I'm interested in your thoughts on converting standards
to feature test macros (or vice versa).

Also, if we want long-form standards in the manual, where would we put
the feature test macros?  It seems more appropriate to document the
feature test macros in the Summary, and the current framework uses the
standard @comment verbatim there.  (There is also the issue that, e.g.,
XOPEN2K or _USE_XOPEN2K aren't the actual feature test macros one would
even use...)

> strncpy is in ISO C90, one of several standards all commonly shown as 
> "ISO" (though I think "C90", "C99", "C11", "TS 18661-1:2014" etc. might be 
> better names to use - as always, only listing the oldest standard 
> relevant, not later ones that are generally supersets of it).  In stdio.h, 
> SEEK_SET, SEEK_CUR, SEEK_END are all likewise C90.

OK, thank you.

I'll fix these up and wait for other comments.

Rical

[1] https://sourceware.org/ml/libc-help/2016-10/msg00014.html