[v2] manual: Document missing feature test macros.

  Several feature test macros are documented in features.h but absent in
the manual, and some documented macros accept undocumented values.
This commit updates the manual to mention all the accepted macros,
along with any values that hold special meaning.

	* manual/creature.texi (_POSIX_C_SOURCE): Document special
	values of 199606L, 200112L, and 200809L.
	(_XOPEN_SOURCE): Document special values of 600 and 700.
	(_ISOC11_SOURCE): Document macro.
	(_ATFILE_SOURCE): Likewise.
	(_FORTIFY_SOURCE): Likewise.

---
Changes in v2:
	* Refer to base editions of POSIX standards, and mention
	supported subsequent bug-fix editions explicitly.
	* Set @standards for _ATFILE_SOURCE and _FORTIFY_SOURCE to
	GNU.
	* Minor wording changes
	* Rebase to master (post-88f9e739).

---
 manual/creature.texi | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)
  

Ping

On 07/27/2017 08:43 PM, Rical Jasan wrote:
> Several feature test macros are documented in features.h but absent in
> the manual, and some documented macros accept undocumented values.
> This commit updates the manual to mention all the accepted macros,
> along with any values that hold special meaning.
> 
> 	* manual/creature.texi (_POSIX_C_SOURCE): Document special
> 	values of 199606L, 200112L, and 200809L.
> 	(_XOPEN_SOURCE): Document special values of 600 and 700.
> 	(_ISOC11_SOURCE): Document macro.
> 	(_ATFILE_SOURCE): Likewise.
> 	(_FORTIFY_SOURCE): Likewise.
> 
> ---
> Changes in v2:
> 	* Refer to base editions of POSIX standards, and mention
> 	supported subsequent bug-fix editions explicitly.
> 	* Set @standards for _ATFILE_SOURCE and _FORTIFY_SOURCE to
> 	GNU.
> 	* Minor wording changes
> 	* Rebase to master (post-88f9e739).
> 
> ---
>  manual/creature.texi | 36 +++++++++++++++++++++++++++++++++++-
>  1 file changed, 35 insertions(+), 1 deletion(-)
  

OK, but suggested followups:

* In the description of _DEFAULT_SOURCE, note that features from the C 
standard version used by the compiler are also enabled by default.  (With 
GCC 5 and later, which defaults to -std=gnu11, that means C11 features are 
enabled, but unlike C99 they aren't part of the 2008 edition of POSIX, so 
aren't already included in the description of default features.)

* Remove the statement about C99 not being widely adopted from the 
description of _ISOC99_SOURCE.  By now, C99 is widely adopted (in the Unix 
world; I'm not sure about the state of Microsoft's compiler in that 
regard, they've historically been better at keeping up with C++ than with 
C).

* Consider obsoleting _ATFILE_SOURCE and making it into an alias for 
_POSIX_C_SOURCE = 200809L if _POSIX_C_SOURCE is undefined or has a lower 
value (similar to the _REENTRANT obsoletion); I don't think we really need 
a separate feature test macro for this subset of POSIX features.
  

On 08/10/2017 03:26 PM, Joseph Myers wrote:
> OK, but suggested followups:
> 
> * In the description of _DEFAULT_SOURCE, note that features from the C 
> standard version used by the compiler are also enabled by default.  (With 
> GCC 5 and later, which defaults to -std=gnu11, that means C11 features are 
> enabled, but unlike C99 they aren't part of the 2008 edition of POSIX, so 
> aren't already included in the description of default features.)

How would you like that said?  That whole paragraph refers to /either/
feature test macros /or/ compiler options, and uses examples of the
latter, so I already read it as implying if you use a specific compiler
option such as -std=gnu11, you get what it entails, along with anything
that is "default":

"defining it together with other feature test macros, or when options
such as @option{-ansi} are used, enables those features even when the
other options would otherwise cause them to be disabled."

Documenting the compiler's defaults is probably out of scope.

> * Remove the statement about C99 not being widely adopted from the 
> description of _ISOC99_SOURCE.  By now, C99 is widely adopted (in the Unix 
> world; I'm not sure about the state of Microsoft's compiler in that 
> regard, they've historically been better at keeping up with C++ than with 
> C).

How is this:

"@Theglibc{} has a complete implementation of the @w{ISO C99} standard,
and to enable its features, the macro @code{_ISOC99_SOURCE} should be
defined."

> * Consider obsoleting _ATFILE_SOURCE and making it into an alias for 
> _POSIX_C_SOURCE = 200809L if _POSIX_C_SOURCE is undefined or has a lower 
> value (similar to the _REENTRANT obsoletion); I don't think we really need 
> a separate feature test macro for this subset of POSIX features.

As this requires more extensive changes throughout, I'll do this
separately, but I think the other issues can be incorporated in a v3.

Rical
  

On Fri, 11 Aug 2017, Rical Jasan wrote:

> On 08/10/2017 03:26 PM, Joseph Myers wrote:
> > OK, but suggested followups:
> > 
> > * In the description of _DEFAULT_SOURCE, note that features from the C 
> > standard version used by the compiler are also enabled by default.  (With 
> > GCC 5 and later, which defaults to -std=gnu11, that means C11 features are 
> > enabled, but unlike C99 they aren't part of the 2008 edition of POSIX, so 
> > aren't already included in the description of default features.)
> 
> How would you like that said?  That whole paragraph refers to /either/
> feature test macros /or/ compiler options, and uses examples of the
> latter, so I already read it as implying if you use a specific compiler
> option such as -std=gnu11, you get what it entails, along with anything
> that is "default":

I read the existing text as saying that certain strict conformance options 
*disable* features that would otherwise be enabled by default; nothing 
about compiler options serving to *enable* visibility of features not 
otherwise listed as present by default.

Maybe more of a rework is needed in this area.  It's also the case that 
this section of the manual is preferentially referring to the old -ansi 
option, when I'd think -std=c11 would be a better example of a standards 
conformance option in most places (de-emphasising the use of options for 
old standards).  Information to include (some is already present) 
includes:

* Features from the compiler's language version are enabled, regardless of 
any feature test macros passed.

* If you use a strict conformance option, this disables features beyond 
those from the compiler's language version, and feature test macros need 
to be used to enable them.

* If you don't use a strict conformance option, but you use any C/POSIX 
feature test macros, this overrides the default enabling of POSIX.1-2008 
features.  (The logic for this in features.h actually checks for 
_ISOC99_SOURCE but not _ISOC11_SOURCE.  That inconsistency should be 
fixed, presumably by adding _ISOC99_SOURCE to the conditionals.)

* _ISOC99_SOURCE and _ISOC11_SOURCE are not generally needed; they are 
only relevant if you specifically want to add those newer library features 
on top of an older language version (e.g. -std=c90 -D_ISOC99_SOURCE).

> "@Theglibc{} has a complete implementation of the @w{ISO C99} standard,
> and to enable its features, the macro @code{_ISOC99_SOURCE} should be
> defined."

I think we only need to comment on the state of the glibc implementation 
when it's significantly incomplete (as for various __STDC_WANT_*).  It's 
more relevant to point out here that there is no need for this macro if 
your compiler (+ options) uses C99 or later.