Improve shell documentation:

* Consistently misspell built-in as builtin.

* Add a builtin(1) manpage and create builtin(1) MLINKS for all shell
  builtin commands for which no standalone utility exists.  These MLINKS
  replace those that were created for csh(1).

* Add appropriate xrefs for builtin(1) to the csh(1) and sh(1) manpages,
  as well as to the manpages of standalone utilities which are supported
  as shell builtin commands in at least one of the shells. In such
  manpages, explain that similar functionality may be provided as a
  shell builtin command.

* Improve sh(1)'s description of the cd builtin command. Csh(1) already
  describes it adequately. Replace the cd(1) manpage with a builtin(1)
  MLINKS link.

* Clean up some mdoc problems: use Xr instead of literal "foo(n)"; use
  Ic instead of Xr for shell builtin commands.

* Undo English contractions.

Reviewed by:	mpp, rgrimes

7 files changed, 91 insertions, 52 deletions

diff --git a/bin/csh/Makefile b/bin/csh/Makefile
index cd05e53..3ebbb1e 100644
--- a/bin/csh/Makefile
+++ b/bin/csh/Makefile
@@ -15,10 +15,10 @@ SRCS=	alloc.c char.c const.c csh.c dir.c dol.c err.c exec.c exp.c file.c \
 .PATH:	${.CURDIR}/../../usr.bin/printf
 
 MAN1=	csh.1
-MLINKS=	csh.1 limit.1 csh.1 alias.1 csh.1 bg.1 csh.1 dirs.1 csh.1 fg.1 \
-	csh.1 foreach.1 csh.1 history.1 csh.1 jobs.1 csh.1 popd.1 \
-	csh.1 pushd.1 csh.1 rehash.1 csh.1 repeat.1 csh.1 suspend.1 \
-	csh.1 stop.1 csh.1 source.1
+# MLINKS for Shell built in commands for which there are no userland
+# utilities of the same name are handled with the associated manpage,
+# builtin.1 in share/man/man1/.
+
 CLEANFILES+=const.h errnum.h
 
 const.h: errnum.h
diff --git a/bin/csh/csh.1 b/bin/csh/csh.1
index af0fc3e..a6f1dd0 100644
--- a/bin/csh/csh.1
+++ b/bin/csh/csh.1
@@ -322,7 +322,9 @@ be set. It is an artifact from a
 implementation
 of the
 tty driver that allows generation of interrupt characters from
-the keyboard to tell jobs to stop.  See stty(1) for details
+the keyboard to tell jobs to stop.  See
+.Xr stty 1
+for details
 on setting options in the new tty driver.
 .Ss Status reporting
 This shell learns immediately whenever a process changes state.
@@ -1487,7 +1489,7 @@ entry in the stack.
 The members of the directory stack are numbered from the top starting at 0.
 .Pp
 .It Ic printf Ar format-string values
-Invokes a built-in version of 
+Invokes a builtin version of 
 .Ic printf 
 after evaluating the 
 .Ar format-string 
@@ -2134,9 +2136,17 @@ To detect looping, the shell restricts the number of
 .Ic alias
 substitutions on a single line to 20.
 .Sh SEE ALSO
+.Xr builtin 1 ,
+.Xr echo 1 ,
+.Xr kill 1 ,
+.Xr login 1 ,
+.Xr nice 1 ,
+.Xr nohup 1 ,
 .Xr printf 1 ,
 .Xr sh 1 ,
 .Xr su 1 ,
+.Xr time 1 ,
+.Xr which 1 ,
 .Xr access 2 ,
 .Xr execve 2 ,
 .Xr fork 2 ,
@@ -2194,7 +2204,7 @@ shell procedures should be provided instead of aliases.
 Commands within loops, prompted for by `?', are not placed on the
 .Ic history
 list.
-Control structure should be parsed instead of being recognized as built-in
+Control structure should be parsed instead of being recognized as builtin
 commands.  This would allow control commands to be placed anywhere,
 to be combined with `\&|', and to be used with `&' and `;' metasyntax.
 .Pp
diff --git a/bin/echo/echo.1 b/bin/echo/echo.1
index 1636b7d..515cff0 100644
--- a/bin/echo/echo.1
+++ b/bin/echo/echo.1
@@ -59,12 +59,22 @@ Do not print the trailing newline character.  This may also be
 achieved by appending `\ec' to the end of the string, as is done
 by iBCS2 compatible systems.
 .El
+.Pp
+Some shells may provide a builtin
+.Nm
+command which is similar or identical to this utility. Consult
+the
+.Xr builtin 1
+manual page.
 .Sh DIAGNOSTICS
 The
 .Nm
 utility exits 0 on success, and >0 if an error occurs.
 .Sh SEE ALSO
-.Xr printf 1
+.Xr builtin 1 ,
+.Xr csh 1 ,
+.Xr printf 1 ,
+.Xr sh 1
 .Sh STANDARDS
 The
 .Nm
diff --git a/bin/kill/kill.1 b/bin/kill/kill.1
index 3264f31..67c2424 100644
--- a/bin/kill/kill.1
+++ b/bin/kill/kill.1
@@ -110,17 +110,14 @@ ALRM (alarm clock)
 TERM (software termination signal)
 .El
 .Pp
-.Nm Kill
-is a built-in to
-.Xr csh  1  ;
-it allows job specifiers of the form ``%...'' as arguments
-so process id's are not as often used as
+Some shells may provide a builtin
 .Nm
-arguments.
-See
-.Xr csh 1
-for details.
+command which is similar or identical to this utility. Consult
+the
+.Xr builtin 1
+manual page.
 .Sh SEE ALSO
+.Xr builtin 1 ,
 .Xr csh 1 ,
 .Xr killall 1 ,
 .Xr ps 1 ,
diff --git a/bin/pwd/pwd.1 b/bin/pwd/pwd.1
index 27150e6..4eaed1d 100644
--- a/bin/pwd/pwd.1
+++ b/bin/pwd/pwd.1
@@ -47,6 +47,13 @@
 .Nm Pwd
 writes the absolute pathname of the current working directory to
 the standard output.
+.Pp
+Some shells may provide a builtin
+.Nm
+command which is similar or identical to this utility. Consult
+the
+.Xr builtin 1
+manual page.
 .Sh DIAGNOSTICS
 The
 .Nm
@@ -58,14 +65,17 @@ utility is expected to be
 .St -p1003.2
 compatible.
 .Sh SEE ALSO
+.Xr builtin 1 ,
 .Xr cd 1 ,
 .Xr csh 1 ,
-.Xr getcwd 3
+.Xr getcwd 3 ,
+.Xr sh 1
 .Sh BUGS
 In
 .Xr csh  1
 the command
 .Ic dirs
-is always faster (although it can give a different answer in the rare case
+is always faster because it is built into that shell. However,
+it can give a different answer in the rare case
 that the current directory or a containing directory was moved after
-the shell descended into it).
+the shell descended into it.
diff --git a/bin/sh/Makefile b/bin/sh/Makefile
index 1a88934..01c46f5 100644
--- a/bin/sh/Makefile
+++ b/bin/sh/Makefile
@@ -10,6 +10,10 @@ GENSRCS= builtins.c init.c nodes.c syntax.c
 GENHDRS= builtins.h nodes.h syntax.h token.h y.tab.h
 SRCS= ${SHSRCS} ${GENSRCS} ${GENHDRS} y.tab.h
 
+# MLINKS for Shell built in commands for which there are no userland
+# utilities of the same name are handled with the associated manpage,
+# builtin.1 in share/man/man1/.  
+
 DPADD+= ${LIBL} ${LIBEDIT} ${LIBTERMCAP}
 LDADD+= -ll -ledit -ltermcap
 
diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
index f104471..a72b289 100644
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -68,11 +68,13 @@ The shell is a command that reads lines from
 either a file or the terminal, interprets them, and
 generally executes other commands. It is the program that is running
 when a user logs into the system (although a user can select
-a different shell with the chsh(1) command).
+a different shell with the
+.Xr chsh 1
+command).
 The shell
 implements a language that has flow control constructs,
 a macro facility that provides a variety of features in
-addition to data storage, along with built in history and line
+addition to data storage, along with builtin history and line
 editing capabilities.  It incorporates many features to
 aid interactive use and has the advantage that the interpretative
 language is common to both interactive and non-interactive
@@ -135,8 +137,8 @@ scripts.
 All of the single letter options to
 .Nm
 have a corresponding name that can be used as an argument to the
-.Xr set 1
-builtin (described later).  These names are provided next to the
+.Ic set
+builtin command (described later).  These names are provided next to the
 single letter option in the descriptions below.  Specifying a dash
 .Dq -
 enables the option, while using a plus
@@ -155,11 +157,11 @@ Enable asynchronous notification of background job
 completion.
 .Pq UNIMPLEMENTED
 .It Fl C Li noclobber
-Don't overwrite existing files with
+Do not overwrite existing files with
 .Dq > .
 .Pq UNIMPLEMENTED
 .It Fl E Li emacs
-Enable the built-in
+Enable the builtin
 .Xr emacs 1
 command line editor (disables
 .Fl V
@@ -206,7 +208,7 @@ Read commands from standard input (set automatically
 if no file arguments are present).  This option has
 no effect when set after the shell has already started
 running (i.e. when set with the
-.Xr set 1
+.Ic set
 command).
 .It Fl T Li asynctraps
 When waiting for a child, execute traps immediately. If this option is
@@ -226,7 +228,7 @@ to expand a variable that is not set, and if the
 shell is not interactive, exit immediately.
 .Pq UNIMPLEMENTED
 .It Fl V Li vi
-Enable the built-in
+Enable the builtin
 .Xr vi 1
 command line editor (disables
 .Fl E
@@ -297,7 +299,7 @@ for     if      then    until   while
 .Ed
 .Ss Aliases
 An alias is a name and corresponding value set using the
-.Xr alias 1
+.Ic alias
 builtin command.  Whenever a reserved word may occur (see above),
 and after checking for reserved words, the shell
 checks the word to see if it matches an alias. If it does,
@@ -427,11 +429,11 @@ definition is executed.   The positional parameters are
 restored to their original values when the command completes.
 This all occurs within the current shell.
 .Pp
-Shell builtins are executed internally to the shell, without
+Shell builtin commands are executed internally to the shell, without
 spawning a new process.
 .Pp
-Otherwise, if the command name doesn't match a function
-or builtin, the command is searched for as a normal
+Otherwise, if the command name does not match a function
+or builtin command, the command is searched for as a normal
 program in the filesystem (as described in the next section).
 When a normal program is executed, the shell runs the program,
 passing the arguments and the environment to the
@@ -553,7 +555,7 @@ asynchronous execution of the preceding AND-OR-list.
 .Pp
 Note that unlike some other shells, each process in the
 pipeline is a child of the invoking shell (unless it
-is a shell builtin, in which case it executes in the
+is a shell builtin command, in which case it executes in the
 current shell -- but any effect it has on the
 environment is wiped).
 .Ss Background Commands -- &
@@ -740,8 +742,8 @@ or a special character as explained below.
 A positional parameter is a parameter denoted by a number (n > 0).
 The shell sets these initially to the values of its command line
 arguments that follow the name of the shell script.  The
-.Xr set 1
-builtin can also be used to set or reset them.
+.Ic set
+builtin command can also be used to set or reset them.
 .Ss Special Parameters
 A special parameter is a parameter denoted by one of the following
 special characters.  The value of the parameter is listed
@@ -991,7 +993,7 @@ a pattern cannot match a string starting with a period
 unless the first character of the pattern is a period.
 The next section describes the patterns used for both
 Pathname Expansion and the
-.Xr case 1
+.Ic case
 command.
 .Ss Shell Patterns
 A pattern consists of normal characters, which match themselves,
@@ -1037,16 +1039,15 @@ character listed (after the
 .Dq ! ,
 if any).  To include a
 minus sign, make it the first or last character listed.
-.Ss Builtins
-This section lists the builtin commands which
+.Ss Builtin Commands
+This section lists the commands which
 are builtin because they need to perform some operation
-that can't be performed by a separate process.  In addition to
-these, there are several other commands that may be
-builtin for efficiency (e.g.
-.Xr printf 1 ,
-.Xr echo 1 ,
-.Xr test 1 ,
-etc).
+that can not be performed by a separate process.  In addition to
+these, builtin versions of the
+.Xr printf 1
+and
+.Xr echo 1
+commands are provided for efficiency.
 .Bl -tag -width Ds
 .It :
 A null command that returns a 0 (true) exit value.
@@ -1072,7 +1073,7 @@ If just
 is specified, the value of the alias
 .Dq name
 is printed.
-With no arguments, the alias builtin prints the
+With no arguments, the alias builtin command prints the
 names and values of all defined aliases (see unalias).
 .It bg [ job ] ...
 Continue the specified jobs (or the current job if no
@@ -1085,7 +1086,8 @@ as a builtin command.)
 Switch to the specified directory (default $HOME).
 If an entry for CDPATH appears in the environment
 of the cd command or the shell variable CDPATH is set
-and the directory name does not begin with a slash,
+and the directory name does not begin with a slash (/),
+dot (.) or dot-dot (..),
 then the directories listed in CDPATH will be
 searched for the specified directory.  The format of
 CDPATH is the same as that of PATH. In an interactive shell,
@@ -1101,7 +1103,7 @@ command.
 .It exec [ command arg ...  ]
 Unless command is omitted, the shell process is
 replaced with the specified program (which must be a
-real program, not a shell builtin or function).  Any
+real program, not a shell builtin command or function).  Any
 redirections on the exec command are marked as permanent,
 so that they are not undone when the exec command finishes.
 .It exit [ exitstatus ]
@@ -1123,7 +1125,7 @@ of all exported variables.
 .It fc [-e editor] [first [last]]
 .It fc -l [-nr] [first [last]]
 .It fc -s [old=new] [first]
-The fc builtin lists, or edits and re-executes, commands
+The fc builtin command lists, or edits and re-executes, commands
 previously entered to an interactive shell.
 .Bl -tag -width Ds
 .It -e editor
@@ -1297,7 +1299,7 @@ Shift the positional parameters n times.  A shift
 sets the value of $1 to the value of $2, the value of
 $2 to the value of $3, and so on, decreasing the
 value of $# by one.  If there are zero positional
-parameters, shifting doesn't do anything.
+parameters, shifting does not do anything.
 .It trap [ action ] signal ...
 Cause the shell to parse and execute action when any
 of the specified signals are received.  The signals
@@ -1311,7 +1313,7 @@ signals that were ignored on entry to the shell.
 .It type [name] ...
 Interpret each name as a command and print the
 resolution of the command search. Possible resolutions are:
-shell keyword, alias, shell builtin, command, tracked alias
+shell keyword, alias, shell builtin command, command, tracked alias
 and not found.  For aliases the alias expansion is printed;
 for commands and tracked aliases the complete pathname of
 the command is printed.
@@ -1396,7 +1398,9 @@ and the return an exit status of zero.
 When
 .Nm
 is being used interactively from a terminal, the current command
-and the command history (see fc in Builtins) can be edited using vi-mode
+and the command history (see fc in
+.Sx Builtin Commands )
+can be edited using vi-mode
 command line editing.  This mode uses commands similar
 to a subset of those described in the vi man page.
 The command 'set -o vi' enables vi-mode editing and places
@@ -1409,7 +1413,11 @@ Hitting <return> while in command mode will pass the line to the shell.
 Similarly, the 'set -o emacs' command can be used to enable a subset of
 emacs-style command line editing features.
 .Sh SEE ALSO
+.Xr builtin 1 ,
+.Xr echo 1 ,
 .Xr expr 1 ,
+.Xr pwd 1 ,
+.Xr printf 1 ,
 .Xr test 1
 .Sh HISTORY
 A