On Saturday, November 16, 2024, Martin D Kealey <mar...@kurahaupo.gen.nz> wrote:
> (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) > This belongs in separate, unofficial document; not the reference manual, which is fine as is. -- Oğuz
