Re: RFC: Enhancements/changes to sh doc and a possible sh extension

[David Holland <dholland-tech%netbsd.org@localhost>]

On Wed, Oct 18, 2017 at 05:49:31PM +0700, Robert Elz wrote:
 > A while ago it was suggested (perhaps in some private mail) that perhaps
 > all of the builtin sh commands should have man pages of their own, rather
 > than only the ones which are also implemented as external commands.

I think I remember a discussion about that...

After chewing on it, what I think I'd like to see for builtins and
multiple shells is something like:

   - a page cd.1 that documents the basic behavior common to all shells(*)
   - pages of the form cd-sh.1 or cd-csh.1 that document shell-specific
     behavior, if there's more than say one paragraph of it
   - all of which should be clear on the command being a builtin, and
     why, unlike the current cd(1)

I don't think a new section (or a new suffix, which is slowly sorting
out to be comparable to a new section) is necessary or even really a
good idea, because the sections are basically namespaces.

(While shell builtins are technically in a different namespace from
ordinary bins, the difference doesn't matter until you get to the
point of calling exec yourself -- hopefully anyone who's doing that
can figure out what the difference is, and also that they should be
calling chdir(2) and not trying to exec it.)

 > We wouldn't necessarily need to document every sh builtin command in a
 > separate page (I'd not do most of the special builtins as one exclusion,
 > and perhaps not a few more that are too simple to need it (like say inputrc,
 > jobid and jobs .. just as examples)

Since the special builtins are more like syntax than commands, yes.
For the others, I dunno. It's nice if everything you can type also
comes up as a man page. "jobs", since it's shared with csh and
basically every other half-modern shell, seems like a good one to have
a page for. Currently "man jobs" brings up csh(1), which is not
optimal.

For ulimit, there should probably be one page that comes up for both
"ulimit" and "limit" that discusses the limits and the various
syntaxes for mucking with them.

 > (For this, you can assume
 > that I will be doing the work, at least initially, for sh(1) references,
 > so by agreeing it is a good idea you would not be volunteering!)

When/if I have time to work on anything again I'm happy to work on doc
cleanup like this :-)

 >             With the -n option, wait instead for any one of the given jobs, or
 >             if none are given, any job, to complete, and return the exit
 >             status of that job.  If none of the given job arguments is a
 >             current child of the shell, or if no job arguments are given and
 >             the shell has no unwaited for children, then the exit status will
 >             be 127.

I think this is good functionality to have, but unless it already
exists elsewhere under -n, I wonder if there isn't a better name for
it. I at least would expect -n to provide access to WNOHANG (which is
certainly useful for scripts, IMO...) and this to be something else.

I guess the optimum would be to have "wait" wait for one process and
"wait -a" to wait for all processes, but it's too late for that. And
-1 is probably bad for other reasons, and -o doesn't suggest "once"
but "output". So I don't actually have a suggestion, just a vague
dissatisfaction. :-(

 >             The -p var option allows the process (or job) identifier of the
 >             job for which the exit status is returned to be obtained.  The
 >             variable named (which must not be readonly) will be unset
 >             initially, and then set to the identifier from the arg list (if
 >             given) of the job that exited, or the process identifier of the
 >             job to exit when used with -n and no job arguments.  Note that -p
 >             with neither -n nor job arguments is useless, as in that case no
 >             job status is returned, the variable named is simply unset.

When I first read this I thought it was returning argv[0] from the
target job. On a second reading I thought it was returning the pid.
Now I'm just confused about what it's doing.

:-/

-- 
David A. Holland
dholland%netbsd.org@localhost