A request to segregate man pages for shell built-ins

Matthew Seaman matthew at FreeBSD.org
Wed Oct 25 08:10:17 UTC 2017

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.



More information about the freebsd-questions mailing list