On Sun, Nov 24, 2024 at 22:51:43 +1000, Martin D Kealey wrote:
> When one *doesn't *already know how it works, “using the syntax *[:class:]*”
> could just as easily mean using *:class:* inside *[…]*.
Yeah, good luck with that. I predict that if you offer a patch to
make this clearer, there will be a huge amount of resistance.
Similar cases exist elsewhere within the man page. For example, if you
search for $! or $$ you will not find the section that documents them.
You would have to know that $! is a "Special Parameter", and then search
for Special Parameter to find it -- and even then, what you find is just
a raw ! with no $ in front of it. (My patch to clarify this was
rejected. It doesn't help that POSIX documents this exactly the same
way, with just # and ! and ? rather than $# and $! and $? being shown.)
Another one that commonly trips people up is the ${parameter-word}
expansion. The man page only has ${parameter:-word} shown. There's
a paragraph above it that talks about "omitting the colon", but people
don't see that.
Newer editions of POSIX include a table that shows both
${parameter:-word} and ${parameter-word} (see
<https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#tag_19_06_02>).
Bash doesn't have that.
In addition, POSIX puts the paragraph that mentions "omission of the
<colon>" *below* the section that people see, rather than above it.
So, if someone scans down the page until they find the eye-catching
${paramter:-word} definitions, and keeps reading from that point,
they will eventually find the paragraph about the colons, even before
the table. They don't have to read *backwards* to find it.
