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:
(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.