Re: [PATCH v2 0/7] Ancient documentation fixes from Debian
From:
Chet Ramey
Subject:
Re: [PATCH v2 0/7] Ancient documentation fixes from Debian
Date:
Tue, 23 Sep 2025 10:15:32 -0400
User-agent:
Mozilla Thunderbird
On 9/22/25 6:55 PM, Gioele Barabucci wrote:
Hi Chet,
I'm consolidating my replies to your replies in this email.
Thanks, it's much easier to have a single thread.
Before I start, a note: I'm a Debian developer, but I'm not the Debian
maintainer of bash. I'm just helping cleaning up 25 years of Debian
packaging cruft. :)
I suspect that most of these were added years ago and the Debian folks
just carry them forward from release to release without looking at any
documentation changes that might render them unnecessary.
I hope that these patches can be integrated "as is" or that they
can serve as starting points for discussions about possible
additional documentation.
Why are you sending these again?
As Brenden suggested, that was a revision of the original patchset,
modified to use Branden's choice of words.
Yep, it's fine, the real question is whether they're necessary at all.
## [PATCH 1/7] doc: Document interaction between `exec` and redirections
On 22/09/25 17:28, Chet Ramey wrote:
I'm satisfied with the language in the current man page, which is
"When used with the exec builtin, redirections modify file handles in
the current shell execution environment."
I see. So you would prefer to see this additional remark removed from
Debian's version of bash, right?
Yes, it seems redundant.
## [PATCH 2/7] doc/bash.1: Document deprecated syntax for arithmetic
evaluation
On 22/09/25 17:56, Chet Ramey wrote:
I think we're going to leave this undocumented and discouraged.
Well, nobody will know that the `$[]` syntax is discouraged if it is not
documented. :)
And "undocumented" will it not be, since it is present in bash(1) in Debian
and all Debian's derivatives. That includes also plenty of websites
generated from those man pages.
So this is a `problem' that Debian created.
What would be the downside of acknowledging this deprecated syntax in the
Bash's documentation?
Since it hasn't been documented in the bash man page or texinfo manual
since the 1990s, I don't see any reason to start now. No one should use it.
## [PATCH 3/7] doc/bash.1: Mention quoting when assigning to FIGNORE
On 22/09/25 17:31, Chet Ramey wrote:
The added text doesn't align with the example, which does not need
quoting. Can you show an example where the tilde expansion might
matter?
OK. Is there any reason to single out FIGNORE in favor of these other
variables, since the Tilde Expansion section says
"Bash checks each variable assignment for unquoted tilde-prefixes imme-
diately following a : or the first =, and performs tilde expansion in
these cases."
## [PATCH 4/7] doc/bash.1: Document role of LC_COLLATE in case insensitive
pathname expansion
On 22/09/25 17:35, Chet Ramey wrote:
I think the existing text describing the behavior of range
expressions is sufficient. This paragraph describes the effect of the
shell options.
I can see adding some text referencing globasciiranges to that
section.
I agree that is the wrong place to talk about that peculiarity of non-ascii
ranges. But that specific issue ("[a-z] may match upcase characters") is
IMO problematic enough to deserve a mention in the manual.
I think the existing text
"To obtain the tradi-
tional interpretation of range expressions, where [a-d]
is equivalent to [abcd], set the value of the LC_COLLATE
or LC_ALL shell variables to C, or enable the globasci-
iranges shell option."
covers this.
## [PATCH 5/7] builtins/test: Document that file expressions act on the
symlink target
On 22/09/25 17:37, Chet Ramey wrote:
This is already specified in the man page and info file. Does it need
to be in the help text as well?
Why not? It does seem like an important piece of information (that's why it
is in the man page in the first page).
Is it that important, though? The help text isn't intended to contain
everything the man page does, just the things you want at your
fingertips.
If folks think it's valuable, I can add something for the next version,
but it won't appear before then -- it invalidates all the existing
translations.
## [PATCH 7/7] doc/bash.1: Document -v/-x options
On 22/09/25 17:15, Chet Ramey wrote:
I think the existing documentation covers this.
It does by referring to `set`, but `-v` and `-x` are common options that
IMO should be highlighted in the man page.
Why call them out specially? They might be more commonly used than
something like, say, `-o posix', or `-e', or `-u' (though I suspect not,
given all the `advice' that exists in favor of using `-euo pipefail'),
but there's nothing special about them.
Chet
--
``The lyf so short, the craft so long to lerne.'' - Chaucer
``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU chet@case.edu http://tiswww.cwru.edu/~chet/