From swear@attbi.com  Thu Jan 30 13:21:45 2003
Return-Path: <swear@attbi.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 795F037B401
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 30 Jan 2003 13:21:45 -0800 (PST)
Received: from sccrmhc03.attbi.com (sccrmhc03.attbi.com [204.127.202.63])
	by mx1.FreeBSD.org (Postfix) with ESMTP id A74AB43F3F
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 30 Jan 2003 13:21:44 -0800 (PST)
	(envelope-from swear@attbi.com)
Received: from localhost.localdomain (<unknown.domain>[12.242.158.67])
          by sccrmhc03.attbi.com (sccrmhc03) with ESMTP
          id <2003013021214300300jidufe>; Thu, 30 Jan 2003 21:21:43 +0000
Received: from localhost.localdomain (localhost [127.0.0.1])
	by localhost.localdomain (8.12.6/8.12.5) with ESMTP id h0ULLH5F005872
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 30 Jan 2003 13:21:17 -0800 (PST)
	(envelope-from swear@attbi.com)
Received: (from jojo@localhost)
	by localhost.localdomain (8.12.6/8.12.5/Submit) id h0ULLCYR005869;
	Thu, 30 Jan 2003 13:21:12 -0800 (PST)
	(envelope-from swear@attbi.com)
Message-Id: <06vg06ibaw.g06@localhost.localdomain>
Date: 30 Jan 2003 13:21:11 -0800
From: "Gary W. Swearingen" <swear@attbi.com>
Reply-To: swear@attbi.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: builtin(1) manpage is wrong about external commands
X-GNATS-Notify:

>Number:         47690
>Category:       docs
>Synopsis:       builtin(1) manpage is wrong about external commands
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jan 30 13:30:00 PST 2003
>Closed-Date:    Wed Feb 23 22:38:17 GMT 2005
>Last-Modified:  Wed Feb 23 22:38:17 GMT 2005
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.7-STABLE i386
>Organization:
none
>Environment:
n/a
================
>Description:

1) The builtin(1) manpage lists several commands as not being external,
while they exist in /usr/bin/.

2) These builtins are not listed, nor do they have manpage links:
    .
    :
    @
    bind
    builtin

3) "builtin echo command" is not in keeping with the usage of "xxx
builtin command" of the "csh" and "sh" manpages.  (The latter two differ
in their hyphenation, but that's for a PR I probably won't write.)

4) The paragraph before the list could use some work.
================
>How-To-Repeat:
n/a
================
>Fix:

Apply patches for
    $FreeBSD: src/share/man/man1/Makefile,v 1.12.2.5 2001/04/25 11:11:29 ru Exp $
    $FreeBSD: src/share/man/man1/builtin.1,v 1.5.2.11 2001/12/15 10:05:19 knu Exp $

--- /usr/src/share/man/man1/Makefile..orig	Thu Jan 30 12:37:47 2003
+++ /usr/src/share/man/man1/Makefile	        Thu Jan 30 12:56:29 2003
@@ -3,9 +3,11 @@
 
 MAN=	builtin.1 intro.1
 
-# Create MLINKS for Shell built in commands for which there are no userland
-# utilities of the same name:
-MLINKS=	builtin.1 alias.1 builtin.1 alloc.1 builtin.1 bg.1 builtin.1 bindkey.1 \
+# Create MLINKS for shell built-in commands for which there are no userland
+# utilities of the same name which have their own manpages:
+MLINKS=	builtin.1 '..1' builtin.1 ':.1' builtin.1 '@.1' \
+	builtin.1 alias.1 builtin.1 alloc.1 builtin.1 bg.1 \
+	builtin.1 bind.1 builtin.1 bindkey.1 \
 	builtin.1 break.1 builtin.1 breaksw.1 builtin.1 builtins.1 \
 	builtin.1 case.1 builtin.1 cd.1 builtin.1 chdir.1 builtin.1 command.1 \
 	builtin.1 complete.1 \

--- /usr/src/share/man/man1/builtin..orig.1	Thu Jan 30 11:34:45 2003
+++ /usr/src/share/man/man1/builtin.1	        Thu Jan 30 13:06:23 2003
@@ -31,9 +31,13 @@
 .Os
 .Sh NAME
 .Nm builtin ,
+.Dq Nm \&. ,
+.Dq Nm \&: ,
+.Dq Nm \&@ ,
 .Nm alias ,
 .Nm alloc ,
 .Nm bg ,
+.Nm bind ,
 .Nm bindkey ,
 .Nm break ,
 .Nm breaksw ,
@@ -147,7 +151,7 @@
 Thus, while specifying
 .Dq Ic echo
 causes a builtin command to be executed under shells that support the
-builtin echo command,
+echo builtin command,
 specifying
 .Dq Pa /bin/echo
 or
@@ -164,25 +168,37 @@
 and
 .Xr sh 1
 shells are listed here.
-Consult the appropriate manual page for
-details on the operation of any given builtin command under those shells.
-Users of other shells will need to consult the documentation supplied
-with the other shells.
+Commands marked
+.Dq Li No**
+under
+.Em External
+do exist externally,
+but are implemented as scripts using a builtin command of the same name.
+Consult a shell's manual page for
+details on the operation its builtin commands.
+Users of other shells may need to consult an
+.Xr info 1
+page or other sources of documentation.
 .Bl -column ".Ic uncomplete" ".Em External" ".Xr csh 1" ".Xr sh 1" -offset indent
 .It Xo
 .Em "Command	External" Ta Xr csh 1 Ta Xr sh 1
 .Xc
-.It Ic alias Ta \&No Ta Yes Ta Yes
+.It Ic \&. Ta \&No Ta \&No Ta Yes
+.It Ic \&: Ta \&No Ta Yes Ta Yes
+.It Ic \&@ Ta \&No Ta Yes Ta \&No
+.It Ic alias Ta \&No** Ta Yes Ta Yes
 .It Ic alloc Ta \&No Ta Yes Ta \&No
-.It Ic bg Ta \&No Ta Yes Ta Yes
+.It Ic bg Ta \&No** Ta Yes Ta Yes
+.It Ic bind Ta \&No Ta \&No Ta Yes
 .It Ic bindkey Ta \&No Ta Yes Ta \&No
 .It Ic break Ta \&No Ta Yes Ta \&Yes
 .It Ic breaksw Ta \&No Ta Yes Ta \&No
+.It Ic builtin Ta \&No Ta \&No Ta Yes
 .It Ic builtins Ta \&No Ta Yes Ta \&No
 .It Ic case Ta \&No Ta Yes Ta Yes
-.It Ic cd Ta \&No Ta Yes Ta Yes
+.It Ic cd Ta \&No** Ta Yes Ta Yes
 .It Ic chdir Ta \&No Ta Yes Ta \&Yes
-.It Ic command Ta \&No Ta \&No Ta Yes
+.It Ic command Ta \&No** Ta \&No Ta Yes
 .It Ic complete Ta \&No Ta Yes Ta \&No
 .It Ic continue Ta \&No Ta Yes Ta \&Yes
 .It Ic default Ta \&No Ta Yes Ta \&No
@@ -202,13 +218,13 @@
 .It Ic exit Ta \&No Ta Yes Ta Yes
 .It Ic export Ta \&No Ta \&No Ta Yes
 .It Ic false Ta Yes Ta \&No Ta Yes
-.It Ic fc Ta \&No Ta \&No Ta Yes
-.It Ic fg Ta \&No Ta Yes Ta Yes
+.It Ic fc Ta \&No** Ta \&No Ta Yes
+.It Ic fg Ta \&No** Ta Yes Ta Yes
 .It Ic filetest Ta \&No Ta Yes Ta \&No
 .It Ic fi Ta \&No Ta \&No Ta Yes
 .It Ic for Ta \&No Ta \&No Ta Yes
 .It Ic foreach Ta \&No Ta Yes Ta \&No
-.It Ic getopts Ta \&No Ta \&No Ta Yes
+.It Ic getopts Ta \&No** Ta \&No Ta Yes
 .It Ic glob Ta \&No Ta Yes Ta \&No
 .It Ic goto Ta \&No Ta Yes Ta \&No
 .It Ic hash Ta \&No Ta \&No Ta Yes
@@ -217,7 +233,7 @@
 .It Ic hup Ta \&No Ta Yes Ta \&No
 .It Ic if Ta \&No Ta Yes Ta \&Yes
 .It Ic jobid Ta \&No Ta \&No Ta Yes
-.It Ic jobs Ta \&No Ta Yes Ta Yes
+.It Ic jobs Ta \&No** Ta Yes Ta Yes
 .It Ic kill Ta Yes Ta Yes Ta \&No
 .It Ic limit Ta \&No Ta Yes Ta \&No
 .It Ic log Ta \&No Ta Yes Ta \&No
@@ -233,7 +249,7 @@
 .It Ic printf Ta Yes Ta \&No Ta Yes
 .It Ic pushd Ta \&No Ta Yes Ta \&No
 .It Ic pwd Ta Yes Ta \&No Ta Yes
-.It Ic read Ta \&No Ta \&No Ta Yes
+.It Ic read Ta \&No** Ta \&No Ta Yes
 .It Ic readonly Ta \&No Ta \&No Ta Yes
 .It Ic rehash Ta \&No Ta Yes Ta \&No
 .It Ic repeat Ta \&No Ta Yes Ta \&No
@@ -256,15 +272,15 @@
 .It Ic true Ta Yes Ta \&No Ta Yes
 .It Ic type Ta \&No Ta \&No Ta Yes
 .It Ic ulimit Ta \&No Ta \&No Ta Yes
-.It Ic umask Ta \&No Ta Yes Ta Yes
-.It Ic unalias Ta \&No Ta Yes Ta Yes
+.It Ic umask Ta \&No** Ta Yes Ta Yes
+.It Ic unalias Ta \&No** Ta Yes Ta Yes
 .It Ic uncomplete Ta \&No Ta Yes Ta \&No
 .It Ic unhash Ta \&No Ta Yes Ta \&No
 .It Ic unlimit Ta \&No Ta Yes Ta \&No
 .It Ic unset Ta \&No Ta Yes Ta Yes
 .It Ic unsetenv Ta \&No Ta Yes Ta \&No
 .It Ic until Ta \&No Ta \&No Ta Yes
-.It Ic wait Ta \&No Ta Yes Ta Yes
+.It Ic wait Ta \&No** Ta Yes Ta Yes
 .It Ic where Ta \&No Ta Yes Ta \&No
 .It Ic which Ta Yes Ta Yes Ta \&No
 .It Ic while Ta \&No Ta Yes Ta \&Yes
@@ -273,6 +289,7 @@
 .Xr csh 1 ,
 .Xr echo 1 ,
 .Xr false 1 ,
+.Xr info 1 ,
 .Xr kill 1 ,
 .Xr login 1 ,
 .Xr nice 1 ,
>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Wed Feb 23 07:12:07 GMT 2005 
State-Changed-Why:  
Patch was out of date but updated and mostly merged.  Thanks! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Wed Feb 23 07:12:07 GMT 2005 
Responsible-Changed-Why:  
Over to me, MFC pending. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=47690 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Wed Feb 23 22:37:56 GMT 2005 
State-Changed-Why:  
MFC complete, switch to closed. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=47690 
>Unformatted:
