NetBSD Problem Report #37981

From Ephaeton@gmx.net  Fri Feb  8 12:46:37 2008
Return-Path: <Ephaeton@gmx.net>
Received: from mail.netbsd.org (mail.netbsd.org [204.152.190.11])
	by narn.NetBSD.org (Postfix) with ESMTP id 5CF9863B853
	for <gnats-bugs@gnats.NetBSD.org>; Fri,  8 Feb 2008 12:46:37 +0000 (UTC)
Message-Id: <20080208124633.B8E5DD754@circe.entropie.net>
Date: Fri,  8 Feb 2008 13:46:33 +0100 (CET)
From: Ephaeton@gmx.net
Reply-To: Ephaeton@gmx.net
To: gnats-bugs@gnats.NetBSD.org
Subject: shell builtin manpages are for csh(1) only...
X-Send-Pr-Version: 3.95

>Number:         37981
>Category:       misc
>Synopsis:       shell builtin manpages are for csh(1) only...
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    misc-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Feb 08 12:50:00 +0000 2008
>Last-Modified:  Sun Jul 31 21:20:00 +0000 2016
>Originator:     Martin S. Weber
>Release:        NetBSD 4.99.52
>Organization:

>Environment:


System: NetBSD circe.entropie.net 4.99.52 NetBSD 4.99.52 (GENERIC) #0: Mon Feb 4 13:19:18 CET 2008 root@circe.entropie.net:/src/obj/sys/arch/i386/compile/GENERIC i386
Architecture: i386
Machine: i386
>Description:

	Shell builtins of the C Shell exist as their own manpages -- at least linking
	the name of the builtin to the C shell manpage. I can understand the historical
	and cultural background of BSD and csh, yet still we do ship with alternative
	shells, among them two bourne shells (sh, ksh).

	It's confusing to users of the latter shells (and actually I'm writing this
	after being asked by a user) to see shell builtins valid for their own
	shell (in this case "alias" for a ksh user) map into manpages of a foreign
	shell.

	Given that on a multi-user system there's no easy way to map virtual manpages
	for all the builtins of the current running shell into the manpage of this
	very shell, I suggest to simply remove the list of linked manpages, or replace
	them by a comment like (e.g. alias):

	"Alias is a shell builtin. SEE ALSO: csh(1), sh(1), ksh(1)" .. or the like.

>How-To-Repeat:

	 $ find . -inum $(stat -f %i csh.1)
	 ./bg.1
	 ./limit.1
	 ./csh.1
	 ./alias.1
	 ./dirs.1
	 ./fg.1
	 ./foreach.1
	 ./history.1
	 ./jobs.1
	 ./popd.1
	 ./pushd.1
	 ./rehash.1
	 ./repeat.1
	 ./suspend.1
	 ./stop.1
	 ./source.1

	 $ man alias ;# --> see manpage of csh

>Fix:
	- remove links on csh.1
	- maybe replace by stub manpages as sketched out above


>Audit-Trail:
From: "Jeremy C. Reed" <reed@reedmedia.net>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Fri, 8 Feb 2008 08:57:15 -0600 (CST)

 On Fri, 8 Feb 2008, Ephaeton@gmx.net wrote:

 > 	 $ find . -inum $(stat -f %i csh.1)
 > 	 ./bg.1
 > 	 ./limit.1
 > 	 ./csh.1
 > 	 ./alias.1
 > 	 ./dirs.1
 > 	 ./fg.1
 > 	 ./foreach.1
 > 	 ./history.1
 > 	 ./jobs.1
 > 	 ./popd.1
 > 	 ./pushd.1
 > 	 ./rehash.1
 > 	 ./repeat.1
 > 	 ./suspend.1
 > 	 ./stop.1
 > 	 ./source.1
 > 
 > 	 $ man alias ;# --> see manpage of csh
 > 
 > >Fix:
 > 	- remove links on csh.1

 Maybe keep csh-specific links, like limit.1, dirs.1, foreach.1, popd.1, 
 pushd.1, rehash.1, repeat.1, and source.1.

 Also history.1 and suspend.1 and stop.1 are csh, but there are aliases for 
 these for other shell(s).

 But then it could still be confusing for add-on shells (like bash).

 > 	- maybe replace by stub manpages as sketched out above

 Maybe instead of several just have them link to one.

 Some systems have a "builtins.1" man page.

 But from your list above, I only see four builtin commands that are 
 generic:

 alias
 bg
 fg
 jobs

 Unless you want to also add:
 history.1
 suspend.1
 stop.1 

 Also a generic "builtins" page could mention echo, kill, time (not in sh 
 though) -- but no symlinks for those manpages.

 Another is cd.1 -- its not a link. But it only mentions csh.

 And where to stop? What about other common shell builtins like the 
 following?

 eval
 exec
 set
 umask
 wait

 (Should they be in the "builtins" man page too?)


 I'll work on this if anyone wants to pursue this.


   Jeremy C. Reed

From: David Holland <dholland-bugs@netbsd.org>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Sat, 9 Feb 2008 22:54:18 +0000

 On Fri, Feb 08, 2008 at 12:50:00PM +0000, Ephaeton@gmx.net wrote:
  > Shell builtins of the C Shell exist as their own manpages -- at
  > least linking the name of the builtin to the C shell manpage. I can
  > understand the historical and cultural background of BSD and csh,
  > yet still we do ship with alternative shells, among them two bourne
  > shells (sh, ksh).
  >
  > It's confusing to users of the latter shells (and actually I'm
  > writing this after being asked by a user) to see shell builtins
  > valid for their own shell (in this case "alias" for a ksh user) map
  > into manpages of a foreign shell.

 It is also confusing for users, particularly novices who may not
 understand the idea of different shells yet, to get nothing at all
 back when they type "man alias". So simply removing the links is not a
 solution.

 It is probably a good idea to have stub pages that point to the proper
 documentation for each shell, plus crossreferences for the same
 functionality in other shells (e.g. csh limit <-> sh ulimit).

 There should also be somewhere an explanation for why builtins are
 builtin and how the per-process state they affect is propagated; this
 stuff is not obvious to beginners, and if there's a good writeup of it
 already in the man pages I dunno where. Probably it should be
 addressed in intro(1), if only by pointing somewhere else.

 -- 
 David A. Holland
 dholland@netbsd.org

From: "Greg A. Woods" <woods@planix.com>
To: NetBSD GNATS <gnats-bugs@NetBSD.org>
Cc: 
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Fri, 11 Apr 2008 08:07:53 -0400

 At Fri,  8 Feb 2008 12:50:00 +0000 (UTC), Ephaeton@gmx.net wrote:
 Subject: misc/37981: shell builtin manpages are for csh(1) only...
 > 

 This particular subject has bothered me for many years now too!

 > 	Given that on a multi-user system there's no easy way to map virtual manpages
 > 	for all the builtins of the current running shell into the manpage of this
 > 	very shell, I suggest to simply remove the list of linked manpages, or replace
 > 	them by a comment like (e.g. alias):

 Well actually if one assumes $SHELL is set to the user's current shell
 then the likes of man(1) could do the same kind of referencing for
 shell-specific manual pages as it does for the system architecture type,
 i.e. they would be in shell-named sub-directories in the man-page
 documentation directories.  It's not perfect, but it's _way_ better than
 what we have now.

 Personally I think the POSIX standard commands do need to be documented
 with their own separate manual pages regardless of what shell the user
 is using at the moment.

 For certain I think the csh(1)-specific manual pages need to be removed.
 (personally I remove all trace of csh from all of my own sytems :-))

 Alternately it might be helpful if the built-in command manual pages
 were named with their shell name as a prefix, then at least apropos(1)
 would find them, eg:

 	sh-alias(1)
 	csh-alias(1)
 	ksh-alias(1)


 I think it would also help if all the built-in command provided more
 useful output when given the "-?" option.  The usage and help
 information provided should also reference the appropriate manual page
 too.  Eg.:

 	$ alias -?
 	Usage: alias [-ptx] [name=[value]...]
 	See also ksh(1)

 or

 	% alias -?
 	Usage: alias [name [value]...]
 	See also csh(1)

 -- 
 						Greg A. Woods
 						Planix, Inc.

 <woods@planix.com>     +1 416 489-5852 x122     http://www.planix.com/

From: David Holland <dholland-bugs@netbsd.org>
To: gnats-bugs@netbsd.org
Cc: 
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Sun, 12 Jun 2016 02:48:27 +0000

 On Sat, Feb 09, 2008 at 10:55:05PM +0000, David Holland wrote:
  >  It is probably a good idea to have stub pages that point to the proper
  >  documentation for each shell, plus crossreferences for the same
  >  functionality in other shells (e.g. csh limit <-> sh ulimit).

 On Fri, Apr 11, 2008 at 12:10:03PM +0000, Greg A. Woods wrote:
  >  [...]
  >  Alternately it might be helpful if the built-in command manual pages
  >  were named with their shell name as a prefix, then at least apropos(1)
  >  would find them, eg:
  >  
  >  	sh-alias(1)
  >  	csh-alias(1)
  >  	ksh-alias(1)

 Fast-forward eight years and it's pretty clear that the right way to
 do this is with disambiguation pages like Wikipedia uses.

 So alias(1) should point to sh-alias(1), csh-alias(1), and
 ksh-alias(1), and probably also to a shell(7) or thereabouts that
 explains what different shells are about.

 In the case of things like time(1) that are both standalone programs
 and common builtins I'm not sure if the main page should be the
 disambiguation page or document the binary and link to something like
 time-disambig(1). I guess probably it should depend on how likely the
 user is to be looking for docs on a builtin, which means doing an
 assessment of which shells have which builtins and how popular those
 shells are.

 (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)?)

 -- 
 David A. Holland
 dholland@netbsd.org

From: "Jeremy C. Reed" <reed@reedmedia.net>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Mon, 13 Jun 2016 19:54:09 -0500 (CDT)

 On Sun, 12 Jun 2016, David Holland 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.

From: David Holland <dholland-bugs@netbsd.org>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Sun, 26 Jun 2016 05:07:19 +0000

 On Tue, Jun 14, 2016 at 12:55:01AM +0000, Jeremy C. Reed 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.)

 -- 
 David A. Holland
 dholland@netbsd.org

From: Abhinav Upadhyay <er.abhinav.upadhyay@gmail.com>
To: NetBSD GNATS <gnats-bugs@netbsd.org>
Cc: misc-bug-people@netbsd.org, gnats-admin@netbsd.org, netbsd-bugs@netbsd.org, 
	Ephaeton@gmx.net
Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
Date: Wed, 29 Jun 2016 02:45:35 +0530

 On Sun, Jun 26, 2016 at 10:40 AM, David Holland
 <dholland-bugs@netbsd.org> wrote:
 > The following reply was made to PR misc/37981; it has been noted by GNATS.
 >
 > From: David Holland <dholland-bugs@netbsd.org>
 > To: gnats-bugs@NetBSD.org
 > Cc:
 > Subject: Re: misc/37981: shell builtin manpages are for csh(1) only...
 > Date: Sun, 26 Jun 2016 05:07:19 +0000
 >
 >  On Tue, Jun 14, 2016 at 12:55:01AM +0000, Jeremy C. Reed 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).
 -
 Abhinav

From: David Holland <dholland-bugs@netbsd.org>
To: gnats-bugs@NetBSD.org
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

>Unformatted:

NetBSD Home
NetBSD PR Database Search

(Contact us) $NetBSD: query-full-pr,v 1.39 2013/11/01 18:47:49 spz Exp $
$NetBSD: gnats_config.sh,v 1.8 2006/05/07 09:23:38 tsutsui Exp $
Copyright © 1994-2014 The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.