A request to segregate man pages for shell built-ins

[Ian Smith]

In freebsd-questions Digest, Vol 699, Issue 4, Message: 3
On Wed, 25 Oct 2017 15:16:47 +0200 Polytropon <freebsd at edvax.de> wrote:

 > On Wed, 25 Oct 2017 02:23:23 +0000, Manish Jain wrote:
 > > But I run into roughly the same weather with shell built-ins, most of 
 > > which do not have their own man page. 'man set' rather blandly throws up
 > > the man page for the shell, and it takes an immense effort to glean the 
 > > relevant information.

Trouble is, it all depends on what shell you're using - at a given time.

 > > Is it not possible to create separate man pages for the shell built-ins 
 > > too ? Or at least ensure that invoking the built-in with --help gets the 
 > > necessary information ?

builtin(1) has always worked for me.  But then, I only use sh(1) for 
scripting and csh(1) interactively, and they're the only two it covers.

 > The key problem is that different shells might have a builtin
 > with the same name, but different syntax or behaviour. That's
 > why you typically use "man sh" or "man csh" and then search
 > for the builtin within that man page.

Yes, after consulting builtin(1) perhaps .. 

 > > (Note : some built-ins (e.g. 'test') do have their own man pages)
 > 
 > Well, test is a binary, a separate program, not a builtin. ;-)
 > 
 > 	% which test
 > 	/bin/test
 > 
 > 	% which [
 > 	/bin/[

% which test
/bin/test
% sh
$ which test
/bin/test

These results are correct for test, but it _is_ builtin to sh(1):

     [       A built-in equivalent of test(1).
     test    A built-in equivalent of test(1).

Fortunately - or it'd be much slower with, um, testing.  So which isn't 
aware of the sh(1) builtin (since sh(1) has no 'which' builtin, so uses 
which(1)) .. whereas csh(1) has builtin which but no 'test' (as such, 
though all test's, um, tests can be done in csh).  Easily confusing, eh?

           Command       External    csh(1)    sh(1)
           echo          Yes         Yes       Yes
           test          Yes         No        Yes

 > Of course, [ and test are actually one and the same binary.

And the builtin test in sh(1) is correctly covered by test(1).

 > Keep in mind some shells also offer a builtin replacement for
 > an existing binary. A good example is echo where a binary exists,
 > but the C Shell has its own internal echo, while BASH uses the
 > binary one:
 > 
 > 	% which echo
 > 	echo: shell built-in command.
 > 
 > 	$ which echo
 > 	/bin/echo

Again, despite that, echo _is_ builtin to sh(1) - and has more options.

 > In such a case, what should "man echo" show?

Among other things, see builtin(1)" .. oh, it already does.

Perhaps sh(1) could use a smarter 'which' that exposes its own builtins 
such as these two more readily - but who dares mess with sh(1) ? :)

cheers, Ian