On Mon, 25 Nov 2024 at 00:21, Oğuz <oguzismailuy...@gmail.com> wrote:
> In another document, not the manual. > If my suggested addition does not belong in the manual, then neither does *any* mention of "character class", nor indeed the entire existing description of "regular expression". Please provide a patch that removes this “unnecessary” text. Maybe stop referring to this minimalist ideal document as a 'manual' and instead call it what everyone else does: a cheat sheet. Should a man page be a cheat sheet, a manual, a tutorial, an overview, or something else? Or simply whatever is most useful in each case? I expect a product manual to be useful *to anyone who's allowed to use the product*. Likewise I expect a product service manual to be useful *to anyone who's allowed to service, repair, or alter the product*. A manual's purpose is to impart enough knowledge that the reader will understand all the options provided by the product, as well as its limitations and maintenance requirements. Good manuals use whatever communication tools are most appropriate to improve understanding, including: - anything critical that needs to be known immediately is shown on the first page; this includes an enumeration of any assumed knowledge, prerequisite skills, and required tools; - chapters that can be read as stand-alone documents, but with a helpful ordering of ideas overall; - precise unambiguous terminology & phrasing; - diagrams, with clear labels; - tables, that highlight contrasts and correlations; - examples, with both working and non-working cases; - references & citations (when printed) or hyperlinks (when online), directing people's attention to other relevant documents or other sections within the same document; - an internal index; - a glossary with definitions; - appendices with extra details of "side topics". A novice might still not understand everything, but they will at least *know* that they don't understand, and can follow the provided references or hyperlinks to appropriate material. If the man page is not going to explain, say, regular expressions (and in particular, that it does NOT mean PCRE), then it should say that up front: > > *“This document assumes you have a working knowledge of POSIX IEEE Std > 1003.1 "extended" regular expressions, as described at > https://pubs.opengroup.org/onlinepubs/9799919799/ > <https://pubs.opengroup.org/onlinepubs/9799919799/>. If you have a working > knowledge of “common” (PCRE) regular expressions, a summary of important > differences is given at [insert other link]”* To be consistent we should also remove any "extra" parts of the man page that contravene that declaration. (To be clear, I do *not* believe that the manual should refrain from detailed explanations; I'm just pointing out the inconsistency.) The man page format makes the inclusion of useful diagrams and hyperlinks quite challenging, so references and citations have to be described in a way that makes them usable by the reader, and the precision of wording becomes all the more critical. I don't have all the answers, but shooting down every suggestion with "not in this document", without saying *which* other document, is really unhelpful. How about this for a concrete proposal: let's split the current man page into a page per topic. The following list is alphabetical, though I should probably put it in some kind of narrative order. - bash(1) - an overview, a table of contents referencing the other man pages, and some basic navigation instructions. (“*References are given in standard «man» format: a name, followed by a section number in parentheses, like «bash-eval(7)». To follow that reference, you should exit this reader and then type «man 7 bash-foo».*”) - bash-alternatives - when NOT to use the shell (or Bash specifically) - bash-backstory(7) - explain how historical factors led to parts that seem weird by current standards; e.g. why we have “foo=value” rather than “$foo=value”. - bash-bnf(7) - explain how to read the subset of BNF used in the other bash man pages - bash-builtins(7) - Explain the distinction between “built in” and “special built in”; list all the available built-ins with references to their respective man pages. Highlight that most loadables create built-ins (so that the list given cannot be comprehensive). - bash-eval(7) - overview of how history expansion, other expansions, word splitting, globbing, and redirection are ordered and how they interact. Include counterexamples that don't work; this page follows bash-parsing(7). - bash-fishhooks(7) - explain common gotchas that trip up most neophytes; - bash-func(7) - stuff you need to know about functions. Strongly highlight that a function "definition" is a statement that does NOTHING until it's executed (“until the flow of control passes over it”), and that functions can be redefined as many times as is useful. Also highlight that “local”, and “declare” are also commands, with the same implication. - bash-deprecations(7) - stuff that should not be used if you can possibly help it. - bash-glob(7) - bash-glossary(7) - alphabetical list of terms, with definitions, and hyperlinks to pubs.opengroup.org where available. - bash-grammar(7) or bash-syntax(7) - Start by explaining "simple command", then its parts (pointing out that it need not include an actual command), then move on to pipelines, conditionals, and compound commands. Then give a full top-down BNF formal definition. - bash-history(7) - explain how “!” expansion is a separate phase before any other parsing; explain selectors and modifiers; explain how to *avoid* history expansion when “!” is present; give examples of where “!” expansion is more useful than using arrow keys to scroll back (“*diff <( !-2 ) <( !-1 )” checks for differences in the output of the previous two commands; see bash-subst(7) for an explanation of the <(...) syntax.*”) Finish with a full BNF-style definition. - bash-index(7) - an alphabetical list of topics covered in all the man pages, including which man page and which search term to use; include an appendix that explains how to search for tricky terms in common pagers. - bash-loadable(3) - an index of the provided built-ins - bash-modes(7) - explain the flags that require different idioms to be used (or avoided). - bash-options(7) - everything controlled by set -X, set -o, or shopt, or that can be provided on the command line. Explain how `shopt -q` can be used to test options, in preference to comparing $SHELL_OPTIONS or $BASH_OPTIONS. - bash-posix(7) - list all the stuff that's not in POSIX, in case you need to avoid them, plus work-around techniques - bash-quotes(7) - make pellucidly clear that quotes do not delimit arguments; explain how to work backwards from the desired arguments to the appropriate quoting. - bash-recipes - lots of examples of common exercises, with explanations. Include references to man pages for mandatory POSIX utilities (awk, grep, sed, cut) plus any other common examples - bash-redir(7) - explain all the redirection symbols. - bash-regex(7) - highlight that ERE is not PCRE; then explain the syntax and its effects. - bash-parsing(7) - a short tabulation of the order of the parsing phases, plus explanations of some of the interactions; this is page precedes bash-eval(7); - bash-status(7) - explain all the interactions of command exit status, including for compound commands. Point out the *lack* of precedence between && and ||. Point out anti-patterns like “[ $? = 0 ]”. Explain the limits of “set -e”, and that “!” is an antidote. - bash-style(7) - stuff that's not semantic to the shell, but which is helpful to humans, e.g. indentation, using UPPER_CASE for exported variables and lower_case for internal stuff; - bash-subshell(7) - explain what subshells are, explain all the places they're created, and enumerate all the cases where they impact shared state; - bash-subst(7) - explain all the substitutions, including $var, ${}, $(), ``, <(), >(), and $(<path) - a separate page for each of the built-ins, in section (1) (or section (1bash) where supported); the “shopt” and “set” pages should defer to bash-options(7). Pages for special builtins should each re-iterate that it *must* be a built-in to work properly. The pages for “declare”, “export”, “local”, “readonly” and “typeset” should explicitly reference bash-func(7) - a separate page for each of the loadables, in section (3) - more pages for any sections I've not included above. Each page should be short enough that it can be read in its entirety by an unskilled reader in under 10 minutes. If adding more information to a page would push it over that limit, create a new page, or split the current one. Each page should include references for "read this next" so that the whole manual can be read progressively. I'm not suggesting that this work should fall on Chet, but I'm not going to offer to make such a massive change unless there's reasonable hope that it will be accepted by the community. -Martin PS: funny how everyone thinks **I'm** the crazy misanthrope for wanting the manual page to start with "here be dragons, flee while you can", yet you're happy to have a mega cheat sheet masquerading as a manual that - by frustrating users and squandering their time - achieves much the same end result.
