Re: misc/37981: shell builtin manpages are for csh(1) only...

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

The following reply was made to PR misc/37981; it has been noted by GNATS.

From: David Holland <dholland-bugs%netbsd.org@localhost>
To: gnats-bugs%netbsd.org@localhost
Cc: 
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Sun, 12 Jun 2016 02:48:27 +0000

 On Sat, Feb 09, 2008 at 10:55:05PM +0000, David Holland wrote:
  >  It is probably a good idea to have stub pages that point to the proper
  >  documentation for each shell, plus crossreferences for the same
  >  functionality in other shells (e.g. csh limit <-> sh ulimit).
 
 On Fri, Apr 11, 2008 at 12:10:03PM +0000, Greg A. Woods wrote:
  >  [...]
  >  Alternately it might be helpful if the built-in command manual pages
  >  were named with their shell name as a prefix, then at least apropos(1)
  >  would find them, eg:
  >  
  >  	sh-alias(1)
  >  	csh-alias(1)
  >  	ksh-alias(1)
 
 Fast-forward eight years and it's pretty clear that the right way to
 do this is with disambiguation pages like Wikipedia uses.
 
 So alias(1) should point to sh-alias(1), csh-alias(1), and
 ksh-alias(1), and probably also to a shell(7) or thereabouts that
 explains what different shells are about.
 
 In the case of things like time(1) that are both standalone programs
 and common builtins I'm not sure if the main page should be the
 disambiguation page or document the binary and link to something like
 time-disambig(1). I guess probably it should depend on how likely the
 user is to be looking for docs on a builtin, which means doing an
 assessment of which shells have which builtins and how popular those
 shells are.
 
 (In the case of time(1) since it's apparently built into everything
 but sh, I guess the time(1) page should be disambiguation. So what do
 we call the page for /usr/bin/time? time-bin(1)?)
 
 -- 
 David A. Holland
 dholland%netbsd.org@localhost