On Fri, 15 Nov 2024 at 00:20, Chet Ramey <chet.ra...@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”.*
