Re: [RFC] Canonical Standards Names

[Joseph Myers <joseph at codesourcery dot com>]

On Wed, 21 Jun 2017, Rical Jasan wrote:

> In the case of multiple standards/headers, there are some existing examples:
> 
>   @deftypefun {char *} ecvt ...
>   @standards{SVID, stdlib.h}
>   @standards{Unix98, stdlib.h}
> 
> I'm not sure if that's what you're getting at, but I would contrast that

What I'm getting at is: since SVID and BSD are not standards supported by 
glibc (do not have any feature test macros distinct from _DEFAULT_SOURCE), 
should they be documented at all in @standards rather than MISC or 
DEFAULT?  Likewise for XPG[123], since _XOPEN_SOURCE was used without 
versioning for all of XPG[1234] so it's not possible to support the older 
versions in the headers.  Likewise anything else that doesn't map to 
feature test macros.

We need standard needs for everything feature test macros distinguish.  I 
think we should be more wary of adding them for many other things, 
preferring e.g. textual "this function comes from OpenBSD" to having an 
OpenBSD "standard".  Likewise if we want to express "this was a GNU 
function originally, added to POSIX in 2008", maybe text is better for 
that than @standards.  If we do add such things as BSD or SVID I think it 
should be clearly defined that e.g. for the purposes of feature test 
macros, that's a synonym of MISC/DEFAULT.

>   @deftypevr Macro int CHAR_BIT
>   @standards{C90, limits.h}
>   @standards{POSIX.1-2001, limits.h}

I think we should always elide standards that are supersets of other 
standards listed, so listing C90 implies not listing anything else (modulo 
e.g. C90 && !C11 for gets).  I think we should only mention GNU in the 
standards if either it's the only one there, or if we're saying a function 
is *excluded* from _GNU_SOURCE (or there are multiple variants of the 
same function, one is GNU and the others aren't).

> Another related issue to address is when standards conflict, or have
> some sort of interdependency.  There are at least a handful where the
> feature test macros imply something like:
> 
>   @item YESSTR
>   @standards{GNU || (XOPEN && !POSIX.1-2001), langinfo.h}

I think such && || ! descriptions are appropriate in such cases, but the 
GNU || should be avoided (on the basis, documented somewhere, that 
everything is in GNU unless explicitly excluded from it).

-- 
Joseph S. Myers
joseph@codesourcery.com