Re: misc/37981: shell builtin manpages are for csh(1) only...

[David Holland <dholland-bugs%netbsd.org@localhost>]

The following reply was made to PR misc/37981; it has been noted by GNATS.

From: David Holland <dholland-bugs%netbsd.org@localhost>
To: gnats-bugs%NetBSD.org@localhost
Cc: 
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Sun, 31 Jul 2016 21:18:23 +0000

 On Tue, Jun 28, 2016 at 09:20:01PM +0000, Abhinav Upadhyay wrote:
  >>>>  (In the case of time(1) since it's apparently built into everything
  >>>>  but sh, I guess the time(1) page should be disambiguation. So what do
  >>>>  we call the page for /usr/bin/time? time-bin(1)?)
  >>>
  >>>  I think time(1) manual is fine as-is.
  >>
  >>  Perhaps so; are there any other cases though where the main page
  >>  should be a disambiguation page?
  >>
  >>  (Also, it occurs to me that one would like disambiguation pages to be
  >>  able to reference pages from installed packages. Need to think about
  >>  how one might make that go.)
  >  
  >  What will be the criteria of such ambiguous man pages? I'm thinking it
  >  should be possible to figure out such cases from the database
  >  generated by makemandb(8).
 
 That's only if multiple pages with the same name are installed, which
 (in the set of cases we're talking about, shell builtins) they mostly
 aren't.
 
 Since the namespace of man pages should (in section 1/8) match the
 namespace of commands, mostly there aren't multiple things with the
 same name and when there are, one supersedes the other and the hidden
 one should just disappear. The latter should follow from $PATH or
 $MANPATH and not need to be handled explicitly. Shell builtins can't
 be done this way because they don't appear in the filesystem
 namespace.
 
 I suppose in an ideal world if you (for example) install openssl in
 pkgsrc you ought to be able to get the man page explicitly from either
 the base or the pkgsrc version by doing something like "man
 /usr/pkg/bin/openssl", but we (and unix in general) are a long way
 from that being particularly viable.
 
 A different question is if you do "man printf" whether you should get
 a disambiguation page that points to both printf(1) and printf(3) --
 that is, the same name in different namespaces. For the time being at
 least I think this is probably not a good idea; without the ability to
 directly follow crossreferences it's probably less useful to get that
 page than to get printf(1) when you wanted printf(3). (Which for me
 seems to be the usual case...)
 
 -- 
 David A. Holland
 dholland%netbsd.org@localhost