environ.7: Reorder the text

Move the the text describing how to set environment variable before
the list(s) of variables in order to improve readability.

[mtk: rewrote commit message]

Signed-off-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 52 insertions, 43 deletions

diff --git a/man7/environ.7 b/man7/environ.7
index 8fb80f289f..c2507b058c 100644
--- a/man7/environ.7
+++ b/man7/environ.7
@@ -61,7 +61,58 @@ The value can be anything that can be represented as a string.
 The name and the value may not contain an embedded null byte (\(aq\e0\(aq),
 since this is assumed to terminate the string.
 .PP
-Common examples are:
+Environment variables may be placed in the shell's environment by the
+.I export
+command in
+.BR sh (1),
+or by the
+.I setenv
+command if you use
+.BR csh (1).
+.PP
+The initial environment of the shell is populated in various ways,
+such as definitions from
+.IR /etc/environment
+that are processed by
+.BR pam_env (8)
+for all users at login time (on systems that employ
+.BR pam (8)).
+In addition, various shell initialization scripts, such as the system-wide
+.IR /etc/profile
+script and per-user initializations script may include commands
+that add variables to the shell's environment;
+see the manual page of your preferred shell for details.
+.PP
+Bourne-style shells support the syntax
+.PP
+    NAME=value command
+.PP
+to create an environment variable definition only in the scope
+of the process that executes
+.IR command .
+Multiple variable definitions, separated by white space, may precede
+.IR command .
+.PP
+Arguments may also be placed in the
+environment at the point of an
+.BR exec (3).
+A C program can manipulate its environment using the functions
+.BR getenv (3),
+.BR putenv (3),
+.BR setenv (3),
+and
+.BR unsetenv (3).
+.PP
+What follows is a list of environment variables typically seen on a
+system.
+This list is incomplete and includes only common variables seen
+by average users in their day-to-day routine.
+Care should be taken
+to not conflict with the variables specified in the next sections.
+Environment variables specific to a particular program or library function
+are documented in the ENVIRONMENT section of the appropriate manual page.
+.SH ENVIRONMENT
+Common examples of environment variables are:
 .TP
 .B USER
 The name of the logged-in user (used by some BSD-derived programs).
@@ -159,48 +210,6 @@ command shall be valid.
 .\" The user's preferred utility to browse URLs. Sequence of colon-separated
 .\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
 .PP
-Names may be placed in the shell's environment by the
-.I export
-command in
-.BR sh (1),
-or by the
-.I setenv
-command if you use
-.BR csh (1).
-.PP
-The initial environment of the shell is populated in various ways,
-such as definitions from
-.IR /etc/environment
-that are processed by
-.BR pam_env (8)
-for all users at login time (on systems that employ
-.BR pam (8)).
-In addition, various shell initialization scripts, such as the system-wide
-.IR /etc/profile
-script and per-user initializations script may include commands
-that add variables to the shell's environment;
-see the manual page of your preferred shell for details.
-.PP
-Bourne-style shells support the syntax
-.PP
-    NAME=value command
-.PP
-to create an environment variable definition only in the scope
-of the process that executes
-.IR command .
-Multiple variable definitions, separated by white space, may precede
-.IR command .
-.PP
-Arguments may also be placed in the
-environment at the point of an
-.BR exec (3).
-A C program can manipulate its environment using the functions
-.BR getenv (3),
-.BR putenv (3),
-.BR setenv (3),
-and
-.BR unsetenv (3).
-.PP
 Note that the behavior of many programs and library routines is
 influenced by the presence or value of certain environment variables.
 Examples include the following: