Date: Sat, 16 Nov 2024 14:05:17 +1000
From: Martin D Kealey <mar...@kurahaupo.gen.nz>
Message-ID:
<CAN_U6MXQJ9cy2d9XMgjGgfU8=d1_ebrgbusb2u1sxhyloqq...@mail.gmail.com>
| I know, but "explicitly" is not the same as "highlighted", let alone "well
| enough".
Please, nothing at all like you're suggesting. Man pages are not, and
not intended to be, tutorials.
People who need tutorials should go get exactly that - there are books on
shell programming, and I expect, at least one that is precisely on bash.
If that kind of thing isn't good enough, talk to their authors. Refer
obvious newbies to those, not to the man page.
kre
ps: that is perhaps except for the separate man pages for built-ins.
I have been considering doing something like that - document the generic
properties of the built-ins, make passing reference to some shell specific
variations, and refer the user to their specific shell documentation for
shell specific details. Then the shell man page needs a reference to the
man page for the built-in, followed by any variations that particular shell
makes to how it works.
