docs/85065: [patch] builtin(1) manpage Aug'05 cleanup

[Gary W. Swearingen]

>Number:         85065
>Category:       docs
>Synopsis:       [patch] builtin(1) manpage Aug'05 cleanup
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Aug 17 23:50:18 GMT 2005
>Closed-Date:
>Last-Modified:
>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:
>Unformatted: