Re: String substitution bug

[Martin D Kealey]

On Mon, 25 Nov 2024 at 00:21, Oğuz <oguzismailuysal@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.