[PATCH 07/14] Better documentation of _GNU_SOURCE for environment

[roucaries.bastien@gmail.com]

From: Bastien Roucariès <rouca@debian.org>

Use feature_test_macros and document that historically
you should manually declare it.
---
 man7/environ.7 | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/man7/environ.7 b/man7/environ.7
index 2fee102ce..bba4f93cb 100644
--- a/man7/environ.7
+++ b/man7/environ.7
@@ -36,19 +36,36 @@
 environ \- user environment
 .SH SYNOPSIS
 .nf
+.B #include <unistd.h>
+.PP
 .BI "extern char **" environ ;
 .fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR environ:
+.nf
+        _GNU_SOURCE
+.fi
 .SH DESCRIPTION
 The variable
 .I environ
 points to an array of pointers to strings called the "environment".
 The last pointer in this array has the value NULL.
-(This variable must be declared in the user program,
-but is declared in the header file
+.PP
+Historically and by standard, this variable must be declared in the user program,
+but for programmer convenience
+.I environ
+is also declared in the header file
 .I <unistd.h>
 if the
 .B _GNU_SOURCE
-feature test macro is defined.)
+feature test macro is defined (see
+.BR feature_test_macros(7)).
+.PP
 This array of strings is made available to the process by the
 .BR exec (3)
 call that started the process.
@@ -384,6 +401,7 @@ and strictly conformant to POSIX.1-2017.
 .BR putenv (3),
 .BR setenv (3),
 .BR unsetenv (3),
+.NR feature_test_macros(7),
 .BR locale (7),
 .BR ld.so (8),
 .BR pam_env (8)
-- 
2.29.2