Re: [PATCH 09/25] doc/bashref.texi: Favor present tense over future.

[G. Branden Robinson]

Hi Chet,

I should note that I have further patches in preparation to make
parallel changes to the man pages.  I meant to hold this one back until
those were ready.

If this stylistic change is unacceptable, let me know, so I won't waste
time finishing that work.  :)

Regards,
Branden

At 2024-11-21T22:21:07-0600, G. Branden Robinson wrote:
> ---
>  doc/bashref.texi | 103 +++++++++++++++++++++++++----------------------
>  1 file changed, 54 insertions(+), 49 deletions(-)
> 
> diff --git a/doc/bashref.texi b/doc/bashref.texi
> index ffaa863b..74581695 100644
> --- a/doc/bashref.texi
> +++ b/doc/bashref.texi
> @@ -554,7 +554,7 @@ @node Top
>  
>  Prefixing a double-quoted string with a dollar sign (@samp{$}), such
>  as @verb{|$"hello, world"|},
> -will cause the string to be translated according to the current locale.
> +causes the string to be translated according to the current locale.
>  The @code{gettext} infrastructure performs the lookup and 
>  translation, using the @code{LC_MESSAGES}, @code{TEXTDOMAINDIR},
>  and @code{TEXTDOMAIN} shell variables, as explained below.
> @@ -1224,7 +1224,7 @@ @node Top
>  If the pattern is stored in a shell variable, quoting the variable
>  expansion forces the entire pattern to be matched literally.
>  
> -The pattern will match if it matches any part of the string.
> +The match succeeds if the pattern matches any part of the string.
>  If you want to force the pattern to match the entire string,
>  anchor the pattern using the @samp{^} and @samp{$} regular expression
>  operators.
> @@ -1361,7 +1361,7 @@ @node Top
>  
>  Bash sets
>  @code{BASH_REMATCH}
> -in the global scope; declaring it as a local variable will lead to
> +in the global scope; declaring it as a local variable leads to
>  unexpected results.
>  
>  Expressions may be combined using the following operators, listed
> @@ -1680,7 +1680,7 @@ @node Top
>  
>  For example, if a variable @env{var} is declared as local in function
>  @code{func1}, and @code{func1} calls another function @code{func2},
> -references to @env{var} made from within @code{func2} will resolve to the
> +references to @env{var} made from within @code{func2} resolve to the
>  local variable @env{var} from @code{func1}, shadowing any global variable
>  named @env{var}.
>  
> @@ -1707,25 +1707,25 @@ @node Top
>  func1
>  @end example
>  
> -The @code{unset} builtin also acts using the same dynamic scope: if a  
> -variable is local to the current scope, @code{unset} will unset it;         
> -otherwise the unset will refer to the variable found in any calling scope 
> +The @code{unset} builtin also acts using the same dynamic scope: if a
> +variable is local to the current scope, @code{unset} unsets it;
> +otherwise the unset refers to the variable found in any calling scope
>  as described above.
> -If a variable at the current local scope is unset, it will remain so
> +If a variable at the current local scope is unset, it remains so
>  (appearing as unset)
>  until it is reset in that scope or until the function returns.
>  Once the function returns, any instance of the variable at a previous
> -scope will become visible.
> +scope becomes visible.
>  If the unset acts on a variable at a previous scope, any instance of a
> -variable with that name that had been shadowed will become visible
> +variable with that name that had been shadowed becomes visible
>  (see below how the @code{localvar_unset} shell option changes this
>  behavior).
>  
>  The @option{-f} option to the @code{declare} (@code{typeset})
>  builtin command (@pxref{Bash Builtins})
> -will list function names and definitions.
> +lists function names and definitions.
>  The @option{-F} option to @code{declare} or @code{typeset}
> -will list the function names only
> +lists the function names only
>  (and optionally the source file and line number, if the @code{extdebug}
>  shell option is enabled).
>  Functions may be exported so that child shell processes
> @@ -1736,7 +1736,7 @@ @node Top
>  The @option{-f} option to
>  the @code{unset} builtin
>  (@pxref{Bourne Shell Builtins})
> -will delete a function definition.
> +deletes a function definition.
>  
>  Functions may be recursive.
>  The @code{FUNCNEST} variable may be used to limit the depth of the
> @@ -1796,8 +1796,8 @@ @node Top
>  
>  In the context where an assignment statement is assigning a value
>  to a shell variable or array index (@pxref{Arrays}),
> -the @samp{+=} operator will append to
> -or add to the variable's previous value.
> +the @samp{+=} operator appends to
> +or increments to the variable's previous value.
>  This includes arguments to declaration commands such as
>  @code{declare} that accept assignment statements.
>  When @samp{+=} is applied to a variable
> @@ -1844,7 +1844,7 @@ @node Top
>  
>  If the control variable in a @code{for} loop has the nameref attribute,
>  the list of words can be a list of shell variables, and a name reference
> -will be established for each word in the list, in turn, when the loop is
> +is established for each word in the list, in turn, when the loop is
>  executed.
>  Array variables cannot be given the nameref attribute.
>  However, nameref variables can reference array variables and subscripted
> @@ -1852,7 +1852,7 @@ @node Top
>  Namerefs can be unset using the @option{-n} option to the @code{unset} 
> builtin
>  (@pxref{Bourne Shell Builtins}).
>  Otherwise, if @code{unset} is executed with the name of a nameref variable
> -as an argument, the variable referenced by the nameref variable will be 
> unset.
> +as an argument, the variable referenced by the nameref variable is unset.
>  
>  @node Positional Parameters
>  @subsection Positional Parameters
> @@ -2576,7 +2576,7 @@ @node Top
>  Quoting any part of @var{string} inhibits replacement in the
>  expansion of the quoted portion, including replacement strings stored
>  in shell variables.
> -Backslash will escape @samp{&} in @var{string}; the backslash is removed
> +Backslash escapes @samp{&} in @var{string}; the backslash is removed
>  in order to permit a literal @samp{&} in the replacement string.
>  Users should take care if @var{string} is double-quoted to avoid
>  unwanted interactions between the backslash and double-quoting, since
> @@ -2704,7 +2704,7 @@ @node Top
>  @item A
>  The expansion is a string in the form of
>  an assignment statement or @code{declare} command that, if
> -evaluated, will recreate @var{parameter} with its attributes and value.
> +evaluated, recreates @var{parameter} with its attributes and value.
>  @item K
>  Produces a possibly-quoted version of the value of @var{parameter},
>  except that it prints the values of
> @@ -2786,7 +2786,7 @@ @node Top
>  Any side effects of @var{command} take effect immediately
>  in the current execution environment and persist in the current 
>  environment after the command completes (e.g., the @code{exit} builtin
> -will exit the shell).
> +exits the shell).
>  
>  This type of command substitution superficially resembles executing an
>  unnamed shell function: local variables are created as when a shell
> @@ -2885,10 +2885,10 @@ @node Top
>  expansion.
>  
>  If the @code{>(@var{list})} form is used, writing to
> -the file will provide input for @var{list}.
> +the file provides input for @var{list}.
>  If the
>  @code{<(@var{list})} form is used, reading the file 
> -will obtain the output of @var{list}.
> +obtains the output of @var{list}.
>  No space may appear between the @code{<} or @code{>}
>  and the left parenthesis, otherwise the construct would be interpreted
>  as a redirection.
> @@ -3022,7 +3022,7 @@ @node Top
>  enabling the @code{dotglob}
>  shell option, so all other filenames beginning with a
>  @samp{.}
> -will match.
> +match.
>  To get the old behavior of ignoring filenames beginning with a
>  @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
>  The @code{dotglob} option is disabled when @env{GLOBIGNORE}
> @@ -3055,9 +3055,9 @@ @node Top
>  Matches any string, including the null string.
>  When the @code{globstar} shell option is enabled, and @samp{*} is used in
>  a filename expansion context, two adjacent @samp{*}s used as a single
> -pattern will match all files and zero or more directories and
> +pattern match all files and zero or more directories and
>  subdirectories.
> -If followed by a @samp{/}, two adjacent @samp{*}s will match only
> +If followed by a @samp{/}, two adjacent @samp{*}s match only
>  directories and subdirectories.
>  @item ?
>  Matches any single character.
> @@ -3193,8 +3193,8 @@ @node Top
>  Each redirection that may be preceded by a file descriptor number
>  may instead be preceded by a word of the form @{@var{varname}@}.
>  In this case, for each redirection operator except
> ->&- and <&-, the shell will allocate a file descriptor greater
> -than 10 and assign it to @{@var{varname}@}.
> +>&- and <&-, the shell allocates a file descriptor greater
> +than 10 and assigns it to @{@var{varname}@}.
>  If @{@var{varname}@} precedes >&- or <&-,
>  the value of @var{varname} defines the file
>  descriptor to close.
> @@ -3245,7 +3245,7 @@ @node Top
>  Bash handles several filenames specially when they are used in
>  redirections, as described in the following table.
>  If the operating system on which Bash is running provides these
> -special files, Bash will use them; otherwise it will emulate them
> +special files, Bash uses them; otherwise it will emulate them
>  internally with the behavior described below.
>  
>  @table @code
> @@ -3309,7 +3309,7 @@ @node Top
>  @code{noclobber}
>  option to the
>  @code{set}
> -builtin has been enabled, the redirection will fail if the file
> +builtin has been enabled, the redirection fails if the file
>  whose name results from the expansion of @var{word} exists and is
>  a regular file.
>  If the redirection operator is @samp{>|}, or the redirection operator is
> @@ -6828,9 +6828,9 @@ @node Top
>  
>  @item BASH_XTRACEFD
>  If set to an integer corresponding to a valid file descriptor,
> -Bash will write the trace output generated when
> +Bash writes the trace output generated when
>  @samp{set -x}
> -is enabled to that file descriptor
> +is enabled to that file descriptor,
>  instead of the standard error.
>  This allows tracing output to be separated from diagnostic and error
>  messages.
> @@ -6935,7 +6935,7 @@ @node Top
>  Assigning to members of this array variable may be used to modify
>  directories already in the stack, but the @code{pushd} and @code{popd}
>  builtins must be used to add and remove directories.
> -Assignment to this variable will not change the current directory.
> +Assignment to this variable does not change the current directory.
>  If @env{DIRSTACK}
>  is unset, it loses its special properties, even if
>  it is subsequently reset.
> @@ -7024,7 +7024,7 @@ @node Top
>  @item FUNCNEST
>  A numeric value greater than 0 defines a maximum function nesting level.
>  Function invocations that exceed this nesting level
> -will cause the current command to abort.
> +cause the current command to abort.
>  
>  @item GLOBIGNORE
>  A colon-separated list of patterns defining the set of file names to
> @@ -7070,7 +7070,7 @@ @node Top
>  numbers and sorts them using their numeric value
>  (so
>  ``2''
> -will sort before
> +sorts before
>  ``10'', for example).
>  When using @samp{numeric}, names containing non-digits sort after all
>  the all-digit names and are sorted by name using the traditional
> @@ -7171,7 +7171,7 @@ @node Top
>  it is not saved on the history list.
>  Each pattern is anchored at the
>  beginning of the line and must match the complete line
> -(Bash will not implicitly append a
> +(Bash does not implicitly append a
>  @samp{*}).
>  Each pattern is tested against the line
>  after the checks specified by
> @@ -7394,8 +7394,8 @@ @node Top
>  Assigning a value to this
>  @env{RANDOM}
>  initializes (seeds) the sequence of random numbers.
> -Seeding the random number generator with the same constant value will
> -produce the same sequence of values.
> +The random number generator produces a consistent sequence of values for
> +a given seed.
>  If @env{RANDOM}
>  is unset, it loses its special properties, even if it is
>  subsequently reset.
> @@ -7499,7 +7499,7 @@ @node Top
>  The optional @var{p} is a digit specifying the precision, the number of
>  fractional digits after a decimal point.
>  A value of 0 causes no decimal point or fraction to be output.
> -@code{time} will print at most six digits after the decimal point;
> +@code{time} prints at most six digits after the decimal point;
>  values of @var{p} greater than 6 are changed to 6.
>  If @var{p} is not specified,
>  @code{time} prints three digits after the decimal point.
> @@ -7687,7 +7687,7 @@ @node Top
>  These are the strings that
>  are subject to language translation when the current locale
>  is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
> -This implies the @option{-n} option; no commands will be executed.
> +This implies the @option{-n} option; no commands are executed.
>  
>  @item [-+]O [@var{shopt_option}]
>  @var{shopt_option} is one of the shell options accepted by the
> @@ -7809,7 +7809,7 @@ @node Top
>  that order.
>  The
>  @option{--noprofile}
> -option will inhibit this behavior.
> +option inhibits this behavior.
>  
>  When invoked as an interactive shell with the name @code{sh}, Bash
>  looks for the variable @env{ENV}, expands its value if it is defined,
> @@ -7847,12 +7847,13 @@ @node Top
>  it reads and executes commands from
>  @file{~/.bashrc},
>  if that file exists and is readable.
> -It will not do this if invoked as @code{sh}.
> +If invoked as @code{sh},
> +the shell does not read this file.
>  The
>  @option{--norc}
> -option will inhibit this behavior, and the
> -@option{--rcfile} option
> -will make Bash use a different file instead of
> +option inhibits this behavior, and the
> +@option{--rcfile}
> +option makes Bash use a different file instead of
>  @file{~/.bashrc},
>  but neither
>  @code{rshd} nor @code{sshd} generally invoke the shell with those
> @@ -8411,7 +8412,7 @@ @node Top
>  Any variable may be used as an indexed array;
>  the
>  @code{declare}
> -builtin will explicitly declare an array.
> +builtin explicitly declares an array.
>  There is no maximum
>  limit on the size of an array, nor any requirement that members
>  be indexed or assigned contiguously.
> @@ -8500,8 +8501,11 @@ @node Top
>  @var{name}, so negative indices count back from the end of the
>  array, and an index of -1 references the last element.
>  
> -The @samp{+=} operator will append to an array variable when assigning
> -using the compound assignment syntax; see @ref{Shell Parameters} above.
> +The @samp{+=} operator appends to an array variable when assigning
> +using the compound assignment syntax;
> +see
> +@ref{Shell Parameters}
> +above.
>  
>  An array element is referenced using
>  @code{$@{@var{name}[@var{subscript}]@}}.
> @@ -8542,9 +8546,10 @@ @node Top
>  
>  Referencing an array variable without a subscript is equivalent to
>  referencing with a subscript of 0.
> -Any reference to a variable using a valid subscript is valid, and
> +Any reference to a variable using a valid subscript is valid,
> +and
>  Bash
> -will create an array if necessary.
> +creates an array if necessary.
>  
>  An array variable is considered set if a subscript has been assigned a
>  value.
> -- 
> 2.30.2
>

signature.asc
Description: PGP signature