significant cleanup; also s/INTRODUCTION/DESCRIPTION/, in particular for man -h

1 files changed, 147 insertions, 124 deletions

diff --git a/usr.bin/mail/mail.1 b/usr.bin/mail/mail.1
index 6705cffc754..8cb8a763fa7 100644
--- a/usr.bin/mail/mail.1
+++ b/usr.bin/mail/mail.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mail.1,v 1.21 1998/11/11 23:01:45 aaron Exp $
+.\"	$OpenBSD: mail.1,v 1.22 1998/11/19 23:23:49 aaron Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -45,8 +45,8 @@
 .Nm mail
 .Op Fl iInv
 .Op Fl s Ar subject
-.Op Fl c Ar cc-addr
-.Op Fl b Ar bcc-addr
+.Op Fl c Ar list
+.Op Fl b Ar list
 .Ar to-addr Op Ar ...
 .Op Fl Ar sendmail-options Op Ar ...
 .Nm mail
@@ -56,7 +56,7 @@
 .Nm mail
 .Op Fl iInNv
 .Op Fl u Ar user
-.Sh INTRODUCTION
+.Sh DESCRIPTION
 .Nm mail
 is an intelligent mail processing system which has
 a command syntax reminiscent of
@@ -74,58 +74,59 @@ particularly useful when using
 .Nm mail
 on noisy phone lines.
 .It Fl I
-Forces mail to run in interactive mode even when
-input isn't a terminal.
-In particular, the
-.Sq Ic \&~
-special
-character when sending mail is only active in interactive mode.
+Forces
+.Nm mail
+to run in interactive mode, even when input is not a terminal.
+In particular, the special
+.Ic \&~
+command character, used when sending mail, is only available interactively.
 .It Fl n
 Inhibits reading
 .Pa /etc/mail.rc
 upon startup.
 .It Fl N
-Inhibits the initial display of message headers
+Inhibits initial display of message headers
 when reading mail or editing a mail folder.
 .It Fl s Ar subject
 Specify subject on command line
 (only the first argument after the
 .Fl s
 flag is used as a subject; be careful to quote subjects
-containing spaces.)
-.It Fl c Ar cc-addr
+containing spaces).
+.It Fl c Ar list
 Send carbon copies to
 .Ar list
 of users.
-.It Fl b Ar bcc-addr
+.Ar list
+should be a comma separated list of names.
+.It Fl b Ar list
 Send blind carbon copies to
 .Ar list .
-List should be a comma-separated list of names.
-.It Fl f
-Read in the contents of your
-.Ar mbox
-(or the specified file)
-for processing; when you
-.Ar quit  ,
+.It Fl f Ar name
+Read in the contents of your mailbox
+(or the specified file
+.Ar name )
+for processing; when you quit,
 .Nm mail
 writes undeleted messages back to this file.
 .It Fl u Ar user
 Is equivalent to:
 .Pp
 .Dl mail -f /var/mail/user
-Except that locking is done.
+.Pp
+except that locking is done.
 .El
 .Ss Startup actions
-At startup time
+At startup time,
 .Nm mail 
 will execute commands in the system command files
 .Pa /usr/share/misc/mail.rc , 
-.Pa /usr/local/etc/mail.rc ,
+.Pa /usr/local/etc/mail.rc
 and
 .Pa /etc/mail.rc 
 in order unless explicitly told not to by using the
 .Fl n
-option.  Next, the commands in the user's personal command file 
+option. Next, the commands in the user's personal command file 
 .Pa ~/.mailrc 
 are executed.
 .Nm mail
@@ -139,8 +140,8 @@ can be invoked with arguments which are the names of people to
 whom the mail will be sent.
 You are then expected to type in
 your message, followed
-by an
-.Sq Li control\-D
+by a control-D
+.Pq Sq ^D
 at the beginning of a line.
 The section below,
 .Ar Replying to or originating mail ,
@@ -149,30 +150,30 @@ describes some features of
 available to help you compose your letter.
 .Pp
 .Ss Reading mail
-In normal usage
+In normal usage,
 .Nm mail
 is given no arguments and checks your mail out of the
 post office, then
 prints out a one line header of each message found.
-The current message is initially the first message (numbered 1)
+The current message is initially set to the first message (numbered 1)
 and can be printed using the
 .Ic print
 command (which can be abbreviated
 .Ic p ) .
-You can move among the messages much as you move between lines in
-.Xr \&ed 1 ,
-with the commands
-.Ql Ic \&+
+Moving among the messages is much like moving between lines in
+.Xr ed 1 ;
+you may use
+.Ic \&+
 and
-.Ql Ic \&\-
-moving backwards and forwards, and
-simple numbers.
+.Ic \&-
+to shift forwards and backwards, or simply enter a message number to move
+directly.
 .Pp
-.Ss Disposing of mail.
+.Ss Disposing of mail
 After examining a message you can
 .Ic delete
 .Pq Ic d
-the message or
+or
 .Ic reply
 .Pq Ic r
 to it.
@@ -188,7 +189,7 @@ session can be aborted by giving the
 .Ic exit
 .Pq Ic x
 command.
-Deleted messages will, however, usually disappear never to be seen again.
+Deleted messages, however, will usually disappear, never to be seen again.
 .Pp
 .Ss Specifying messages
 Commands such as
@@ -198,22 +199,22 @@ and
 can be given a list of message numbers as arguments to apply
 to a number of messages at once.
 Thus
-.Dq Li delete 1 2
+.Ic delete 1 2
 deletes messages 1 and 2, while
-.Dq Li delete 1\-5
+.Ic delete 1\-5
 deletes messages 1 through 5.
 The special name
-.Ql Li \&*
-addresses all messages, and
-.Ql Li \&$
+.Dq \&*
+addresses all messages and
+.Dq \&$
 addresses
 the last message; thus the command
 .Ic top
 which prints the first few lines of a message could be used in
-.Dq Li top \&*
+.Ic top \&*
 to print the first few lines of all messages.
 .Pp
-.Ss Replying to or originating mail.
+.Ss Replying to or originating mail
 You can use the
 .Ic reply
 command to
@@ -223,15 +224,15 @@ Text you then type in, up to an end-of-file,
 defines the contents of the message.
 While you are composing a message,
 .Nm mail
-treats lines beginning with the character
-.Ql Ic \&~
-specially.
+treats lines beginning with the tilde
+.Pq Sq ~
+character specially.
 For instance, typing
-.Ql Ic \&~m
+.Ic ~m
 (alone on a line) will place a copy
-of the current message into the response right shifting it by a tabstop
-(see
-.Em indentprefix
+of the current message into the response, right shifting it by a single
+tab-stop (see
+.Va indentprefix
 variable, below).
 Other escapes will set up subject fields, add and delete recipients
 to the message and allow you to escape to an editor to revise the
@@ -239,7 +240,7 @@ message or to a shell to run some commands.
 (These options
 are given in the summary below.)
 .Pp
-.Ss Ending a mail processing session.
+.Ss Ending a mail processing session
 You can end a
 .Nm mail
 session with the
@@ -249,12 +250,11 @@ command.
 Messages which have been examined go to your
 .Ar mbox
 file unless they have been deleted in which case they are discarded.
-Unexamined messages go back to the post office.
-(See the
+Unexamined messages go back to the post office (see the
 .Fl f
 option above).
 .Pp
-.Ss Personal and systemwide distribution lists.
+.Ss Personal and system wide distribution lists
 It is also possible to create personal distribution lists so that,
 for instance, you can send mail to
 .Dq Li cohorts
@@ -270,24 +270,23 @@ in your home directory.
 The current list of such aliases can be displayed with the
 .Ic alias
 command in
-.Nm mail  .
+.Nm mail .
 System wide distribution lists can be created by editing
 .Pa /etc/aliases ,
-see
-.Xr aliases  5
+(see
+.Xr aliases 5
 and
-.Xr sendmail  8  ;
+.Xr sendmail 8 ) ;
 these are kept in a different syntax.
 In mail you send, personal aliases will be expanded in mail sent
 to others so that they will be able to
 .Ic reply
 to the recipients.
-System wide
-.Ic aliases
+System wide aliases
 are not expanded when the mail is sent,
 but any reply returned to the machine will have the system wide
 alias expanded as all mail goes through
-.Xr sendmail  .
+.Xr sendmail .
 .Pp
 .Ss Network mail (ARPA, UUCP, Berknet)
 See
@@ -304,12 +303,13 @@ enables the
 feature.
 (These options are summarized below.)
 .Sh SUMMARY
-(Adapted from the `Mail Reference Manual')
+(Adapted from the
+.Dq Mail Reference Manual . ) 
 .Pp
 Each command is typed on a line by itself, and may take arguments
 following the command word.
 The command need not be typed in its
-entirety \- the first command which matches the typed prefix is used.
+entirety -- the first command which matches the typed prefix is used.
 For commands which take message lists as arguments, if no message
 list is given, then the next message forward which satisfies the
 command's requirements is used.
@@ -326,9 +326,9 @@ aborts the command.
 Print out the preceding message.
 If given a numeric
 argument
-.Ar n  ,
+.Ar n ,
 goes to the
-.Ar n Ns 'th
+.Ar n Ns th
 previous message and prints it.
 .It Ic \&?
 Prints a brief summary of commands.
@@ -403,7 +403,7 @@ is used on for deletion when you quit.
 .Pq Ic d
 Takes a list of messages as argument and marks them all as deleted.
 Deleted messages will not be saved in
-.Ar mbox  ,
+.Ar mbox ,
 nor will they be available for most other commands.
 .It Ic dp
 (also
@@ -426,11 +426,11 @@ Effects an immediate return to the shell without
 modifying the user's system mailbox, his
 .Ar mbox
 file, or his edit file in
-.Fl f  .
+.Fl f .
 .It Ic file
 .Pq Ic fi
 The same as
-.Ic folder  .
+.Ic folder .
 .It Ic folders
 List the names of the folders in your folder directory.
 .It Ic folder
@@ -460,14 +460,14 @@ Takes a list of messages and prints their message headers.
 Lists the current range of headers, which is an 18\-message group.
 If
 a
-.Ql \&+
-argument is given, then the next 18\-message group is printed, and if
+.Dq \&+
+argument is given, the next 18\-message group is printed; if
 a
-.Ql \&\-
+.Dq \&\-
 argument is given, the previous 18\-message group is printed.
 .It Ic help
 A synonym for
-.Ic \&?  .
+.Ic \&? .
 .ne li
 .It Ic hold
 .Pf ( Ic ho ,
@@ -476,7 +476,7 @@ also
 Takes a message list and marks each
 message therein to be saved in the
 user's system mailbox instead of in
-.Ar mbox  .
+.Ar mbox .
 Does not override the
 .Ic delete
 command.
@@ -533,7 +533,7 @@ With an argument list, types the next matching message.
 .It Ic preserve
 .Pq Ic pre
 A synonym for
-.Ic hold  .
+.Ic hold .
 .It Ic print
 .Pq Ic p
 Takes a message list and types out each message on the user's terminal.
@@ -568,10 +568,10 @@ recipients of the specified message.
 The default message must not be deleted.
 .It Ic respond
 A synonym for
-.Ic reply  .
+.Ic reply .
 .It Ic retain
 Add the list of header fields named to the
-.Ar retained list  .
+.Ar retained list .
 Only the header fields in the retain list
 are shown on your terminal when you print a message.
 All other header fields are suppressed.
@@ -601,7 +601,7 @@ Arguments are of the form
 .Ar option .
 Quotation marks may be placed around any part of the assignment statement to
 quote blanks or tabs, i.e.
-.Dq Li "set indentprefix=\*q->\*q"
+.Dq Li "set indentprefix=\*q->\*q" .
 .It Ic saveignore
 .Ic Saveignore
 is to
@@ -611,12 +611,12 @@ what
 is to
 .Ic print
 and
-.Ic type  .
+.Ic type .
 Header fields thus marked are filtered out when
 saving a message by
 .Ic save
 or when automatically saving to
-.Ar mbox  .
+.Ar mbox .
 .pl +1
 .It Ic saveretain
 .Ic Saveretain
@@ -627,15 +627,15 @@ what
 is to
 .Ic print
 and
-.Ic type  .
+.Ic type .
 Header fields thus marked are the only ones saved
 with a message when saving by
 .Ic save
 or when automatically saving to
-.Ar mbox  .
+.Ar mbox .
 .Ic Saveretain
 overrides
-.Ic saveignore  .
+.Ic saveignore .
 .It Ic shell
 .Pq Ic sh
 Invokes an interactive version of the shell.
@@ -656,7 +656,7 @@ and defaults to five.
 .It Ic type
 .Pq Ic t
 A synonym for
-.Ic print  .
+.Ic print .
 .It Ic unalias
 Takes a list of names defined by
 .Ic alias
@@ -676,14 +676,14 @@ having been read.
 .It Ic unset
 Takes a list of option names and discards their remembered values;
 the inverse of
-.Ic set  .
+.Ic set .
 .It Ic visual
 .Pq Ic v
 Takes a message list and invokes the display editor on each message.
 .It Ic write
 .Pq Ic w
 Similar to
-.Ic save  ,
+.Ic save ,
 except that
 .Ic only
 the message body
@@ -696,7 +696,7 @@ program text over the message system.
 .It Ic xit
 .Pq Ic x
 A synonym for
-.Ic exit  .
+.Ic exit .
 .It Ic z
 .Nm mail
 presents message headers in windowfuls as described under the
@@ -708,16 +708,16 @@ attention forward to the next window with the
 .Ic \&z
 command.
 Also, you can move to the previous window by using
-.Ic \&z\&\-  .
+.Ic \&z\&\- .
 .El
-.Ss Tilde/Escapes
+.Ss Tilde/escapes
 Here is a summary of the tilde escapes,
 which are used when composing messages to perform
 special functions.
 Tilde escapes are only recognized at the beginning
 of lines.
 The name
-.Dq Em tilde\ escape
+.Dq tilde escape
 is somewhat of a misnomer since the actual escape character can be set
 by the option
 .Ic escape .
@@ -731,7 +731,7 @@ the names visible in the Cc: line ("blind" carbon copy).
 Add the given names to the list of carbon copy recipients.
 .It Ic \&~d
 Read the file
-.Dq Pa dead.letter
+.Pa dead.letter
 from your home directory into the message.
 .It Ic \&~e
 Invoke the text editor on the message collected so far.
@@ -758,7 +758,7 @@ current terminal erase and kill characters.
 .It Ic \&~m Ns Ar messages
 Read the named messages into the message being sent, indented by a
 tab or by the value of
-.Ar indentprefix  .
+.Ar indentprefix .
 If no messages are specified,
 read the current message.
 Message headers currently being ignored (by the
@@ -775,7 +775,7 @@ Print out the message collected so far, prefaced by the message header
 fields.
 .It Ic \&~q
 Abort the message being sent, copying the message to
-.Dq Pa dead.letter
+.Pa dead.letter
 in your home directory if
 .Ic save
 is set.
@@ -815,7 +815,7 @@ If
 you have changed the escape character, then you should double
 that character in order to send it.
 .El
-.Ss Mail Options
+.Ss Mail options
 Options are controlled via
 .Ic set
 and
@@ -870,7 +870,7 @@ is the same as specifying
 on the command line and causes
 .Nm mail
 to output all sorts of information useful for debugging
-.Nm mail  .
+.Nm mail .
 .It Ar dot
 The binary option
 .Ar dot
@@ -913,7 +913,7 @@ Normally, when you abort a message with two
 (erase or delete)
 .Nm mail
 copies the partial letter to the file
-.Dq Pa dead.letter
+.Pa dead.letter
 in your home directory.
 Setting the binary option
 .Ar nosave
@@ -927,16 +927,38 @@ commands.
 .It Ar quiet
 Suppresses the printing of the version when first invoked.
 .It Ar searchheaders
-If this option is set, then a message-list specifier in the form ``/x:y''
-will expand to all messages containing the substring ``y'' in the header
-field ``x''.  The string search is case insensitive.
-If ``x'' is omitted, it will default to the ``Subject'' header field.
-The form ``/to:y'' is a special case, and will expand
-to all messages containing the substring ``y'' in the ``To'', ``Cc''
-or ``Bcc'' header fields.
-The check for "to" is case sensitive, so that
-``/To:y'' can be used to limit the search for ``y'' to just
-the ``To:'' field.
+If this option is set, then a message-list specifier in the form
+.Dq /x:y
+will expand to all messages containing the substring
+.Dq y
+in the header
+field
+.Dq x .
+The string search is case insensitive. If
+.Dq x
+is omitted, it will default to the
+.Dq Subject
+header field.
+The form
+.Dq /to:y
+is a special case, and will expand
+to all messages containing the substring
+.Dq y
+in the
+.Dq To ,
+.Dq Cc
+or
+.Dq Bcc
+header fields.
+The check for
+.Dq to
+is case sensitive, so that
+.Dq /To:y
+can be used to limit the search for
+.Dq y
+to just the
+.Dq To:
+field.
 .It Ar verbose
 Setting the option
 .Ar verbose
@@ -947,7 +969,7 @@ When mail runs in verbose mode,
 the actual delivery of messages is displayed on the user's
 terminal.
 .El
-.Ss Option String Values
+.Ss Option string values
 .Bl -tag -width Va
 .It Ev EDITOR
 Pathname of the text editor to use in the
@@ -1005,7 +1027,8 @@ use in the place of ~ to denote escapes.
 .It Ar folder
 The name of the directory to use for storing folders of
 messages.
-If this name begins with a `/',
+If this name begins with a
+.Dq / ,
 .Nm mail
 considers it to be an absolute pathname; otherwise, the
 folder directory is found relative to your home directory.
@@ -1022,8 +1045,10 @@ If defined, gives the pathname of the file used to record all outgoing
 mail.
 If not defined, then outgoing mail is not so saved.
 .It Ar indentprefix
-String used by the ``~m'' tilde escape for indenting messages, in place of
-the normal tab character (^I).
+String used by the 
+.Ic \&~m
+tilde escape for indenting messages, in place of the normal tab character
+.Pq Sq ^I
 Be sure to quote the value if it contains
 spaces or tabs.
 .It Ar toplines
@@ -1048,22 +1073,21 @@ user's mail spool.
 .Sh FILES
 .Bl -tag -width /usr/share/misc/mail.*help -compact
 .It Pa /var/mail/*
-Post office (unless overridden by the
+post office (unless overridden by the
 .Ev MAIL
-environment variable).
+environment variable)
 .It ~/mbox
-User's old mail.
+user's old mail
 .It ~/.mailrc
-File giving initial mail commands.
-This can be overridden by setting the
+file giving initial mail commands; can be overridden by setting the
 .Ev MAILRC
-environment variable.
+environment variable
 .It Pa /tmp/R*
-Temporary files.
+temporary files
 .It Pa /usr/share/misc/mail.*help
-Help files.
+help files
 .It Pa /etc/mail.rc
-System initialization file.
+system initialization file
 .El
 .Sh SEE ALSO
 .Xr fmt 1 ,
@@ -1074,9 +1098,8 @@ System initialization file.
 .Xr mailaddr 7 ,
 .Xr mail.local 8 ,
 .Xr sendmail 8
-and
 .Rs
-.%T "The Mail Reference Manual" .
+.%T "The Mail Reference Manual"
 .Re
 .Sh HISTORY
 A
@@ -1097,5 +1120,5 @@ Usually,
 and
 .Nm mailx
 are just links to
-.Nm Mail  ,
+.Nm Mail ,
 which can be confusing.