Add some rudimentary EXAMPLES sections and standardize the way we display

existing EXAMPLES sections.

16 files changed, 176 insertions, 122 deletions

diff --git a/bin/cat/cat.1 b/bin/cat/cat.1
index e20d93b480f..962a591116a 100644
--- a/bin/cat/cat.1
+++ b/bin/cat/cat.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: cat.1,v 1.19 2000/08/05 22:05:52 pjanzen Exp $
+.\"	$OpenBSD: cat.1,v 1.20 2000/10/18 06:55:06 aaron Exp $
 .\"	$NetBSD: cat.1,v 1.12 1995/09/27 05:38:55 cgd Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
@@ -109,21 +109,15 @@ The
 .Nm
 utility exits 0 on success or >0 if an error occurred.
 .Sh EXAMPLES
-The command:
-.Bd -literal -offset indent
-.Ic cat file1
-.Ed
+.Cm cat file1
 .Pp
-will print the contents of
+Print the contents of
 .Ar file1
 to the standard output.
 .Pp
-The command:
-.Bd -literal -offset indent
-.Ic cat file1 file2 > file3
-.Ed
+.Cm cat file1 file2 > file3
 .Pp
-will sequentially print the contents of
+Sequentially print the contents of
 .Ar file1
 and
 .Ar file2
@@ -136,12 +130,9 @@ See the manual page for your shell (i.e.,
 .Xr sh 1 )
 for more information on redirection.
 .Pp
-The command:
-.Bd -literal -offset indent
-.Ic cat file1 - file2 - file3
-.Ed
+.Cm cat file1 - file2 - file3
 .Pp
-will print the contents of
+Print the contents of
 .Ar file1 ,
 print data it receives from the standard input until it receives an
 .Dv EOF
diff --git a/bin/chmod/chmod.1 b/bin/chmod/chmod.1
index b95dac48c59..8811cfcc383 100644
--- a/bin/chmod/chmod.1
+++ b/bin/chmod/chmod.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: chmod.1,v 1.19 2000/07/10 13:30:04 aaron Exp $
+.\"	$OpenBSD: chmod.1,v 1.20 2000/10/18 06:55:07 aaron Exp $
 .\"	$NetBSD: chmod.1,v 1.8 1995/03/21 09:02:07 cgd Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993, 1994
@@ -328,38 +328,38 @@ or
 .Sq t ,
 are ignored.
 .Sh EXAMPLES
-Make a file readable by anyone and writable by the owner only.
+.Cm chmod 644 file
 .Pp
-.Dl Ic  chmod 644 file
+Set file readable by anyone and writable by the owner only.
+.Pp
+.Cm chmod go-w file
 .Pp
 Deny write permission to group and others.
 .Pp
-.Dl Ic chmod go-w file
+.Cm chmod =rw,+X file
 .Pp
 Set the read and write permissions to the usual defaults, but
 retain any execute permissions that are currently set.
 .Pp
-.Dl Ic chmod =rw,+X file
+.Cm chmod +X file
 .Pp
 Make a directory or file searchable/executable by everyone if it is
 already searchable/executable by anyone.
 .Pp
-.Dl Ic chmod +X file
+.Cm chmod 755 file
+.Cm chmod u=rwx,go=rx file
+.Cm chmod u=rwx,go=u-w file
 .Pp
-Any of the following will make a file readable/executable by everyone and
+Any of these commands will make a file readable/executable by everyone and
 writable by the owner only.
 .Pp
-.Dl Ic chmod 755 file
-.Dl Ic chmod u=rwx,go=rx file
-.Dl Ic chmod u=rwx,go=u-w file
+.Cm chmod go= file
 .Pp
 Clear all mode bits for group and others.
 .Pp
-.Dl Ic chmod go= file
+.Cm chmod g=u-w file
 .Pp
 Set the group bits equal to the user bits, but clear the group write bit.
-.Pp
-.Dl Ic chmod g=u-w file
 .Sh SEE ALSO
 .Xr chflags 1 ,
 .Xr chgrp 1 ,
diff --git a/bin/cp/cp.1 b/bin/cp/cp.1
index edf1c332e93..bc8a7b78e50 100644
--- a/bin/cp/cp.1
+++ b/bin/cp/cp.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: cp.1,v 1.15 2000/03/21 14:40:14 aaron Exp $
+.\"	$OpenBSD: cp.1,v 1.16 2000/10/18 06:55:07 aaron Exp $
 .\"	$NetBSD: cp.1,v 1.9 1995/07/25 19:36:45 jtc Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993, 1994
@@ -185,26 +185,26 @@ The
 .Nm
 utility exits 0 on success or >0 if an error occurred.
 .Sh EXAMPLES
+.Cm cp foo bar
+.Pp
 Make a copy of file
 .Pa foo
 named
-.Pa bar :
+.Pa bar .
 .Pp
-.D1 Ic cp foo bar
+.Cm cp *.txt /tmp
 .Pp
 Copy a group of files to the
 .Pa /tmp
-directory:
+directory.
 .Pp
-.D1 Ic cp *.txt /tmp
+.Cm cp -R junk /tmp
 .Pp
 Copy the directory
-.Pa junk ,
+.Pa junk
 and all of its contents (including any subdirectories) to the
 .Pa /tmp
-directory:
-.Pp
-.D1 Ic cp -R junk /tmp
+directory.
 .Sh COMPATIBILITY
 Historic versions of the
 .Nm
diff --git a/bin/date/date.1 b/bin/date/date.1
index ff72ee5018d..36f602f5b38 100644
--- a/bin/date/date.1
+++ b/bin/date/date.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: date.1,v 1.25 2000/04/15 11:45:53 aaron Exp $
+.\"	$OpenBSD: date.1,v 1.26 2000/10/18 06:55:07 aaron Exp $
 .\"	$NetBSD: date.1,v 1.12 1996/03/12 04:32:37 phil Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
@@ -143,31 +143,22 @@ Everything but the minute is optional.
 Time changes for Daylight Saving Time, standard time, leap seconds,
 and leap years are handled automatically.
 .Sh EXAMPLES
-The command:
-.Bd -literal -offset indent
-date "+DATE: %Y-%m-%d%nTIME: %H:%M:%S"
-.Ed
+.Cm date "+DATE: %Y-%m-%d%nTIME: %H:%M:%S"
 .Pp
-will display:
+Displays
 .Bd -literal -offset indent
 DATE: 1987-11-21
 TIME: 13:36:16
 .Ed
 .Pp
-The command:
-.Bd -literal -offset indent
-date 8506131627
-.Ed
+.Cm date 8506131627
 .Pp
-sets the date to
+Sets the date to
 .Dq Li "June 13, 1985, 4:27 PM" .
 .Pp
-The command:
-.Bd -literal -offset indent
-date 1432
-.Ed
+.Cm date 1432
 .Pp
-sets the time to
+Sets the time to
 .Li "2:32 PM" ,
 without modifying the date.
 .Sh ENVIRONMENT
diff --git a/bin/dd/dd.1 b/bin/dd/dd.1
index 72af4b42ad4..9f358137f7b 100644
--- a/bin/dd/dd.1
+++ b/bin/dd/dd.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: dd.1,v 1.10 1999/09/23 10:29:09 aaron Exp $
+.\"	$OpenBSD: dd.1,v 1.11 2000/10/18 06:55:07 aaron Exp $
 .\"	$NetBSD: dd.1,v 1.5 1995/03/21 09:04:04 cgd Exp $
 .\"
 .\" Copyright (c) 1990, 1993
@@ -341,6 +341,12 @@ will exit.
 The
 .Nm
 utility exits 0 on success or >0 if an error occurred.
+.Sh EXAMPLES
+.Cm dd if=floppy28.fs of=/dev/fd0a
+.Pp
+Write an
+.Ox
+floppy image to a floppy disk.
 .Sh SEE ALSO
 .Xr cp 1 ,
 .Xr mt 1 ,
diff --git a/bin/df/df.1 b/bin/df/df.1
index 5e899849575..4faa223e9d4 100644
--- a/bin/df/df.1
+++ b/bin/df/df.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: df.1,v 1.22 2000/03/17 18:15:12 aaron Exp $
+.\"	$OpenBSD: df.1,v 1.23 2000/10/18 06:55:07 aaron Exp $
 .\"	$NetBSD: df.1,v 1.12 1995/12/05 02:42:45 jtc Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
@@ -114,6 +114,13 @@ If a file system is given on the command line that is not of
 the specified type, a warning is issued and no information is given on
 that file system.
 .El
+.Sh EXAMPLES
+.Cm df -kP /usr
+.Pp
+Output, in a strict format suitable for portable scripts, disk space
+statistics for the
+.Pa /usr
+file system using kilobyte block sizes.
 .Sh ENVIRONMENT
 The following environment variables affect the execution of
 .Nm df :
diff --git a/bin/expr/expr.1 b/bin/expr/expr.1
index 169addc3c3f..100310d3e55 100644
--- a/bin/expr/expr.1
+++ b/bin/expr/expr.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: expr.1,v 1.9 2000/03/17 18:15:13 aaron Exp $
+.\"	$OpenBSD: expr.1,v 1.10 2000/10/18 06:55:08 aaron Exp $
 .\"	$NetBSD: expr.1,v 1.9 1995/04/28 23:27:13 jtc Exp $
 .\"
 .\" Written by J.T. Conklin <jtc@netbsd.org>.
@@ -74,10 +74,12 @@ otherwise, returns 0.
 .Pp
 Parentheses are used for grouping in the usual manner.
 .Sh EXAMPLES
+.Cm a=`expr $a + 1`
+.Pp
 Add 1 to the variable
-.Va a :
+.Va a .
 .Pp
-.Dl a=`expr $a + 1`
+.Cm expr "//$a" \&: '.*/\e(.*\e)'
 .Pp
 Return the filename portion of a pathname stored
 in variable
@@ -86,13 +88,10 @@ The
 .Ql //
 characters act to eliminate ambiguity with the division operator.
 .Pp
-.Dl expr "//$a" Li : '.*/\e(.*\e)'
+.Cm expr $a \&: '.*'
 .Pp
 Return the number of characters in variable
-.Va a :
-.Pp
-.Dl expr $a Li : '.*'
-.Pp
+.Va a .
 .Sh DIAGNOSTICS
 The
 .Nm
diff --git a/bin/kill/kill.1 b/bin/kill/kill.1
index 5a7482461e2..4f887b8bdcf 100644
--- a/bin/kill/kill.1
+++ b/bin/kill/kill.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: kill.1,v 1.14 2000/06/28 16:55:15 deraadt Exp $
+.\"	$OpenBSD: kill.1,v 1.15 2000/10/18 06:55:08 aaron Exp $
 .\"	$NetBSD: kill.1,v 1.8 1995/09/07 06:30:26 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
@@ -136,6 +136,17 @@ arguments.
 See
 .Xr csh 1
 for details.
+.Sh EXAMPLES
+.Cm kill -9 -1 1234
+.Pp
+Forcibly terminate process ID 1234.
+.Pp
+.Cm kill -HUP `cat /var/run/inetd.pid`
+.Pp
+Send the
+.Xr inetd 8
+daemon the hangup signal, instructing it to re-read its configuration from
+.Pa /etc/inetd.conf .
 .Sh SEE ALSO
 .Xr csh 1 ,
 .Xr ps 1 ,
diff --git a/bin/ln/ln.1 b/bin/ln/ln.1
index e519288e61b..923c8d038f8 100644
--- a/bin/ln/ln.1
+++ b/bin/ln/ln.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ln.1,v 1.8 1999/09/23 19:15:49 aaron Exp $
+.\"	$OpenBSD: ln.1,v 1.9 2000/10/18 06:55:08 aaron Exp $
 .\"	$NetBSD: ln.1,v 1.10 1995/07/25 19:37:04 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
@@ -121,19 +121,19 @@ makes links in
 to all the named source files.
 The links made will have the same name as the files being linked to.
 .Sh EXAMPLES
-Create a symbolic link named
+.Cm ln -s /var/www /home/www
+.Pp
+Creates a symbolic link named
 .Pa /home/www
-and point it to
-.Pa /var/www :
+and points it to
+.Pa /var/www .
 .Pp
-.D1 Ic ln -s /var/www /home/www
+.Cm ln /usr/local/bin/fooprog-1.0 /usr/local/bin/fooprog
 .Pp
 Hard link
 .Pa /usr/local/bin/fooprog
 to file
-.Pa /usr/local/bin/fooprog-1.0 :
-.Pp
-.D1 Ic ln /usr/local/bin/fooprog-1.0 /usr/local/bin/fooprog
+.Pa /usr/local/bin/fooprog-1.0 .
 .Pp
 As an exercise, try the following commands:
 .Pp
diff --git a/bin/ls/ls.1 b/bin/ls/ls.1
index 7e7a5c4e472..f96217c0c2d 100644
--- a/bin/ls/ls.1
+++ b/bin/ls/ls.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ls.1,v 1.27 2000/07/23 06:16:42 ericj Exp $
+.\"	$OpenBSD: ls.1,v 1.28 2000/10/18 06:55:08 aaron Exp $
 .\"	$NetBSD: ls.1,v 1.14 1995/12/05 02:44:01 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
@@ -393,6 +393,24 @@ system immutable
 The
 .Nm
 utility exits 0 on success or >0 if an error occurred.
+.Sh EXAMPLES
+.Cm ls -l
+.Pp
+List the contents of the current working directory in long format.
+.Pp
+.Cm ls -lioF
+.Pp
+In addition to listing the contents of the current working directory in
+long format, show inode numbers, file flags (see
+.Xr chflags 1 ) ,
+and suffix each filename with a symbol representing its file type.
+.Pp
+.Cm ls -lt /var/log
+.Pp
+List the files in
+.Pa /var/log ,
+sorting the output such that the mostly recently modified entries are
+printed first.
 .Sh ENVIRONMENT
 The following environment variables affect the execution of
 .Nm ls :
diff --git a/bin/mkdir/mkdir.1 b/bin/mkdir/mkdir.1
index 0850980ba95..aa899f952a5 100644
--- a/bin/mkdir/mkdir.1
+++ b/bin/mkdir/mkdir.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mkdir.1,v 1.12 2000/03/21 14:40:14 aaron Exp $
+.\"	$OpenBSD: mkdir.1,v 1.13 2000/10/18 06:55:09 aaron Exp $
 .\"	$NetBSD: mkdir.1,v 1.9 1995/07/25 19:37:13 jtc Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
@@ -90,22 +90,22 @@ The
 .Nm
 utility exits 0 on success or >0 if an error occurred.
 .Sh EXAMPLES
+.Cm mkdir foobar
+.Pp
 Create a directory named
-.Pa foobar :
+.Pa foobar .
 .Pp
-.D1 Ic mkdir foobar
+.Cm mkdir -m 700 foobar
 .Pp
 Create a directory named
 .Pa foobar
-and make it mode 700:
+and sets its file mode to 700.
 .Pp
-.D1 Ic mkdir -m 700 myjunk
+.Cm mkdir -p cow/horse/monkey
 .Pp
-Make a directory named
+Create a directory named
 .Pa cow/horse/monkey ,
-creating any non-existent intermediate directories as necessary:
-.Pp
-.D1 Ic mkdir -p cow/horse/monkey
+creating any non-existent intermediate directories as necessary.
 .Sh SEE ALSO
 .Xr chmod 1 ,
 .Xr rmdir 1 ,
diff --git a/bin/mv/mv.1 b/bin/mv/mv.1
index 0e1783d57ba..56ccfa58762 100644
--- a/bin/mv/mv.1
+++ b/bin/mv/mv.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mv.1,v 1.10 2000/03/21 14:40:14 aaron Exp $
+.\"	$OpenBSD: mv.1,v 1.11 2000/10/18 06:55:09 aaron Exp $
 .\"	$NetBSD: mv.1,v 1.8 1995/03/21 09:06:51 cgd Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
@@ -124,6 +124,16 @@ rm -f destination_path && \e
 The
 .Nm
 utility exits 0 on success or >0 if an error occurred.
+.Sh EXAMPLES
+.Cm mv -f foo bar
+.Pp
+Rename file
+.Pa foo
+to
+.Pa bar ,
+overwriting
+.Pa bar
+if it already exists.
 .Sh SEE ALSO
 .Xr cp 1 ,
 .Xr symlink 7
diff --git a/bin/pax/pax.1 b/bin/pax/pax.1
index 473110b83d4..fb7f4932989 100644
--- a/bin/pax/pax.1
+++ b/bin/pax/pax.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pax.1,v 1.20 2000/04/15 02:15:10 aaron Exp $
+.\"	$OpenBSD: pax.1,v 1.21 2000/10/18 06:55:09 aaron Exp $
 .\"	$NetBSD: pax.1,v 1.3 1995/03/21 09:07:37 cgd Exp $
 .\"
 .\" Copyright (c) 1992 Keith Muller.
@@ -1047,53 +1047,52 @@ options are specified along with the
 option, a file is not considered selected unless it is newer
 than the file to which it is compared.
 .Sh EXAMPLES
-The command:
-.Dl pax -w -f /dev/rst0 .\ 
-copies the contents of the current directory to the device
+.Cm pax -w -f /dev/rst0 .\ 
+.Pp
+Copies the contents of the current directory to the device
 .Pa /dev/rst0 .
 .Pp
-The command:
-.Dl pax -v -f filename
-gives the verbose table of contents for an archive stored in
+.Cm pax -v -f filename
+.Pp
+Gives the verbose table of contents for an archive stored in
 .Pa filename .
 .Pp
-The following commands:
-.Dl mkdir newdir
-.Dl cd olddir
-.Dl pax -rw .\ newdir
-will copy the entire
+.Cm mkdir newdir
+.Cm cd olddir
+.Cm pax -rw .\ newdir
+.Pp
+This sequence of commands will copy the entire
 .Pa olddir
 directory hierarchy to
 .Pa newdir .
 .Pp
-The command:
-.Dl pax -r -s ',^//*usr//*,,' -f a.pax
-reads the archive
+.Cm pax -r -s ',^//*usr//*,,' -f a.pax
+.Pp
+Reads the archive
 .Pa a.pax ,
 with all files rooted in
 .Pa /usr
-into the archive extracted relative to the
-current directory.
+into the archive extracted relative to the current directory.
 .Pp
-The command:
-.Dl pax -rw -i .\ dest_dir
-can be used to interactively select the files to copy from the current
+.Cm pax -rw -i .\ dest_dir
+.Pp
+Can be used to interactively select the files to copy from the current
 directory to
 .Pa dest_dir .
 .Pp
-The command:
-.Dl pax -r -pe -U root -G bin -f a.pax
-will extract all files from the archive
+.Cm pax -r -pe -U root -G bin -f a.pax
+.Pp
+Extract all files from the archive
 .Pa a.pax
 which are owned by
 .Em root
 with group
 .Em bin
-and will preserve all file permissions.
+and preserve all file permissions.
+.Pp
+.Cm "pax -r -w -v -Y -Z home /backup"
 .Pp
-The command:
-.Dl pax -r -w -v -Y -Z home /backup
-will update (and list) only those files in the destination directory
+Update (and list) only those files in the destination directory
 .Pa /backup
 which are older (less recent inode change or file modification times) than
 files with the same name found in the source file tree
diff --git a/bin/ps/ps.1 b/bin/ps/ps.1
index 04c0ab29ac6..4e4ca50eb71 100644
--- a/bin/ps/ps.1
+++ b/bin/ps/ps.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ps.1,v 1.25 2000/06/18 17:59:54 niklas Exp $
+.\"	$OpenBSD: ps.1,v 1.26 2000/10/18 06:55:09 aaron Exp $
 .\"	$NetBSD: ps.1,v 1.16 1996/03/21 01:36:28 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
@@ -512,6 +512,10 @@ wait channel (as a symbolic name)
 .It xstat
 exit or stop status (valid only for stopped or zombie process)
 .El
+.Sh EXAMPLES
+.Cm ps -auxw
+.Pp
+Display information on all system processes.
 .Sh FILES
 .Bl -tag -width /var/db/kvm_bsd.db -compact
 .It Pa /dev
diff --git a/bin/rm/rm.1 b/bin/rm/rm.1
index 38b7d90c61f..1cf124d1ccb 100644
--- a/bin/rm/rm.1
+++ b/bin/rm/rm.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: rm.1,v 1.9 2000/03/21 14:40:14 aaron Exp $
+.\"	$OpenBSD: rm.1,v 1.10 2000/10/18 06:55:10 aaron Exp $
 .\"	$NetBSD: rm.1,v 1.8 1995/07/25 19:37:30 jtc Exp $
 .\"
 .\" Copyright (c) 1990, 1993, 1994
@@ -127,20 +127,18 @@ removed.
 If an error occurs,
 .Nm
 exits with a value >0.
+.Sh EXAMPLES
+.Cm rm -rf foobar
+.Pp
+Recursively remove all files contained within the
+.Pa foobar
+directory hierarchy.
 .Sh SEE ALSO
 .Xr rmdir 1 ,
 .\" .Xr undelete 2 ,
 .Xr unlink 2 ,
 .Xr fts 3 ,
 .Xr symlink 7
-.Sh BUGS
-The
-.Fl P
-option assumes that the underlying file system is a fixed-block file
-system.
-UFS is a fixed-block file system, LFS is not.
-In addition, only regular files are overwritten, other types of files
-are not.
 .Sh COMPATIBILITY
 The
 .Nm
@@ -164,3 +162,11 @@ An
 .Nm
 command appeared in
 .At v1 .
+.Sh BUGS
+The
+.Fl P
+option assumes that the underlying file system is a fixed-block file
+system.
+UFS is a fixed-block file system, LFS is not.
+In addition, only regular files are overwritten, other types of files
+are not.
diff --git a/bin/rmdir/rmdir.1 b/bin/rmdir/rmdir.1
index fdf90833728..7af82bd1790 100644
--- a/bin/rmdir/rmdir.1
+++ b/bin/rmdir/rmdir.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: rmdir.1,v 1.9 2000/03/21 14:40:15 aaron Exp $
+.\"	$OpenBSD: rmdir.1,v 1.10 2000/10/18 06:55:10 aaron Exp $
 .\"	$NetBSD: rmdir.1,v 1.10 1995/07/25 19:37:35 jtc Exp $
 .\"
 .\" Copyright (c) 1990, 1993
@@ -87,6 +87,18 @@ successfully.
 .It Li \&>\&0
 An error occurred.
 .El
+.Sh EXAMPLES
+.Cm rmdir foobar
+.Pp
+Remove the directory
+.Pa foobar
+if it is empty.
+.Pp
+.Cm rmdir -p cow/horse/monkey
+.Pp
+Remove all directories up to and including
+.Pa monkey ,
+stopping at the first non-empty directory (if any).
 .Sh SEE ALSO
 .Xr rm 1 ,
 .Xr rmdir 2