Re: CVS commit: src/bin/sh

[Robert Elz <kre%munnari.OZ.AU@localhost>]

    Date:        Sat, 17 Mar 2018 23:10:36 +0300
    From:        Valery Ushakov <uwe%stderr.spb.ru@localhost>
    Message-ID:  <20180317201036.GK3278%pony.stderr.spb.ru@localhost>

  | [this probably belong to tech-userlevel]

Perhaps - we don't really have a good place to discuss the doc.

  | ksh(1) has "Parameters" sections
  | bash(1) has a separate section "Shell Variables".

There are many different ways the doc could be structured,
zsh has a whole set of man pages rather than just one (all
three of those shells have rather more to document than our
sh has though).

What is the best heading to use, and what order to include
everything is a complex (and debatable) issue - it would be
easier (as it would matter less) if the man pages were to
return to their original purpose of simply being technical
specifications - but would also mean having user guides
as well (as the original Bell Labs, and even the CSRG
distributions had).   But that we have let slip - we don't
really have people interested in working on the latter.

So, the man pages need to serve both roles,. and that makes
them messier.

kre