Re: CVS commit: src/bin/sh

[Valery Ushakov <uwe%stderr.spb.ru@localhost>]

On Fri, Mar 16, 2018 at 23:58:30 +0700, Robert Elz wrote:

>     Date:        Fri, 16 Mar 2018 17:24:55 +0300
>     From:        Valery Ushakov <uwe%stderr.spb.ru@localhost>
>     Message-ID:  <20180316142455.GF3278%pony.stderr.spb.ru@localhost>
> 
>   | mdoc.samples(7) is a very handy reference.
> 
> For me that is the same as mdoc(7) (a copy of the same
> man page) - is that what is intended (I see mdoc.samples(7) has
> 2 links - I did not chase down and find what the other is, except
> to know it is not mdoc(7) which is a copy) and while I agree that it is
> useful, it isn't all that useful - for example, it says that Dv is
> for:
> 	A variable (or constant) which is defined in an include file
> 
> And so which would never be appropriate in sh(1) for which
> include files are irrelevant.
>
> This is one of the reasons I have typically avoided mdoc -- while
> I understand and agree with the intent, much of what it provides
> is far too specific, and leaves too many cases fall through the
> cracks.   Defined variables (which I would extend beyond include
> files to also allow anything #define'd - in an include file or not)
> environment variables, arguments, internal commands, command
> modifiers (and flags) all have macros, just just simple variables,
> which are none of those, and constants, do not seem to have a
> macro of their own - and just fall back on the catch all Li (literal).
>
> Given that, was changing .Li 0 into .Dv 0 really the right thing to
> do?   "0" is certainly not a defined variable...    (changing the
> input to whatever just happens to generate the output desired,
> regardless of semantics seems like cheating to me.)

Right, mdoc vocabulary is defined sometimes in a bit too C-centric
terms, however even its own man page has a passage or two that
indicate that common sense should be used when it's applied to other
languages.  Defining wast hair-splitting vocabularies is possible, but
do we really want a version of DocBook for troff? :)

IMO, .Dv is the perfect match for shell parameters that has defined
semantic associated with them.

That reminds me...  We currently abuse ENVIRONMENT section to document
variables like PS1 or HISTSIZE which are quite obviously not
environment variables.  I think most of them should be moved out of
.Sh ENVIRONMENT into a separate .Ss section inside .Sh DESCRIPTION
(and the LINENO section should moved into DESCRIPTION as well).

-uwe