Re: The 'source x' command doesn't keep variables set by x when source output is piped into other command

[Martin D Kealey]

On Fri, 15 Nov 2024 at 00:20, Chet Ramey <chet.ramey@case.edu> wrote:

> On 11/13/24 11:40 PM, Martin D Kealey wrote:
>
> > The fact that pipeline components are implicitly run in subshells is
> > arguably not highlighted well enough [...]
>


> The man page states that explicitly.
>

I know, but "explicitly" is not the same as "highlighted", let alone "well
enough".

Novice shell users tend to have a weak-at-best grasp of process separation,
and an abysmal-to-non-existent grasp of subshells, so the documentation for
Bash needs to drive those home at every opportunity.

I know that the FSF believes that "info" is the *one true documentation
format*, but that's pretty unrealistic in most environments. If people want
documentation from the command line, they type "man whatever", because it
works. (Or they ask Facebook or Bing or Google or Reddit or StackExchange,
and get ... wherever.)

The manual page runs to 7000+ lines, all in one document, so most people
*don't* read it from start to finish; rather they search for keywords.

If a warning or explanation isn't shown in response to such a search, it
might as well not exist.

There are no hyperlinks in man pages. Most $PAGER programs have a search
function, but it's a challenge to convince a human under the age of 40 to
use it. So I conclude that *writing* "see also" is not enough; any warning
text itself has to be repeated, immediately adjacent to each description
where it's germane.

And yes that would probably blow up the current 7000 lines to 10000+ lines.
Perhaps the Bash man page needs to be broken into many separate pages,
including one-per-builtin.

-Martin

PS: I would envisage maybe as many as a hundred repetitions of something
like this: *“The built-in Foo command changes the Bar setting only in the
current process, which may or may not be your script's main process. Please
read "man bash-subshell" for an explanation of when new processes are
created and how this affects **each of the **built-in commands”* or this: *“The
Zot construct creates a subshell. This will limit the effects of built-in
commands within it, preventing them from changing settings in the main
process. Please read "man bash-subshell" for an explanation of when new
processes are created and how this affects **each of the **built-in
commands”.*