A request to segregate man pages for shell built-ins

[Matthew Seaman]

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