From owner-freebsd-questions@freebsd.org Wed Oct 25 08:10:17 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 85222E4254C for ; Wed, 25 Oct 2017 08:10:17 +0000 (UTC) (envelope-from matthew@FreeBSD.org) Received: from smtp.infracaninophile.co.uk (smtp.infracaninophile.co.uk [IPv6:2001:8b0:151:1:c4ea:bd49:619b:6cb3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "smtp.infracaninophile.co.uk", Issuer "infracaninophile.co.uk" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4B2CE2530 for ; Wed, 25 Oct 2017 08:10:17 +0000 (UTC) (envelope-from matthew@FreeBSD.org) Received: from leaf.local (unknown [88.202.132.43]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: m.seaman@infracaninophile.co.uk) by smtp.infracaninophile.co.uk (Postfix) with ESMTPSA id BA5D314F3; Wed, 25 Oct 2017 08:10:15 +0000 (UTC) Authentication-Results: smtp.infracaninophile.co.uk; dmarc=none (p=none dis=none) header.from=FreeBSD.org Subject: Re: A request to segregate man pages for shell built-ins To: Arthur Chance , freebsd-questions@freebsd.org References: <6f62db58-8220-0fe4-133b-410da2f58579@qeng-ho.org> From: Matthew Seaman Message-ID: Date: Wed, 25 Oct 2017 09:10:12 +0100 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:52.0) Gecko/20100101 Thunderbird/52.4.0 MIME-Version: 1.0 In-Reply-To: <6f62db58-8220-0fe4-133b-410da2f58579@qeng-ho.org> Content-Type: text/plain; charset=utf-8 Content-Language: en-GB Content-Transfer-Encoding: 7bit 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: Wed, 25 Oct 2017 08:10:17 -0000 On 25/10/2017 08:40, Arthur Chance wrote: > On 25/10/2017 07:14, Matthew Seaman wrote: >> On 25/10/2017 03:23, Manish Jain wrote: >>> (Note : some built-ins (e.g. 'test') do have their own man pages) >> >> That's because there's a stand-alone test(1) as well as a shell built-in. >> >>> 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 ? >> >> I'm sure creating separate man pages is possible: it's just a question >> of someone stepping up and doing the work. > > "man builtin" suggests there might be a few problems in organising the > new pages. Some builtins work in both shells, others in only one, some > have external equivalents, others don't. Some builtins work differently > in the two shells. > > For example, do we have one page for echo or three: echo(bin), echo(sh) > and echo(csh)? /bin/echo has a single flag, the sh builtin has two and > the csh builtin mimics one or the other depending on a csh variable setting. > > Yes, it just needs someone to do the work but making the new pages > coherent and clear would take more effort than it first seems. > Indeed. In that case, I'd suggest thinking about how to arrange the man pages from the point of view of the person writing a shell script -- what's the most effective way for them to find the information they need? In the case of eg. echo(1), I'd be happy to see the existing page for the stand-alone echo refactored to cover all of the different flavours of echo -- the behaviour is much the same in most use cases -- plus some discussion on how the variants differ. Cheers, Matthew