Re: [PATCH v2 0/7] Ancient documentation fixes from Debian

[Chet Ramey]

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?

Following the reasoning of <https://bugs.debian.org/115290>,

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.

On 22/09/25 17:37, Chet Ramey wrote:

## [PATCH 5/7] builtins/test: Document that file expressions act on the symlink target

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    c...@case.edu    http://tiswww.cwru.edu/~chet/

OpenPGP_signature.asc
Description: OpenPGP digital signature