From 0cef3983bf873b322ba816211073fefebb297abc Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Sun, 31 Jan 2021 10:54:53 +0100
Subject: [PATCH] doc: show environment variables in a consistent style

In manual pages, set environment variables in bold;
in the texinfo manual, use the @env{} macro consistently.
Additionally, talk about PATH instead of $PATH in all manuals.

* doc/find.texi: Do the above.
* find/find.1: Likewise.
* NEWS (Documentation Changes): Mention the fix.

Reported by Helge Kreutzmann in
https://savannah.gnu.org/bugs/?59963
---
 NEWS          |   4 ++
 doc/find.texi |  62 ++++++++++++++--------------
 find/find.1   | 112 ++++++++++++++++++++++++++++++++------------------
 3 files changed, 106 insertions(+), 72 deletions(-)

diff --git a/NEWS b/NEWS
index 20dc7a6c..1ee7f329 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,10 @@ GNU findutils NEWS - User visible changes.      -*- outline -*- (allout)
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
+** Documentation Changes
+
+  The find.1 man page and the Texinfo manual now show environment variables
+  in a consistent style. [#59963]
 
 * Noteworthy changes in release 4.8.0 (2020-01-09) [stable]
 
diff --git a/doc/find.texi b/doc/find.texi
index fbf59188..15bfdbc8 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -581,7 +581,7 @@ was generated, the default was @file{@value{LOCATE_DB}}.
 Instead of searching the default file name database, search the file
 name databases in @var{path}, which is a colon-separated list of
 database file names.  You can also use the environment variable
-@code{LOCATE_PATH} to set the list of database files to search.  The
+@env{LOCATE_PATH} to set the list of database files to search.  The
 option overrides the environment variable if both are used.
 @end table
 
@@ -1051,7 +1051,7 @@ Gibibytes (GiB, units of 1024 * 1024 * 1024 = 1073741824 bytes)
 @end table
 
 The `b' suffix always considers blocks to be 512 bytes.  This is not
-affected by the setting (or non-setting) of the @code{POSIXLY_CORRECT}
+affected by the setting (or non-setting) of the @env{POSIXLY_CORRECT}
 environment variable.  This behaviour is different from the behaviour of
 the @samp{-ls} action).  If you want to use 1024-byte units, use the
 `k' suffix instead.
@@ -1705,7 +1705,7 @@ files based on their inode number.
 
 @item
 the number of blocks in the file.  The block counts are of 1K blocks,
-unless the environment variable @code{POSIXLY_CORRECT} is set, in
+unless the environment variable @env{POSIXLY_CORRECT} is set, in
 which case 512-byte blocks are used.  @xref{Size}, for how to find
 files based on their size.
 
@@ -2173,7 +2173,7 @@ locale's date representation (mm/dd/yy)
 Date and time, separated by '+', for example
 `2004-04-28+22:22:05.0000000000'.
 The time is given in the current timezone (which may be affected by
-setting the TZ environment variable).  This is a GNU extension.  The
+setting the @env{TZ} environment variable).  This is a GNU extension.  The
 seconds field includes a fractional part.
 @end table
 
@@ -2234,11 +2234,11 @@ find . -name '*.h' -execdir diff -u '@{@}' /tmp/master ';'
 @end example
 @end deffn
 
-If you use @samp{-execdir}, you must ensure that the @samp{$PATH}
+If you use @samp{-execdir}, you must ensure that the @env{PATH}
 variable contains only absolute directory names.  Having an empty
-element in @samp{$PATH} or explicitly including @samp{.} (or any other
+element in @env{PATH} or explicitly including @samp{.} (or any other
 non-absolute name) is insecure.  GNU find will refuse to run if you
-use @samp{-execdir} and it thinks your @samp{$PATH} setting is
+use @samp{-execdir} and it thinks your @env{PATH} setting is
 insecure.  For example:
 
 @table @samp
@@ -2543,7 +2543,7 @@ which cannot be used to send arbitrary data to the terminal, and so
 these are printed as-is.
 @item %f, %h, %l, %p, %P
 The output of these directives is quoted if the output is going to a
-terminal.  The setting of the @code{LC_CTYPE} environment
+terminal.  The setting of the @env{LC_CTYPE} environment
 variable is used to determine which characters need to be quoted.
 
 This quoting is performed in the same way as for GNU @code{ls}.  This
@@ -2825,14 +2825,14 @@ Otherwise, run it, with  standard input redirected from
 The response to the prompt is matched against a pair of regular
 expressions to determine if it is a yes or no response.  These regular
 expressions are obtained from the system (@code{nl_langinfo} items
-YESEXPR and NOEXPR are used) if the @code{POSIXLY_CORRECT} environment
+YESEXPR and NOEXPR are used) if the @env{POSIXLY_CORRECT} environment
 variable is set and the system has such patterns available.  Otherwise,
 @code{find}'s message translations are used.  In either case, the
-@code{LC_MESSAGES} environment variable will determine the regular
+@env{LC_MESSAGES} environment variable will determine the regular
 expressions used to determine if the answer is affirmative or negative.
 The interpretation of the regular expressions themselves will be
-affected by the environment variables @code{LC_CTYPE} (character
-classes) and @code{LC_COLLATE} (character ranges and equivalence
+affected by the environment variables @env{LC_CTYPE} (character
+classes) and @env{LC_COLLATE} (character ranges and equivalence
 classes).
 @end deffn
 
@@ -2975,7 +2975,7 @@ You can obtain some statistics about the databases by using
 @section Database Locations
 
 There can be multiple file name databases.  Users can select which
-databases @code{locate} searches using the @code{LOCATE_PATH}
+databases @code{locate} searches using the @env{LOCATE_PATH}
 environment variable or a command line option.  The system
 administrator can choose the file name of the default database, the
 frequency with which the databases are updated, and the directories
@@ -2998,7 +2998,7 @@ the default location @file{@value{LOCATE_DB}}.
 
 If no database exists at @file{@value{LOCATE_DB}} but the user did not
 specify where to look (by using @samp{-d} or setting
-@code{LOCATE_PATH}), then @code{locate} will also check for a
+@env{LOCATE_PATH}), then @code{locate} will also check for a
 ``secure'' database in @file{/var/lib/slocate/slocate.db}.
 
 @node Database Formats
@@ -3345,7 +3345,7 @@ circumstances, @code{find} may issue a warning message.
 
 By default, warnings are enabled only if @code{find} is being run
 interactively (specifically, if the standard input is a terminal) and
-the @code{POSIXLY_CORRECT} environment variable is not set.  Warning
+the @env{POSIXLY_CORRECT} environment variable is not set.  Warning
 messages can be controlled explicitly by the use of options on the
 command line:
 
@@ -3512,7 +3512,7 @@ Instead of searching the default @code{locate} database
 @file{@value{LOCATE_DB}}, @code{locate} searches the file
 name databases in @var{path}, which is a colon-separated list of
 database file names.  You can also use the environment variable
-@code{LOCATE_PATH} to set the list of database files to search.  The
+@env{LOCATE_PATH} to set the list of database files to search.  The
 option overrides the environment variable if both are used.  Empty
 elements in @var{path} (that is, a leading or trailing colon, or two
 colons in a row) are taken to stand for the default database.
@@ -3655,7 +3655,7 @@ environment and then executes @code{updatedb} in the environment.
 @table @code
 @item --findoptions='@var{OPTION}@dots{}'
 Global options to pass on to @code{find}.
-The environment variable @code{FINDOPTIONS} also sets this value.
+The environment variable @env{FINDOPTIONS} also sets this value.
 Default is none.
 
 @item --localpaths='@var{path}@dots{}'
@@ -3664,12 +3664,12 @@ Default is @file{/}.
 
 @item --netpaths='@var{path}@dots{}'
 Network (NFS, AFS, RFS, etc.) directories to put in the database.
-The environment variable @code{NETPATHS} also sets this value.
+The environment variable @env{NETPATHS} also sets this value.
 Default is none.
 
 @item --prunepaths='@var{path}@dots{}'
 Directories to omit from the database, which would otherwise be
-included.  The environment variable @code{PRUNEPATHS} also sets this
+included.  The environment variable @env{PRUNEPATHS} also sets this
 value.  Default is @file{/tmp /usr/tmp /var/tmp /afs}.  The paths are
 used as regular expressions (with @code{find ... -regex}, so you need
 to specify these paths in the same way that @code{find} will encounter
@@ -3680,7 +3680,7 @@ slashes.
 Filesystems to omit from the database, which would otherwise be
 included.  Note that files are pruned when a filesystem is reached;
 Any filesystem mounted under an undesired filesystem will be ignored.
-The environment variable @code{PRUNEFS} also sets this value.  Default
+The environment variable @env{PRUNEFS} also sets this value.  Default
 is @file{nfs NFS proc}.
 
 @item --output=@var{dbfile}
@@ -3690,12 +3690,12 @@ when this document was formatted it was @file{@value{LOCATE_DB}}.
 @item --localuser=@var{user}
 The user to search the non-network directories as, using @code{su}.
 Default is to search the non-network directories as the current user.
-You can also use the environment variable @code{LOCALUSER} to set this user.
+You can also use the environment variable @env{LOCALUSER} to set this user.
 
 @item --netuser=@var{user}
 The user to search network directories as, using @code{su}.  Default
 @code{user} is @code{daemon}.  You can also use the environment variable
-@code{NETUSER} to set this user.
+@env{NETUSER} to set this user.
 
 @item --dbformat=@var{FORMAT}
 Generate the locate database in format @code{FORMAT}.  Supported
@@ -3886,7 +3886,7 @@ possible simultaneously.   @xref{Controlling Parallelism}, for
 information on dynamically controlling parallelism.
 
 @item --process-slot-var=@var{environment-variable-name}
-Set the environment variable @var{environment-variable-name} to a
+Set the environment variable @env{environment-variable-name} to a
 unique value in each running child process.  Each value is a decimal
 integer.  Values are reused once child processes exit.  This can be
 used in a rudimentary load distribution scheme, for example.
@@ -4059,10 +4059,10 @@ matching to be used for the `\-name' option.  GNU find uses the
 GNU version of the @code{fnmatch} library function.
 
 This variable also affects the interpretation of the response to
-@code{-ok}; while the @code{LC_MESSAGES} variable selects the actual
+@code{-ok}; while the @env{LC_MESSAGES} variable selects the actual
 pattern used to interpret the response to @code{-ok}, the interpretation
 of any bracket expressions in the pattern will be affected by the
-@code{LC_COLLATE} variable.
+@env{LC_COLLATE} variable.
 
 @item LC_CTYPE
 This variable affects the treatment of character classes used in
@@ -4071,7 +4071,7 @@ the @samp{-name} test, if the @code{fnmatch} function supports this.
 
 This variable also affects the interpretation of any character classes
 in the regular expressions used to interpret the response to the
-prompt issued by @code{-ok}.  The @code{LC_CTYPE} environment variable will
+prompt issued by @code{-ok}.  The @env{LC_CTYPE} environment variable will
 also affect which characters are considered to be unprintable when
 filenames are printed (@pxref{Unusual Characters in File Names}).
 
@@ -4086,7 +4086,7 @@ Determines the location of the internationalisation message catalogues.
 @item PATH
 Affects the directories which are searched to find the executables
 invoked by @samp{-exec}, @samp{-execdir} @samp{-ok} and @samp{-okdir}.
-If the @var{PATH} environment variable includes the current directory
+If the @env{PATH} environment variable includes the current directory
 (by explicitly including @samp{.} or by having an empty element), and
 the find command line includes @samp{-execdir} or @samp{-okdir},
 @code{find} will refuse to run.  @xref{Security Considerations}, for a
@@ -4094,7 +4094,7 @@ more detailed discussion of security matters.
 
 @item POSIXLY_CORRECT
 Determines the block size used by @samp{-ls} and @samp{-fls}.  If
-@code{POSIXLY_CORRECT} is set, blocks are units of 512 bytes.  Otherwise
+@env{POSIXLY_CORRECT} is set, blocks are units of 512 bytes.  Otherwise
 they are units of 1024 bytes.
 
 Setting this variable also turns off warning messages (that is, implies
@@ -4102,7 +4102,7 @@ Setting this variable also turns off warning messages (that is, implies
 the output for @samp{-ok}, all messages printed on stderr are
 diagnostics and must result in a non-zero exit status.
 
-When @code{POSIXLY_CORRECT} is set, the response to the prompt made by the
+When @env{POSIXLY_CORRECT} is set, the response to the prompt made by the
 @code{-ok} action is interpreted according to the system's message
 catalogue, as opposed to according to @code{find}'s own message
 translations.
@@ -5390,7 +5390,7 @@ be processed is passed to the invoked command, with a @samp{./}
 prepended (giving @file{./passwd} in our example).
 
 The @samp{-execdir} action refuses to do anything if the current
-directory is included in the @var{$PATH} environment variable.  This
+directory is included in the @env{PATH} environment variable.  This
 is necessary because @samp{-execdir} runs programs in the same
 directory in which it finds files -- in general, such a directory
 might be writable by untrusted users.  For similar reasons,
@@ -5721,7 +5721,7 @@ to run.
 This should not happen.  Re-run @code{updatedb}.  If that works, but
 @code{locate} still produces this error, run @code{locate --version}
 and @code{updatedb --version}.  These should produce the same output.
-If not, you are using a mixed toolset; check your @samp{$PATH}
+If not, you are using a mixed toolset; check your @env{PATH}
 environment variable and your shell aliases (if you have any).  If
 both programs claim to be GNU versions, this is a bug; all versions of
 these programs should interoperate without problem.  Ask for help on
diff --git a/find/find.1 b/find/find.1
index 0b6129df..96fb1fc7 100644
--- a/find/find.1
+++ b/find/find.1
@@ -476,11 +476,11 @@ if standard input is a tty, and to
 otherwise.  If a warning message relating to command-line usage is
 produced, the exit status of
 .B find
-is not affected.  If the POSIXLY_CORRECT environment variable is set,
-and
+is not affected.  If the
+.B POSIXLY_CORRECT
+environment variable is set, and
 .B \-warn
-is also used, it is not specified which, if any,
-warnings will be active.
+is also used, it is not specified which, if any, warnings will be active.
 
 .SS GLOBAL OPTIONS
 Global options always return true.
@@ -794,7 +794,9 @@ will never include a slash, so `\-name a/b' will never match anything
 .B \-path
 instead).
 A warning is issued if you try to do this,
-unless the environment variable POSIXLY_CORRECT is set.
+unless the environment variable
+.B POSIXLY_CORRECT
+is set.
 The metacharacters (`*', `?',
 and `[]') match a `.\&' at the start of the base name (this is a change
 in findutils-4.2.2; see section STANDARDS CONFORMANCE below).  To ignore a
@@ -1228,13 +1230,13 @@ invocation of
 .I command
 will only list files that exist in the same subdirectory.  If you use
 this option, you must ensure that your
-.B $PATH
+.B PATH
 environment variable does not reference `.';
 otherwise, an attacker can run any commands they like by leaving an
 appropriately-named file in a directory in which you will run
 .BR \-execdir .
 The same applies to having entries in
-.B $PATH
+.B PATH
 which are empty or which are not absolute directory names.  If
 any invocation with the `+' form returns a non-zero value as exit status,
 then
@@ -1309,7 +1311,8 @@ True; list current file in
 .B ls \-dils
 format on standard output.
 The block counts are of 1\ KB blocks, unless the environment variable
-POSIXLY_CORRECT is set, in which case 512-byte blocks are used.
+.B POSIXLY_CORRECT
+is set, in which case 512-byte blocks are used.
 See the
 .B UNUSUAL FILENAMES
 section for information about how unusual characters in filenames are handled.
@@ -1326,16 +1329,19 @@ from
 The response to the prompt is matched against a pair of regular
 expressions to determine if it is an affirmative or negative
 response.  This regular expression is obtained from the system if the
-`POSIXLY_CORRECT' environment variable is set, or otherwise from
+.B POSIXLY_CORRECT
+environment variable is set, or otherwise from
 .BR find 's
 message translations.  If the system has no suitable
 definition,
 .BR find 's
 own definition will be used.
 In either case, the interpretation of the regular expression itself
-will be affected by the environment variables 'LC_CTYPE'
-(character classes) and 'LC_COLLATE' (character ranges and equivalence
-classes).
+will be affected by the environment variables
+.B LC_CTYPE
+(character classes) and
+.B LC_COLLATE
+(character ranges and equivalence classes).
 
 
 
@@ -1460,7 +1466,8 @@ time, 24-hour (hh:mm:ss.xxxxxxxxxx)
 .IP +
 Date and time, separated by `+', for example
 `2004\-04\-28+22:22:05.0'.  This is a GNU extension.  The time is
-given in the current timezone (which may be affected by setting the TZ
+given in the current timezone (which may be affected by setting the
+.B TZ
 environment variable).  The seconds field includes a fractional part.
 .IP X
 locale's time representation (H:M:S).  The seconds field includes a
@@ -1820,8 +1827,9 @@ If you are able to decide what format to use for the output of
 .B find
 then it is normally better to use `\e0' as a terminator
 than to use newline, as file names can contain white space and newline
-characters.  The setting of the `LC_CTYPE' environment
-variable is used to determine which characters need to be quoted.
+characters.  The setting of the
+.B LC_CTYPE
+environment variable is used to determine which characters need to be quoted.
 
 .IP "\-print, \-fprint"
 Quoting is handled in the same way as for
@@ -1844,8 +1852,10 @@ actions print the current filename as-is.  This may change in a future release.
 .
 .SH "STANDARDS CONFORMANCE"
 For closest compliance to the POSIX standard, you should set the
-POSIXLY_CORRECT environment variable.  The following options are
-specified in the POSIX standard (IEEE Std 1003.1-2008, 2016 Edition):
+.B POSIXLY_CORRECT
+environment variable.
+The following options are specified in the POSIX standard
+(IEEE Std 1003.1-2008, 2016 Edition):
 
 .IP \fB\-H\fR
 This option is supported.
@@ -1872,14 +1882,19 @@ comma-separated list.
 .IP \fB\-ok\fR
 Supported.
 Interpretation of the response is according to the `yes' and `no'
-patterns selected by setting the `LC_MESSAGES' environment variable.
-When the `POSIXLY_CORRECT' environment variable is set, these patterns
-are taken system's definition of a positive (yes) or negative (no)
-response.  See the system's
-documentation for
+patterns selected by setting the
+.B LC_MESSAGES
+environment variable.
+When the
+.B POSIXLY_CORRECT
+environment variable is set, these patterns are taken system's definition
+of a positive (yes) or negative (no) response.
+See the system's documentation for
 .BR nl_langinfo (3),
 in particular YESEXPR and NOEXPR.
-When `POSIXLY_CORRECT' is not set, the patterns are instead taken from
+When
+.B POSIXLY_CORRECT
+is not set, the patterns are instead taken from
 .BR find 's
 own message catalogue.
 
@@ -1890,7 +1905,9 @@ take the relevant time from the symbolic link; see the HISTORY section
 below.
 
 .IP \fB\-perm\fR
-Supported.  If the POSIXLY_CORRECT environment variable is not set,
+Supported.  If the
+.B POSIXLY_CORRECT
+environment variable is not set,
 some mode arguments (for example +a+x) which are not valid in POSIX
 are supported for backward-compatibility.
 
@@ -1975,8 +1992,9 @@ but you should use the POSIX-compliant option
 .B \-depth
 instead.
 .P
-The POSIXLY_CORRECT environment variable does not affect the behaviour
-of the
+The
+.B POSIXLY_CORRECT
+environment variable does not affect the behaviour of the
 .B \-regex
 or
 .B \-iregex
@@ -1999,15 +2017,18 @@ matching to be used for the
 option.
 GNU find uses the
 .BR fnmatch (3)
-library function, and so support for `LC_COLLATE' depends on the
-system library.
+library function, and so support for
+.B LC_COLLATE
+depends on the system library.
 This variable also affects the interpretation of the response to
 .BR \-ok ;
-while the `LC_MESSAGES' variable selects the actual pattern used to
-interpret the response to
+while the
+.B LC_MESSAGES
+variable selects the actual pattern used to interpret the response to
 .BR \-ok ,
 the interpretation of any bracket expressions in the pattern will be
-affected by `LC_COLLATE'.
+affected by
+.BR LC_COLLATE .
 
 .IP LC_CTYPE
 This variable affects the treatment of character classes used in
@@ -2020,14 +2041,17 @@ library function supports this.  This variable also affects the
 interpretation of any character classes in the regular expressions
 used to interpret the response to the prompt issued by
 .BR \-ok .
-The `LC_CTYPE' environment variable will
-also affect which characters are considered to be unprintable when
-filenames are printed; see the section UNUSUAL FILENAMES.
+The
+.B LC_CTYPE
+environment variable will also affect which characters are considered
+to be unprintable when filenames are printed;
+see the section UNUSUAL FILENAMES.
 
 .IP LC_MESSAGES
-Determines the locale to be used for internationalised messages.  If
-the `POSIXLY_CORRECT' environment variable is set, this also
-determines the interpretation of the response to the prompt made by the
+Determines the locale to be used for internationalised messages.  If the
+.B POSIXLY_CORRECT
+environment variable is set, this also determines the interpretation of
+the response to the prompt made by the
 .B \-ok
 action.
 
@@ -2061,15 +2085,21 @@ the output for
 all messages printed on stderr are diagnostics and must result in a
 non-zero exit status.
 .IP
-When POSIXLY_CORRECT is not set,
+When
+.B POSIXLY_CORRECT
+is not set,
 .B "\-perm \fI+zzz\fR"
 is treated just like
 .B "\-perm \fI/zzz\fR"
 if
-\fI+zzz\fR is not a valid symbolic mode.  When POSIXLY_CORRECT is set, such
+\fI+zzz\fR is not a valid symbolic mode.  When
+.B POSIXLY_CORRECT
+is set, such
 constructs are treated as an error.
 .IP
-When POSIXLY_CORRECT is set, the response to the prompt made by the
+When
+.B POSIXLY_CORRECT
+is set, the response to the prompt made by the
 .B \-ok
 action is interpreted according to the system's message catalogue, as
 opposed to according to
@@ -2592,7 +2622,7 @@ should be used instead.
 .
 .P
 The environment variable
-.B  LC_COLLATE
+.B LC_COLLATE
 has no effect on the
 .B \-ok
 action.
-- 
2.30.0

