From garys@opusnet.com  Wed Aug 17 23:41:08 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id C01C016A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 17 Aug 2005 23:41:08 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 6889043D46
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 17 Aug 2005 23:41:08 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id AB129AC30032; Wed, 17 Aug 2005 16:41:06 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j7HNg4YV076925
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 17 Aug 2005 16:42:04 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j7HNfxk0076924;
	Wed, 17 Aug 2005 16:41:59 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <30ll30t9ko.l30@mail.opusnet.com>
Date: Wed, 17 Aug 2005 16:41:59 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: [patch] builtin(1) manpage Aug'05 cleanup
X-GNATS-Notify:

>Number:         85065
>Category:       docs
>Synopsis:       [patch] builtin(1) manpage Aug'05 cleanup
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    garys
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Aug 17 23:50:18 GMT 2005
>Closed-Date:    Sat Sep 17 18:12:14 GMT 2005
>Last-Modified:  Sat Sep 17 18:12:14 GMT 2005
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

-- The first "alias" "Yes" should be "No**".

-- "builtin echo command" is not consistent with the  "xxx builtin
command" (or just "xxx builtin") usage of csh(1) and sh(1) manpages.

-- The "pathname" macro (Pa) is twice used where an "interactive
command" macro (Ic) should be used (esp. because they are in a group
of three interactive commands).

-- The "Name" section has "builtin" twice, and no "built-in" for
   the benefit of literate "apropos" users.

-- These builtins are omitted from the Name section and the list:
(   Command       External    csh(1)    sh(1) )

    !             No          No        Yes
    %             No          Yes       No
    .             No          No        Yes
    :             No          Yes       Yes
    @             No          Yes       Yes
    {             No          No        Yes
    }             No          No        Yes
    local         No          No        Yes
    return        No          No        Yes

(They also don't have manpage hard links,
but they don't need them, IMO.)

-- The list is missing the Command "command" from its line.

>How-To-Repeat:
>Fix:

--- builtin..orig.1	Tue Aug  9 10:26:04 2005
+++ builtin.1	Tue Aug  9 14:53:19 2005
@@ -31,6 +31,13 @@
 .Os
 .Sh NAME
 .Nm builtin ,
+.Nm \&! ,
+.Nm \&% ,
+.Nm \&. ,
+.Nm \&: ,
+.Nm \&@ ,
+.Nm \&{ ,
+.Nm \&} ,
 .Nm alias ,
 .Nm alloc ,
 .Nm bg ,
@@ -80,6 +87,7 @@
 .Nm jobs ,
 .Nm kill ,
 .Nm limit ,
+.Nm local ,
 .Nm log ,
 .Nm login ,
 .Nm logout ,
@@ -96,6 +104,7 @@
 .Nm readonly ,
 .Nm rehash ,
 .Nm repeat ,
+.Nm return ,
 .Nm sched ,
 .Nm set ,
 .Nm setenv ,
@@ -127,7 +136,7 @@
 .Nm where ,
 .Nm which ,
 .Nm while
-.Nd shell builtin commands
+.Nd shell built-in commands
 .Sh SYNOPSIS
 .Nm
 .Op Fl options
@@ -147,11 +156,12 @@
 Thus, while specifying
 .Dq Ic echo
 causes a builtin command to be executed under shells that support the
-builtin echo command,
+.Nm echo
+builtin command,
 specifying
-.Dq Pa /bin/echo
+.Dq Ic /bin/echo
 or
-.Dq Pa ./echo
+.Dq Ic ./echo
 does not.
 .Pp
 While some builtin commands may exist in more than one shell, their
@@ -164,22 +174,36 @@
 and
 .Xr sh 1
 shells are listed here.
+Consult a shell's manual page for
+details on the operation its builtin commands.
+Beware that the
+.Xr sh 1
+manual page, at least, calls some of these commands
+.Dq built-in commands
+and some of them
+.Dq reserved words .
+Users of other shells may need to consult an
+.Xr info 1
+page or other sources of documentation.
+.Pp
 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 Yes Ta Yes Ta Yes
+.It Ic ! Ta \&No Ta \&No Ta \&Yes
+.It Ic % Ta \&No Ta Yes Ta \&No
+.It Ic . Ta \&No Ta \&No Ta Yes
+.It Ic : Ta \&No Ta Yes Ta Yes
+.It Ic @ Ta \&No Ta Yes Ta Yes
+.It Ic { Ta \&No Ta \&No Ta \&Yes
+.It Ic } Ta \&No Ta \&No Ta \&Yes
+.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 bind Ta \&No Ta \&No Ta Yes
@@ -191,7 +215,7 @@
 .It Ic case 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 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
@@ -229,6 +253,7 @@
 .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 local Ta \&No Ta \&No Ta Yes
 .It Ic log Ta \&No Ta Yes Ta \&No
 .It Ic login Ta Yes Ta Yes Ta \&No
 .It Ic logout Ta \&No Ta Yes Ta \&No
@@ -245,6 +270,7 @@
 .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
+.It Ic return Ta \&No Ta \&No Ta Yes
 .It Ic sched Ta \&No Ta Yes Ta \&No
 .It Ic set Ta \&No Ta Yes Ta \&Yes
 .It Ic setenv Ta \&No Ta Yes Ta \&No
>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->analyzed 
State-Changed-By: garys 
State-Changed-When: Wed Aug 31 23:52:38 GMT 2005 
State-Changed-Why:  
Patch is ready for discussion with mentor. 


Responsible-Changed-From-To: freebsd-doc->garys 
Responsible-Changed-By: garys 
Responsible-Changed-When: Wed Aug 31 23:52:38 GMT 2005 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=85065 
State-Changed-From-To: analyzed->patched 
State-Changed-By: garys 
State-Changed-When: Fri Sep 9 17:02:33 GMT 2005 
State-Changed-Why:  
Patched HEAD. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=85065 
State-Changed-From-To: patched->closed 
State-Changed-By: garys 
State-Changed-When: Sat Sep 17 18:11:25 GMT 2005 
State-Changed-Why:  
MFC'd to RELENG_6 and RELENG_5. 

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