Bug#981171: [PATCH 4/6] Better documentation of the environment mechanism

2021-01-30 Thread Michael Kerrisk (man-pages)
Hello Bastien,

Thanks. This looks better. But still some things to 
improve, I think.

On 1/30/21 12:29 AM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Document the purpose of the envirment mechanism, compared to the

s/envirment/environment/

> command line argument of a program. Document particularly that
> the environment is shared by many programs and is inherited.
> 
> Define also the so called process environment and "the environment"

s/so called/so-called/

> concept that are used in other manpages.

s/manpages/manual pages/

> 
> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 26 ++
>  1 file changed, 26 insertions(+)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 3c2769bfb..d1e86ee8d 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -43,6 +43,32 @@ 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.
> +.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.

Oui en français c'est discuter; mais en anglais: to discuss

> +.PP
> +The program arguments are typically used to pass so-called command-line 
> argument specific to

Source lines should be no more than 75 columns or so.

s/so-called command-line argument/values that are/

> +a particular use of the program being invoked, thus changing the program 
> behavior to an use case.

s/, thus changing the program behavior to an use case//
(This test does not really add to the explanation.)

> +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 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,
> +current language,...

s/.../ and so on./

> +An user can define additional variables for other purposes.

s/An/A/
(Because the "u" is iotized -- "a 'yooser'") [1]

> +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 execve (2)
>  call when a new program is started.

Thanks,

Michael



[1] https://www.quickanddirtytips.com/education/grammar/a-versus-an

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/



Bug#981171: [PATCH 4/6] Better documentation of the environment mechanism

2021-01-29 Thread roucaries . bastien
From: Bastien Roucariès 

Document the purpose of the envirment mechanism, compared to the
command line argument of a program. Document particularly that
the environment is shared by many programs and is inherited.

Define also the so called process environment and "the environment"
concept that are used in other manpages.

Signed-off-by: Bastien Roucariès 
---
 man7/environ.7 | 26 ++
 1 file changed, 26 insertions(+)

diff --git a/man7/environ.7 b/man7/environ.7
index 3c2769bfb..d1e86ee8d 100644
--- a/man7/environ.7
+++ b/man7/environ.7
@@ -43,6 +43,32 @@ 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.
+.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.
+.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.
+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 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,
+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
 This array of strings is made available to the process by the
 .BR execve (2)
 call when a new program is started.
-- 
2.29.2