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

[Joseph Myers <joseph@codesourcery.com>]

On Thu, 24 Nov 2016, Rical Jasan wrote:

> > 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).

I'm not on libc-help.  libc-help is for user questions.  It's not an 
appropriate place for development discussions and is not relevant to 
establishing consensus on development directions.

> 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...)

My assumption is that creature.texi (which is very out of date regarding 
what's enabled by default, values of _POSIX_C_SOURCE, etc.) would, where 
it describes support for a standard and any associated feature test 
macros, say something like: "Functions enabled with this feature test 
macro / from this standard are listed as POSIX.1-2008 in <summary>.".  
Where <summary> could be a link to the existing summary.  Or it could say 
"in the Standards information in the individual function description", if 
we use macros to generate explicit Standards information in each function 
description alongside the Safety information.  Or both.

That is, creature.texi would explain the notation just like intro.texi has 
an explanation of the safety annotations.  The summary currently says "the 
standard or other source from which each facility is derived", not "the 
feature test macro".

There's an open question of whether we wish to continue to document BSD / 
SVID / ... sources not corresponding to feature test macros, or just make 
the annotations say MISC or DEFAULT and leave information about BSD etc. 
origins to free-text descriptions.

As for names corresponding to standards / feature test macros, I suggest 
one possibility:

C90 (everything is a superset of this apart from gets obsoletion)
C95
C99
C11
  (note that these four are normally selected with -std, not with feature 
   test macros, though glibc has _ISOC99_SOURCE and _ISOC11_SOURCE)
TR 27431-2:2010
TS 18661-1:2014
TS 18661-4:2015
POSIX.1 (= 1990 edition)
POSIX.2
POSIX.1-1993
POSIX.1-1995
POSIX.1-2001
XSI POSIX.1-2001
POSIX.1-2008
XSI POSIX.1-2008
DEFAULT
GNU
XOPEN (= __USE_XOPEN; listed as XPG3 in conform/ tests; corresponds to 
       functions in C435 that are not UX-shaded)
XPG4 (= __USE_XOPEN_EXTENDED; corresponds to everything in C435)
UNIX98
LFS (= __USE_LARGEFILE64, i.e. *64 functions)

(which doesn't cover _LARGEFILE_SOURCE / _ATFILE_SOURCE / _REENTRANT, but 
should be enough anyway to provide a sufficient indication of where 
functions come from, at least if you can handle "standard 1 || standard 
2", "standard 1 && ! standard 2", or similar).

-- 
Joseph S. Myers
joseph@codesourcery.com