On Sat, 16 Nov 2024 at 15:01, Robert Elz <k...@munnari.oz.au> wrote: > 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. >
In the general case I agree; man pages should be reference manuals, not tutorials. But in this case we have a language that simultaneously *looks* familiar, but *actually* has an unfamiliar grammar, radically different semantics, and a large number of intricate behind-the-scenes interactions. As a result, some significant fraction of users are going to overestimate how well they understand it, and prematurely skip from the "tutorial" phase to the "reference manual" phase. If nothing else, the manual needs to point out, in unequivocal ways that cannot be missed, that they really *don't* understand it as well as they think they do, and that they need to go study a tutorial before doing anything else (and especially before submitting a bug report). And that needs to be right up front, where they cannot miss it. I would hope that this idea isn't controversial, but if you feel my idea misses something important then please let me know. If you agree with the idea, then I would welcome suggestions for improving the wording below, which I offer as a tentative implementation of the idea above. (Insert this between the "Copyright" and "Description" sections) *“PrefaceDear reader, if this is your introduction to the Shell programming language, please be aware that although it may look like other languages you are familiar with, such similarity is deceptive. The shell language is different in subtle and non-obvious ways from all (*1) other languages, and making assumptions based on what you know from other languages will lead you into traps. Please read the "Shell Grammar" section, allowing **time to digest it **slowly and thoroughly, and then read at least one of the recommended tutorials listed in appendix B. If you are unsure whether you fully understand the Shell, please take the test in appendix A.”* (Insert this after the "Bugs" section) *“Appendix A: a self-test to check understanding of basic principles.If you have trouble answering these questions then you should read one of the tutorials in Appendix B before consulting this manual. It will also be helpful to read the "Shell Grammar" section. Please write down your answer to each question, and then run its code (*2) to see if its behaviour matches your answer. There is no pass or fail mark, but any mismatch indicates that you would likely benefit from revision.* *1. What will be displayed when you run this: foo=bar ; echo zot | read foo ; echo "$foo"* *2. What will be displayed when you run this: export foo=bar ; foo=zot ; env | grep ^foo=* *3. ...” *(additional questions welcome) *“Appendix B: Recommended TutorialsBefore consulting this manual, we recommend reading: https://mywiki.wooledge.org/BashGuide <https://mywiki.wooledge.org/BashGuide> *http://guide.bash.academy/* etc... We recommend avoiding the so-called Advanced Bash-Scripting Guide on * tldp.org <https://tldp.org/LDP/abs/html/> *...”*(additional reading suggestions welcome) -Martin (*1: yes I know it's an offshoot of the UNIX v7 shell, and other similar languages were designed around the same time, but they're all dead now, and certainly won't be encountered by a neophyte reading this manual page in 2024.) (*2: this may require some finessing of nroff to ensure that it does NOT substitute curly quotes or otherwise mess with the shell syntax, so that users can simply copy & paste the example code to test it)
