Re: Improve environ manpages
roucaries.bastien@gmail.com wrote:
> Could you review the language of the following improvement of
> environ manpages ?
Sure - I've merged it all into one mail here but I can splt things up
if that helps.
> Do not use for documentation purposes the unsecure mktemp function
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 6 +++++-
> 1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index 182d823d2..7d6318c1a 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -191,7 +191,10 @@ and
> .IP *
> .B TMPDIR
> influences the path prefix of names created by
> -.BR tempnam (3)
> +.BR mktemp (1),
> +.BR mkstemp (3),
> +.BR mkdtemp (3),
> +.BR tmpfile (3)
for consistency with the style used on other lists in environ(7), this
last item before the "and" should also have a comma:
.BR tmpfile (3),
[...]
>
> Some variables are portable at least under UNIX
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 10 ++++++++++
> 1 file changed, 10 insertions(+)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index 7d6318c1a..fe220cc03 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -242,6 +242,16 @@ tell applications about the window size, possibly overriding the actual size.
> may specify the desired printer to use.
> See
> .BR lpr (1).
> +.SH CONFORMING TO
> +The variables
> +.B HOME
> +.B LOGNAME,
> +.B PATH,
> +.B PWD,
insert "and" here
> +.B SHELL
> +are specified by
> +POSIX.1-1996
> +and should be reasonably portable.
> .SH NOTES
> The
> .BR prctl (2)
> --
> 2.29.2
>
[...]
>
> Clearly document that su by default does not change this variables.
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 41 +++++++++++++++++++++++++++++++++++++----
> 1 file changed, 37 insertions(+), 4 deletions(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index fe220cc03..568962bb3 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -65,15 +65,15 @@ Common examples are:
> .TP
> .B USER
> The name of the logged-in user (used by some BSD-derived programs).
> +Set a login time, see section NOTES below.
^
Here and below that should be:
Set at login time
> .TP
> .B LOGNAME
> The name of the logged-in user (used by some System-V derived programs).
> +Set a login time, see section NOTES below.
^
> .TP
> .B HOME
> -A user's login directory, set by
> -.BR login (1)
> -from the password file
> -.BR passwd (5).
> +A user's login directory, set a login time.
^
> +Set a login time, see section NOTES below.
^
Redundant backup of the typo; make it just
A user's login directory.
Set at login time, see section NOTES below.
> .TP
> .B LANG
> The name of a locale to use for locale categories when not overridden
> @@ -114,6 +114,7 @@ Set by some shells.
> .TP
> .B SHELL
> The absolute pathname of the user's login shell.
> +Set a login time, see section NOTES below.
^
> .TP
> .B TERM
> The terminal type for which output is to be prepared.
> @@ -259,6 +260,37 @@ The
> and
> .B PR_SET_MM_ENV_END
> operations can be used to control the location of the process's environment.
> +.PP
> +The
> +.B HOME,
> +.B LOGNAME,
> +.B SHELL
^
> +and
> +.B USER
> +variables are only set when an user is changing using
^ ^^^
> +session management interface, typically by program
> +.B login(1)
> +from user database (for instance, but not limited, by using
> +.B password (5)
> +database).
Some grammar problems including missing articles, some of them
significant. And there's no need to say that an example is an
example; if it was the only possibility, you wouldn't have introduced
it with "for instance".
It's not immediately obvious how "from (a/the) user database" fits
into this sentence - for a start you aren't saying that /bin/login is
from that database. Maybe it would work better in a different order.
Oh, but meanwhile, I'm not convinced that what it says is true (though
it might have been in 1993). The average user only logs in via a
display manager, and could run "sudo rm /bin/login" without it causing
any problems! So instead of "typically" this should probably be
another "for instance".
The
.B HOME,
.B LOGNAME,
.B SHELL,
and
.B USER
variables are set from a user database (such as the
.B password (5)
database) only when when a user is changed using the
session management interface, for instance by the
.B login(1)
program.
> +Particularly,
> +.B setuid (2)
> +family of function
^
> +or even
> +.I su -p
> +command, as documented in
> +.B su (1),
> +does not set theses variables. Notes that as documented,
^
> +going to root by
> +.I su
> +result in a mixed environment where
^
> +.B LOGNAME
> +and
> +.B USER
> +are retained from old user. Therefore,
> +using
> +.I su -l
> +is recommended.
The version I'd always heard was recommended was "su -" (see for
instance "https://en.wikipedia.org/wiki/Su_(Unix)"). Is there a
reason to prefer "su -l"?
Yes, "su -p" avoids (re)setting things like HOME, but I'm not sure why
you need to mention this given that it's p for --preserve-environment;
and as the manpage points out, in the case of "su -lp" the "--login"
option wins and it *does* set them all (with a warning at the password
prompt). Can we keep the su-specific stuff together, maybe as
something like this?
In particular, the
.B setuid (2)
family of functions does not set these variables.
Note that as documented in
+.B su (1),
getting a root shell with just the command
.I su
results in a mixed environment where
.B LOGNAME
and
.B USER
are retained from the old user. Using
.I su -p
preserves all the variables from the existing shell, and
.I su -
or
.I su -l
is the recommended way of getting a full root environment.
(Making this specifically a note about usage of "su" also makes it
look less as if we're saying you *shouldn't* use "sudo".)
> .SH BUGS
> Clearly there is a security risk here.
> Many a system command has been
> @@ -305,6 +337,7 @@ should consider renaming their option to
> .BR mktemp (1),
> .BR printenv (1),
> .BR sh (1),
> +.BR su (1)
^
missing serial comma.
> .BR tcsh (1),
> .BR execve (2),
> .BR clearenv (3),
> --
> 2.29.2
>
[...]
>
> Document PATH resolution, particularly null sequence and empty PATH
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 39 +++++++++++++++++++++++++++++++++++----
> 1 file changed, 35 insertions(+), 4 deletions(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index 568962bb3..16e122154 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -68,7 +68,8 @@ The name of the logged-in user (used by some BSD-derived programs).
> Set a login time, see section NOTES below.
> .TP
> .B LOGNAME
> -The name of the logged-in user (used by some System-V derived programs).
> +The name of the logged-in user (used by some System-V derived programs
> +and POSIX.1-2017).
> Set a login time, see section NOTES below.
> .TP
> .B HOME
> @@ -97,16 +98,28 @@ environment variables).
> The sequence of directory prefixes that
> .BR sh (1)
> and many other
> -programs apply in searching for a file known by an incomplete pathname.
> +programs using
> +.BR execlp (3)
> +apply in searching for a file known by an incomplete pathname.
All looking good so far.
> The prefixes are separated by \(aq\fB:\fP\(aq.
> -(Similarly one has
> +When a non-zero-length prefix is applied to this pathname, a \(aq\fB/\fP\(aq
> +(slash) shall be inserted between the prefix and the filename if the prefix
> +did not end in
> +\(aq\fB\(sl\fP\(aq (slash).
> +A zero length prefix is a legacy sequence that indicate the current directory or
> +\(aq\fB.\fP\(aq (see section BUGS below).
> +The list of prefixes shall be searched from beginning to end, applying the
> +pathname to each prefix, until an executable file with the specified name
> +and appropriate execution permissions is found.
This explanation implies you *don't* get an inserted slash when your
PATH is "". Frankly I think if we're going to make the explanation
more complicated, it needs to be rewritten from scratch as something
more like this:
PATH The list of places that shells and other programs look in to find
a command when given an incomplete pathname. Elements on this
colon-separated list may be absolute or relative directory
names or the zero-length string (interpreted as meaning the
current directory - see section BUGS below). PATH is checked
element by element, applying that directory name as a prefix to
the pathname (if it does not already end in a slash, the
expansion will insert one between the prefix and the filename),
until a file is found with the appropriate name and execution
permissions.
> +.IP
> +Similarly one has
> .B CDPATH
> used by some shells to find the target
> of a change directory command,
> .B MANPATH
> used by
> .BR man (1)
> -to find manual pages, and so on)
> +to find manual pages, and so on.
> .TP
> .B PWD
> The current working directory.
> @@ -253,6 +266,9 @@ The variables
> are specified by
> POSIX.1-1996
> and should be reasonably portable.
> +.PP
> +.B PATH
> +behavior is specified by POSIX.1-2017.
> .SH NOTES
> The
> .BR prctl (2)
> @@ -291,6 +307,12 @@ are retained from old user. Therefore,
> using
> .I su -l
> is recommended.
> +.PP
> +The default search path (used when the environment
> +does not contain the variable \fBPATH\fR)
> +shows some variation across systems. See
> +.B execlp (3)
> +for documentation of the exact behavior.
This all looks good.
> .SH BUGS
> Clearly there is a security risk here.
> Many a system command has been
> @@ -329,6 +351,14 @@ The authors of
> .I gzip
> should consider renaming their option to
> .BR GZIP_OPT .
> +.PP
> +.B PATH
> +zero lengh sequence,
> +that appears as two adjacent colons \(aq\fB::\fP\(aq, as a initial colon
> +\(aq\fB:\fP\(aq preceding the rest of the list,
> +or as a trailing colon \(aq\fB:\fP\(aq following the rest of the list,
> +shall be replaced by implicit \(aq\fB.\fP\(aq, in order to be portable
> +and strictly conformant to POSIX.1-2017.
Wait, it's not a "zero length *sequence*", it's a zero-length element
in the sequence of directory prefixes. (Which goes to show how
confusing this terminology is.)
a zero-length element in
.B PATH,
which appears as two adjacent colons \(aq\fB::\fP\(aq or as a leading
or trailing colon on the list, is replaced by implicit \(aq\fB.\fP\(aq,
in order to be portable and strictly conformant to POSIX.1-2017.
If this is going to appear under BUGS, shouldn't it say what the
problem is? Here's something we might point at:
"http://www.faqs.org/faqs/unix-faq/faq/part2/section-13.html";
> .SH SEE ALSO
> .BR bash (1),
> .BR csh (1),
> @@ -342,6 +372,7 @@ should consider renaming their option to
> .BR execve (2),
> .BR clearenv (3),
> .BR exec (3),
> +.BR execlp (3)
^
missing serial comma.
> .BR getenv (3),
> .BR putenv (3),
> .BR setenv (3),
> --
> 2.29.2
>
[...]
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 3 ++-
> 1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index 16e122154..4fa1c53aa 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -216,7 +216,8 @@ and other programs.
> .BR LD_LIBRARY_PATH ", " LD_PRELOAD ,
> and other
> .BR LD_*
> -variables influence the behavior of the dynamic loader/linker.
> +variables influence the behavior of the dynamic loader/linker. See also
> +.B ld.so (8)
> .IP *
> .B POSIXLY_CORRECT
> makes certain programs and library routines follow
> --
> 2.29.2
>
[...]
>
> More is the default pager in a lot of system mention it
> ---
> man7/environ.7 | 8 +++++++-
> 1 file changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index 4fa1c53aa..2fee102ce 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -136,7 +136,12 @@ The terminal type for which output is to be prepared.
> The user's preferred utility to display text files.
> Any string acceptable as a command_string operand to the
> .I sh\ \-c
> -command shall be valid.
> +command shall be valid. If the
> +.B PAGER
> +variable is null or not set,
> +command could fallback
> +.B more (1)
> +or any suitable paging utility default defined system-wise.
[...] If the
.B PAGER
variable is null or not set, the command could fall back on
.B more (1)
or any suitable paging utility as the system default.
(Debian also has the /bin/pager alternative. Come to think of it
having PAGER explicitly set to "" sounds more like a case for
defaulting to "cat", but never mind that.)
> .TP
> .BR EDITOR / VISUAL
> The user's preferred utility to edit text files.
> @@ -366,6 +371,7 @@ and strictly conformant to POSIX.1-2017.
> .BR env (1),
> .BR login (1),
> .BR mktemp (1),
> +.BR more (1),
> .BR printenv (1),
> .BR sh (1),
> .BR su (1)
> --
> 2.29.2
>
[...]
>
> 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
Well, I know nothing about any of that, but fortunately it all looks
like flawlessly grammatical English.
[...]
>
>
> Compare with argc/argv and describe the purpose of environment
> ---
> man7/environ.7 | 23 +++++++++++++++++++++++
> 1 file changed, 23 insertions(+)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index bba4f93cb..2fdb63d68 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -66,6 +66,29 @@ if the
> feature test macro is defined (see
> .BR feature_test_macros(7)).
> .PP
> +At time of execution, a program receive context information by two mechanisms. The first way is
> +the program arguments, represented by the arguments of
> +.I main
> +function,
> +.I argc
> +and
> +.I argv
> +variables. The second way, is the
> +.I environ
> +variable as discuted in this manual.
I think this should be:
At time of execution, a program receives context information by two mechanisms.
The first way is the program arguments, represented by the
.I argc
and
.I argv
arguments of the
.I main
function. The second is the
.I environ
variable as discussed in this manual.
> +.PP
> +The program arguments are typically used to pass so-called command-line argument specific to
^
> +a particular use of the program being invoked, thus changing the program behavior to an use case.
^ ^^^^^^
This needs some grammar fixes:
The program arguments are typically used to pass so-called
command-line arguments specific to a particular use of the program
being invoked, thus changing the program's behavior for this use case.
> +The environment, on the other hand, keeps track of information that is shared by many programs and
> +rarely changes. For example, a running process can query the value of the
> +.B TEMP
> +environment variable to discover a suitable location to store temporary files.
> +.PP
> +Standard environment variables are used for information about the user’s home directory,
^
> +current language,... An user can define additional variables for other purposes.
^^^^ ^^
> +The set of all environment variables that have values is collectively known as
> +the process environment or simply the environment.
> +.PP
With minor fixes for Unicode apostrophe, odd punctuation, etc.:
The environment, on the other hand, keeps track of information that is shared by many programs and
rarely changes. For example, a running process can query the value of the
.B TEMP
environment variable to discover a suitable location to store temporary files.
.PP
Standard environment variables are used for information about the user' home directory,
current language, etc., and a user can define additional variables for other purposes.
The set of all environment variables that have values is collectively known as
the process environment or simply the environment.
.PP
> This array of strings is made available to the process by the
> .BR exec (3)
> call that started the process.
> --
> 2.29.2
>
[...]
>
> Document the name=value system and that nul byte is forbidden
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 12 +++++++++---
> 1 file changed, 9 insertions(+), 3 deletions(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index 2fdb63d68..da540a3e1 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -89,6 +89,15 @@ current language,... An user can define additional variables for other purposes.
> The set of all environment variables that have values is collectively known as
> the process environment or simply the environment.
> .PP
> +By convention, the strings in
> +.I environ
> +have the form "\fIname\fP\fB=\fP\fIvalue\fP".
> +Names of environment variables are case-sensitive and must not contain
> +the character "\fB=\fP". The values of environment variables can be anything
> +that can be represented as a string. A value and a name must not contain an
> +embedded null byte (\(aq\e0\(aq),
> +since this is assumed to terminate the string.
All good.
(If we're describing things that are Considered Stupid rather than
technically impossible, maybe it should also warn against variables
named " " or "", though these like "=" can in fact be created.)
[...]
>
> Let use section for this man page
(I don't understand this description)
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 92 +++++++++++++++++++++++++++-----------------------
> 1 file changed, 49 insertions(+), 43 deletions(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index da540a3e1..f7bdad6f0 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -107,7 +107,55 @@ it inherits a
> .I copy
> of its parent's environment.
> .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).
(Popcon reports 291 votes for csh.)
> +.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
^ ^
This whole patch is good apart from that one sliding plural marker:
script and per-user initialization scripts 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.
> +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).
No problems.
[...]
> 2.29.2
>
[...]
>
> Introduce a Posix defined environment, other and internalization
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 69 +++++++++++++++++++++++++-------------------------
> 1 file changed, 34 insertions(+), 35 deletions(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index f7bdad6f0..c28a2dc5a 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -151,15 +151,14 @@ and
> .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.
> +by average users in their day-to-day routine. Care should be taken
> +to not conflict with the variables specified in the next sections.
A good idiomatic split infinitive.
> 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).
> -Set a login time, see section NOTES below.
> +.SH POSIX STANDARD ENVIRONMENT
> +Common examples of environment variables defined by POSIX.1-2017 are defined in the following
> +section. Conforming applications shall not set these environment variables to have
> +meanings other than as described.
> .TP
> .B LOGNAME
> The name of the logged-in user (used by some System-V derived programs
> @@ -170,24 +169,6 @@ Set a login time, see section NOTES below.
> A user's login directory, set a login time.
> Set a login time, see section NOTES below.
> .TP
> -.B LANG
> -The name of a locale to use for locale categories when not overridden
> -by
> -.B LC_ALL
> -or more specific environment variables such as
> -.BR LC_COLLATE ,
> -.BR LC_CTYPE ,
> -.BR LC_MESSAGES ,
> -.BR LC_MONETARY ,
> -.BR LC_NUMERIC ,
> -and
> -.BR LC_TIME
> -(see
> -.BR locale (7)
> -for further details of the
> -.BR LC_*
> -environment variables).
> -.TP
> .B PATH
> The sequence of directory prefixes that
> .BR sh (1)
> @@ -246,20 +227,34 @@ command shall be valid.
> .\" .B BROWSER
> .\" The user's preferred utility to browse URLs. Sequence of colon-separated
> .\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
> -.PP
> +.SH INTERNATIONALIZATION ENVIRONMENT VARIABLES
> +.TP
> +.B LANG
> +The name of a locale to use for locale categories when not overridden
> +by
> +.B LC_ALL
> +or more specific environment variables such as
> +.B LC_COLLATE ,
> +.B LC_CTYPE ,
> +.B LC_MESSAGES ,
> +.B LC_MONETARY ,
> +.B LC_NUMERIC ,
> +and
> +.BR LC_TIME.
> +See
> +.BR catopen (3),
> +.BR gettext (3),
> +.BR locale (7)
> +for further details of the
> +.B LANG
> +and
> +.B LC_*
> +environment variables.
> +.SH COMMON ENVIRONMENT VARIABLES
> 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:
> .IP * 3
> -The variables
> -.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH ,
> -.BR LC_ALL ", " LC_MESSAGES ,
> -and so on influence locale handling; see
> -.BR catopen (3),
> -.BR gettext (3),
> -and
> -.BR locale (7).
> -.IP *
> .B TMPDIR
> influences the path prefix of names created by
> .BR mktemp (1),
> @@ -292,6 +287,10 @@ gives the name of a file containing aliases
> to be used with
> .BR gethostbyname (3).
> .IP *
> +.B USER
> +The name of the logged-in user (used by some BSD-derived programs).
> +Set a login time, see section NOTES below.
^
AT login time.
> +.IP *
> .BR TZ " and " TZDIR
> give timezone information used by
> .BR tzset (3)
> --
> 2.29.2
>
[...]
>
> Introduce the user custumization section
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 75 +++++++++++++++++++++++++++-----------------------
> 1 file changed, 40 insertions(+), 35 deletions(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index c28a2dc5a..ebf738a15 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -81,7 +81,7 @@ The program arguments are typically used to pass so-called command-line argument
> a particular use of the program being invoked, thus changing the program behavior to an use case.
> The environment, on the other hand, keeps track of information that is shared by many programs and
> rarely changes. For example, a running process can query the value of the
> -.B TEMP
> +.B TMPDIR
> environment variable to discover a suitable location to store temporary files.
> .PP
> Standard environment variables are used for information about the user’s home directory,
> @@ -160,15 +160,15 @@ Common examples of environment variables defined by POSIX.1-2017 are defined in
> section. Conforming applications shall not set these environment variables to have
> meanings other than as described.
> .TP
> +.B HOME
> +A user's login directory, set a login time.
> +Set a login time, see section NOTES below.
> +.TP
> .B LOGNAME
> The name of the logged-in user (used by some System-V derived programs
> and POSIX.1-2017).
> Set a login time, see section NOTES below.
> .TP
> -.B HOME
> -A user's login directory, set a login time.
> -Set a login time, see section NOTES below.
> -.TP
> .B PATH
> The sequence of directory prefixes that
> .BR sh (1)
> @@ -207,26 +207,16 @@ Set a login time, see section NOTES below.
> .B TERM
> The terminal type for which output is to be prepared.
> .TP
> -.B PAGER
> -The user's preferred utility to display text files.
> -Any string acceptable as a command_string operand to the
> -.I sh\ \-c
> -command shall be valid. If the
> -.B PAGER
> -variable is null or not set,
> -command could fallback
> -.B more (1)
> -or any suitable paging utility default defined system-wise.
> -.TP
> -.BR EDITOR / VISUAL
> -The user's preferred utility to edit text files.
> -Any string acceptable as a command_string operand to the
> -.I sh\ \-c
> -command shall be valid.
> -.\" .TP
> -.\" .B BROWSER
> -.\" The user's preferred utility to browse URLs. Sequence of colon-separated
> -.\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
> +.B TMPDIR
> +The current temporary directory.
> +Influences the path prefix of names created by
> +.BR mktemp (1),
> +.BR mkstemp (3),
> +.BR mkdtemp (3),
> +.BR tmpfile (3)
^
missing serial comma.
> +and other routines, and the temporary directory used by
> +.BR sort (1)
> +and other programs.
> .SH INTERNATIONALIZATION ENVIRONMENT VARIABLES
> .TP
> .B LANG
> @@ -250,21 +240,36 @@ for further details of the
> and
> .B LC_*
> environment variables.
> +.SH USER CUSTOMIZATION ENVIRONMENT VARIABLES
> +The following variables are commonly used for personalizing
> +the applications used by user.
Make that "for personalizing applications used by the user".
> +.TP
> +.B PAGER
> +The user's preferred utility to display text files.
> +Any string acceptable as a command_string operand to the
> +.I sh\ \-c
> +command shall be valid. If the
> +.B PAGER
> +variable is null or not set,
> +command could fallback
> +.B more (1)
> +or any suitable paging utility default defined system-wise.
This was:
[...] If the
.B PAGER
variable is null or not set, the command could fall back on
.B more (1)
or any suitable paging utility as the system default.
> +Defined by POSIX.1-2017.
> +.TP
> +.BR EDITOR / VISUAL
> +The user's preferred utility to edit text files.
> +Any string acceptable as a command_string operand to the
> +.I sh\ \-c
> +command shall be valid. Defined by POSIX.1-2017.
> +.\" .TP
> +.\" .B BROWSER
> +.\" The user's preferred utility to browse URLs. Sequence of colon-separated
^
> +.\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
Probably "A sequence of colon-separated..."
> .SH COMMON ENVIRONMENT VARIABLES
> 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:
> .IP * 3
> -.B TMPDIR
> -influences the path prefix of names created by
> -.BR mktemp (1),
> -.BR mkstemp (3),
> -.BR mkdtemp (3),
> -.BR tmpfile (3)
> -and other routines, and the temporary directory used by
> -.BR sort (1)
> -and other programs.
> -.IP *
> .BR LD_LIBRARY_PATH ", " LD_PRELOAD ,
> and other
> .BR LD_*
[...]
>
> Document the variable LINES and COLUMN
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 45 ++++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 42 insertions(+), 3 deletions(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index ebf738a15..79f34a302 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -244,6 +244,48 @@ environment variables.
> The following variables are commonly used for personalizing
> the applications used by user.
> .TP
> +.B COLUMNS
> +This variable is a positive or zero decimal integer used to indicate the user's preferred width
^^^^^^^^^^^^^^^^
What's a "zero decimal integer"? Just say "non-negative".
> +in column positions for the terminal screen or window.
> +If this variable is unset or set to zero, the applications determines
> +the number of columns, appropriate for the terminal or window.
Wobbly grammar, but also there seems to be a missing element of "it
will have to do this for itself". You could just say:
This variable is a non-negative decimal integer used to indicate the user's preferred width
in column positions for the terminal screen or window.
If this variable is unset or set to zero, applications will
determine the appropriate value themselves.
> +When
Probably needs an inserted "the".
> +.B COLUMNS
> +environment variable
> +is set, any terminal-width information implied by the
> +.B TERM
> +environment variable is overridden.
> +.IP
> +Users and applications should not set
> +.B COLUMNS
> +unless they wish to override the system selection.
> +In this case, application may produce output unrelated to the terminal characteristics.
^s
> +Users should not need to set this variable in the environment unless
> +there is a specific reason to override the implementation's default behavior,
> +such as to display data in an area arbitrarily smaller than the terminal or window.
> +.TP
> +.B LINES
> +This variable is a positive or zero decimal integer used to indicate the user's preferred number
non-negative
> +of lines for the terminal screen or window.
> +If this variable is unset or set to zero, the applications determines
> +the number of lines, appropriate for the terminal or window.
If this variable is unset or set to zero, applications will
determine the appropriate value themselves.
> +When
^the
> +.B LINES
> +environment variable
> +is set, any terminal-width information implied by the
> +.B TERM
> +environment variable is overridden.
> +.IP
> +As for the related variable
> +.B COLUMNS,
> +users and applications should not set
> +.B LINES
> +unless they wish to override the system selection.
> +In this case, application may produce output unrelated to the terminal characteristics.
^s
> +Users should not need to set this variable in the environment unless
> +there is a specific reason to override the implementation's default behavior,
> +such as to display data in an area arbitrarily smaller than the terminal or window.
> +.TP
> .B PAGER
> The user's preferred utility to display text files.
> Any string acceptable as a command_string operand to the
[...]
Nearly there now...
>
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
> man7/environ.7 | 34 +++++++++++++++++++++-------------
> 1 file changed, 21 insertions(+), 13 deletions(-)
>
> diff --git a/man7/environ.7 b/man7/environ.7
> index 79f34a302..173c7a1d9 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -217,6 +217,22 @@ Influences the path prefix of names created by
> and other routines, and the temporary directory used by
> .BR sort (1)
> and other programs.
> +.TP
> +.B TZ
> +The
> +.B TZ
> +variable along the
^
You mean "along with"
> +.B TZDIR
> +variable
> +give timezone information used by
> +.BR tzset (3)
> +and through that by functions like
> +.BR ctime (3),
> +.BR localtime (3),
> +.BR mktime (3),
> +.BR strftime (3).
> +See also
> +.BR tzselect (8).
> .SH INTERNATIONALIZATION ENVIRONMENT VARIABLES
> .TP
> .B LANG
> @@ -247,7 +263,7 @@ the applications used by user.
> .B COLUMNS
> This variable is a positive or zero decimal integer used to indicate the user's preferred width
> in column positions for the terminal screen or window.
> -If this variable is unset or set to zero, the applications determines
> +If this variable is unset, set to zero or empty, the applications determines
^
Low-urgency missing serial comma.
> the number of columns, appropriate for the terminal or window.
> When
> .B COLUMNS
> @@ -267,7 +283,7 @@ such as to display data in an area arbitrarily smaller than the terminal or wind
> .B LINES
> This variable is a positive or zero decimal integer used to indicate the user's preferred number
> of lines for the terminal screen or window.
> -If this variable is unset or set to zero, the applications determines
> +If this variable is unset, set to zero or empty, the applications determines
^
As above.
> the number of lines, appropriate for the terminal or window.
> When
> .B LINES
> @@ -338,17 +354,6 @@ to be used with
> The name of the logged-in user (used by some BSD-derived programs).
> Set a login time, see section NOTES below.
> .IP *
> -.BR TZ " and " TZDIR
> -give timezone information used by
> -.BR tzset (3)
> -and through that by functions like
> -.BR ctime (3),
> -.BR localtime (3),
> -.BR mktime (3),
> -.BR strftime (3).
> -See also
> -.BR tzselect (8).
> -.IP *
> .B TERMCAP
> gives information on how to address a given terminal
> (or gives the name of a file containing such information).
> @@ -370,6 +375,9 @@ and should be reasonably portable.
> .PP
> .B PATH
> behavior is specified by POSIX.1-2017.
> +.PP
> +.B TZ
> +behavior is specified by POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
> .SH NOTES
> The
> .BR prctl (2)
> --
> 2.29.2
>
Okay, that's the end.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: