From owner-freebsd-questions@freebsd.org Thu Oct 26 16:02:47 2017 Return-Path: Delivered-To: freebsd-questions@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id D6310E4D2B8 for ; Thu, 26 Oct 2017 16:02:47 +0000 (UTC) (envelope-from smithi@nimnet.asn.au) Received: from sola.nimnet.asn.au (paqi.nimnet.asn.au [115.70.110.159]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 0FC798343A for ; Thu, 26 Oct 2017 16:02:45 +0000 (UTC) (envelope-from smithi@nimnet.asn.au) Received: from localhost (localhost [127.0.0.1]) by sola.nimnet.asn.au (8.14.2/8.14.2) with ESMTP id v9QG2H4H050556; Fri, 27 Oct 2017 03:02:18 +1100 (EST) (envelope-from smithi@nimnet.asn.au) Date: Fri, 27 Oct 2017 03:02:17 +1100 (EST) From: Ian Smith To: Polytropon cc: Manish Jain , freebsd-questions@freebsd.org Subject: Re: A request to segregate man pages for shell built-ins In-Reply-To: Message-ID: <20171027021115.A40402@sola.nimnet.asn.au> References: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: User questions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 26 Oct 2017 16:02:48 -0000 In freebsd-questions Digest, Vol 699, Issue 4, Message: 3 On Wed, 25 Oct 2017 15:16:47 +0200 Polytropon 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