Document the new threading etc. features. From Anon Ymous.

usr.bin/mail/mail.1

@@ -1,4 +1,4 @@
-.\"	$NetBSD: mail.1,v 1.40 2006/11/28 18:45:32 christos Exp $
+.\"	$NetBSD: mail.1,v 1.41 2006/12/03 18:09:09 christos Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"	@(#)mail.1	8.8 (Berkeley) 4/28/95
 .\"
-.Dd November 3, 2006
+.Dd December 3, 2006
 .Dt MAIL 1
 .Os
 .Sh NAME
@@ -223,60 +223,89 @@ session can be aborted by giving the
 command.
 Deleted messages will, however, usually disappear never to be seen again.
 .Ss Specifying messages
-Commands such as
-.Ic print
+Many commands (e.g.,
+.Ic delete ,
+.Ic from ,
 and
-.Ic delete
-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
-deletes messages 1 and 2, while
-.Dq Li delete 1\-5
-deletes messages 1 through 5.
-The special name
-.Ql Li \&*
-addresses all messages,
-.Ql Li \&^
-denotes the first message,
-.Ql Li \&.
-denotes the current message, and
-.Ql Li \&$
-denotes the last message; thus the command
-.Ic top
-which prints the first few lines of a message could be used in
-.Dq Li top \&*
-to print the first few lines of all messages or
-.Dq Li top \&.-$
-to print the first few lines of current to last messages.
-The previous and next messages are denoted by
-.Ql Li \&-
+.Ic print )
+accept a list of messages as an argument.
+Messages may be specified by their message number, by a range of
+messages, or by a pattern string matching certain fields in the header
+as described below.
+These message
+.Qq specs
+may be combined by the usual binary boolean operations
+.Ql Li \&& ,
+.Ql Li \&| ,
 and
-.Ql Li \&+
-respectively, when not used in a range.
+.Ql Li \&^ ,
+which denote, respectively, a logical
+.Qq and ,
+.Qq or ,
+and
+.Qq xor .
+Logical expressions may be grouped with parentheses
+.Ql Li \&(
+and
+.Ql Li \&)
+and
+negated with
+.Ql Li \&! .
+If the binary operator is missing between two message specs, it is
+assumed to be a
+.Ql Li \&| .
+This is for simplicity, backwards compatibility, and also to to
+facilitate using the 
+.Ql Li \&|
+symbol to denote a pipe.
+(See
+.Ar enable-pipes . )
 .Pp
-Messages may also be specified by the sender's name, by the subject,
-or (if
+Besides the obvious (base10) message numbers, the characters
+.Ql Li \&^ ,
+.Ql Li \&- ,
+.Ql Li \&. ,
+.Ql Li \&+ ,
+and
+.Ql Li \&$
+denote, respectively, the first message, the message before the
+.Sq dot ,
+the
+.Sq dot
+message, the message following the
+.Sq dot ,
+and the last message.
+.Pp
+A
+.Dq message range
+consists of two message numbers separated by a
+.Ql Li \&- .
+A
+.Ql Li \&*
+denotes all messages and is equivalent to
+.Ql Li ^-$ .
+.Pp
+A pattern is a string (not beginning with any of the above special
+characters).
+If it does not begin with a
+.Ql Li \&/ ,
+it is compared with the senders address.
+If it begins with a
+.Ql Li \&/ ,
+and
+.Qq searchheaders
+is not defined, the remainder of the string is compared with the
+subject field.
+(See
 .Ar searchheaders
-is defined) by any header field.
-A non-numeric string that does not begin a
-.Sq /
-or with any of the above special
-characters is assumed to specify sender's name: a case insensitive
-substring compare with the senders name is done, unless
+for searching other header fields.)
+If
 .Ar regex-search
-is defined.
-If the string begins with a
-.Sq /
-then what follows is compared with the subject field, again the
-matching is controled by the
+is not defined, then the comparison is a simple case insensitive
+substring match.
+(See
 .Ar regex-search
-variable.
-To search other header fields, see the
-.Ar searchheader
-variable.
-Multiple search specs may be given and they may be mixed with numeric
-lists.
+for regular expression matches.)
 .Pp
 A list of messages may be restricted by a
 .Sq colon-modifier
@@ -298,7 +327,7 @@ u	unread and not new
 .Ed
 .Pp
 If there are no address specifications other than colon-modifiers,
-the colon-modifiers apply to all messags.
+the colon-modifiers apply to all messages.
 Thus
 .Dq Li from netbsd :n
 would display the headers of all new messages with
@@ -311,9 +340,28 @@ would both display all new and unread messages.
 Multiple colon-modifiers may be specified and a single
 .Sq \&:
 with no letters following indicates the colon-modifier from the
-preceeding command.
-Note: commands cannot select messages that are not displayed, such as
-deleted or hidden messages, the exception being the
+preceding command.
+.Pp
+For example:
+.Bd -literal -offset indent
+from 1 12 3-5
+.Ed
+.Pp
+would display the headers from messages 1, 3, 4, 5, and 12.
+.Bd -literal -offset indent
+from anon & ( /foo | /bar )
+.Ed
+.Pp
+would display all headers that had 
+.Qq anon
+in the sender's address and either
+.Qq foo
+or
+.Qq bar
+in the subject line.
+.Pp
+Generally, commands cannot select messages that are not displayed,
+such as deleted or hidden messages, the exception being the
 .Ic undelete
 command.
 .Pp
@@ -420,6 +468,13 @@ types
 .Dq Li \&No applicable messages
 and aborts the command.
 .Bl -tag -width delete
+.It Ic \&!
+Executes the shell
+(see
+.Xr sh 1
+and
+.Xr csh 1 )
+command which follows.
 .It Ic \&\-
 Print out the preceding message.
 If given a numeric
@@ -428,15 +483,11 @@ argument
 goes to the
 .Ar n Ap th
 previous message and prints it.
+.It Ic \&=
+With no argument, it displays the current message number.
+Otherwise, set the current message number to its first argument.
 .It Ic \&?
 Prints a brief summary of commands.
-.It Ic \&!
-Executes the shell
-(see
-.Xr sh 1
-and
-.Xr csh 1 )
-command which follows.
 .It Ic \&|
 Pipe the current message body through the shell
 (see
@@ -537,6 +588,14 @@ command does the same thing that
 .Ic save
 does, except that it does not mark the messages it
 is used on for deletion when you quit.
+.It Ic deldups
+Delete duplicate messages based on their
+.Qq Message-Id
+field, keeping the first one in the current sort order.
+This can be useful with replies to a mailing list that are also CCed
+to a subscriber.
+(The same thing can also be accomplished with the threading and
+tagging commands.)
 .It Ic delete
 .Pq Ic d
 Takes a list of messages as argument and marks them all as deleted.
@@ -572,7 +631,9 @@ If there is no next message,
 says
 .Dq Li "at EOF" .
 .It Ic down
-XXX - document me!
+Go down one level in the thread.
+If given a message number, it descends the thread below that message,
+otherwise it descends from the current message (dot).
 .It Ic edit
 .Pq Ic e
 Takes a list of messages and points the text editor at each one in
@@ -603,11 +664,21 @@ modifying the user's system mailbox, his
 file, or his edit file in
 .Fl f .
 .It Ic expose
-XXX - document me!
+Expose the thread structure so all messages appear in header listings.
+(See
+.Ar hide
+for the inverse.)
+The default header prompt will indent each header line one space for
+each level in the threading.
+The'%?* ?' format string does this.
 .It Ic file
 .Pq Ic fi
 The same as
 .Ic folder .
+.It Ic flatten
+For each message number in the argument list, or the current thread if
+no message list is given, promote all exposed children to the same
+level.
 .It Ic folders
 List the names of the folders in your folder directory.
 .It Ic folder
@@ -648,7 +719,19 @@ argument is given, the previous 18\-message group is printed.
 A synonym for
 .Ic \&?
 .It Ic hide
-XXX - document me!
+Collapse the threads so that only the head of each thread is shown,
+hiding the subthreads.
+(See
+.Ar expose
+for the inverse.)
+.It Ic hidetags
+Restrict the display to tagged messages.
+In threaded mode, subthreads that connect directly to an untagged
+message are also displayed, including tagged messages in the
+connecting chain.
+.It Ic hidethreads
+The same as
+.Ar hide .
 .It Ic hold
 .Po Ic ho ,
 also
@@ -661,8 +744,12 @@ Does not override the
 .Ic delete
 command.
 .It Ic if
-Execute commands that follow depending on the operating mode.  The
-current supported modes are "receiving", "sending", and "headersonly".
+Execute commands that follow depending on the operating mode.
+The current supported modes are
+.Qq receiving ,
+.Qq sending ,
+and
+.Qq headersonly .
 For example, one use might be:
 .Bd -literal -offset 0
 if headersonly
@@ -701,6 +788,10 @@ If
 .Ic ignore
 is executed with no arguments, it lists the current set of
 ignored fields.
+.It Ic invtags
+Invert the tags on a list of messages or the current message if none
+are given.
+Note: this will not affect any currently deleted messages.
 .It Ic mail
 .Pq Ic m
 Takes as argument login names and distribution group names and sends
@@ -785,7 +876,9 @@ If
 is executed with no arguments, it lists the current set of
 retained fields.
 .It Ic reverse
-XXX - document me!
+Reverse the order of the messages in at the current thread level.
+This is completely equivalent to
+.Sq sort \&! .
 .It Ic save
 .Pq Ic s
 Takes a message list and a filename and appends each message in
@@ -845,6 +938,12 @@ Invokes an interactive version of the shell.
 Takes a list of variables and prints out their values in the form
 .Ar option=value .
 If the list is empty, all variable values are shown.
+.It Ic showtags
+Display all current messages, tagged or not, unless they are in a
+hidden thread.
+.It Ic showthreads
+The same as
+.Ar expose .
 .It Ic size
 Takes a message list and prints out the size in characters of each
 message.
@@ -867,7 +966,7 @@ The
 may be an alias, address, domain (beginning with a
 .Sq @ ) ,
 or subdomain
-(begining with a
+(beginning with a
 .Sq \&. ) .
 If mail is sent to multiple users, the sendmail flags are
 used only if the flags are the same for each recipients.
@@ -902,18 +1001,105 @@ would not have any sendmail flags set (unless they are set by the
 .Ic \&~h
 escape).
 .It Ic sort
-XXX - document me!
+With no argument,
+.Ic sort
+does nothing.
+Otherwise it will sort based on the header field name given as an
+argument.
+A few names are special:
+.Bd -literal -offset indent
+"blines"	sort based on the number of body lines.
+"hlines"	sort on the number of header lines.
+"tlines"	sort on the total number of lines.
+"size"		sort on the message size
+"sday"		sent day (ignores the hour/min/sec)
+"rday"		received day (ignores the hour/min/sec)
+"sdate"		sent date
+"rdate"		received date
+"subject"	sort on the subject, ignoring "Re:" prefixes.
+"from"		sort on the sender's address.
+.Ed
+.Pp
+The check for these special names is case sensitive while the header
+field name comparisons are case insensitive, so changing the case on
+any of these special names will sort based on the header field
+ignoring the special keyword.
+.Pp
+There are also three modifiers which may preceed the argument:
+.Bd -literal -offset indent
+\&'!'	reverse the sorting order.
+\&'^'	case insensitive sorting.
+\&'-'	skin the field (removing RFC 822 comments and
+	keep the address).
+.Ed
+.Pp
+The same keywords and modifiers also apply to threading (see the
+.Ic thread
+command).
+.Pp
+Note:
+.Ic sort
+has no effect on the threading, sorting only on the heads
+of the threads if threads exist.
+See the
+.Ic thread
+command.
+.Pp
 .It Ic source
 The
 .Ic source
 command reads commands from a file.
+.It Ic tag
+Tag a list of messages or the current message if none are given.
+In hidden thread mode, the entire thread will be tagged, i.e.,
+.Ic tag
+is recursive
+.It Ic tagbelow
+Tag all messages of the current thread below the level of the
+current message (dot) or the supplied message number if given.
 .It Ic thread
-XXX - document me!
+By default this threads the current message list based on the
+.Qq In-Reply-To
+and
+.Qq References
+header fields (intended for this purpose by RFC 2822).
+If given an argument, it will thread on that header field name
+instead.
+The same field keywords and modifiers recognized by the sort command
+are also recognized here.
+Display of the threads is controlled by the
+.Ic hide
+and
+.Ic expose
+commands; navigation of threads is done with the
+.Ic down ,
+.Ic up ,
+and 
+.Ic tset
+commands.
+.Pp
+If
+.Qq recursive-commands
+is defined, many commands (e.g.,
+.Ic print )
+act on the entire thread (when it is hidden), otherwise they act on
+just the current message.
+.Pp
+NOTE: the
+.Qq In-Reply-To
+and
+.Qq Reference
+header fields are necessary to do threading correctly.
+This version of mail(1) now emits these header fields when replying.
 .It Ic top
 Takes a message list and prints the top few lines of each.
 The number of lines printed is controlled by the variable
 .Ic toplines
 and defaults to five.
+.It Ic tset
+Set the current thread (thread set) so that the supplied message
+number (or the current message if no argument is given) is at the top
+level of the current thread.
 .It Ic type
 .Pq Ic t
 A synonym for
@@ -937,23 +1123,33 @@ having been read.
 Takes a list of option names and discards their remembered values;
 the inverse of
 .Ic set .
-.It Ar unsmopts
+.It Ic unsmopts
 Takes a list of
 .Sq address-specs
 defined by
 .Ic smopts
 commands and discards them from the smopts datebase.
+.It Ic untag
+Untag a list of messages or the current message if none are given.
+Like the
+.Ic tag
+command,
+.Ic untag
+is recursive on hidden threads.
 .It Ic unthread
-XXX - document me!
+Undo all threading and sorting, restoring the original display order,
+i.e., the order in the mail file.
 .It Ic up
-XXX - document me!
+Go up one level in the thread.
+This also takes an optional (positive) argument to go up multiple
+levels in the thread.
 .It Ic view
 .Pq Ic vie
 Like
 .Ic print
 but has the opposite MIME decoding behavior.
 (See the
-.Ar mime-decode-message
+.Ic mime-decode-message
 variable.)
 .It Ic visual
 .Pq Ic v
@@ -1177,6 +1373,37 @@ causes
 .Nm
 to interpret a period alone on a line as the terminator
 of a message you are sending.
+.It Ar enable-pipes
+If defined, the output of most commands can be piped into a shell
+command or redirected to a file.
+The pipe/redirection is signaled by the first occurrence of a
+.Sq |
+or
+.Sq >
+character that is not in a quoted string or in a parenthetical
+group.
+This character terminates the mail command line and the remaining
+string is passed to the shell.
+For example, assuming normal headers, something like
+.Bd -literal -offset indent
+  from john@ | fgrep -i ' "Re:' | wc
+.Ed
+.Pp
+could be used to count how may replies were made by senders with
+.Qq john@
+in their address and
+.Bd -literal -offset indent
+  from john@ >> /tmp/john
+.Ed
+.Pp
+would append all the headers such senders to /tmp/john.
+.Pp
+Note: With piping enabled, you cannot use the
+.Ql Li \&|
+as a logical
+.Qq or
+operator outside of a parenthetical group.
+This should not be a problem as it is the default logical operator.
 .It Ar hold
 This option is used to hold messages in the system mailbox
 by default.
@@ -1260,6 +1487,7 @@ delete dp dt
 undelete
 hold preserve
 mbox mkread touch unread
+tag untag invtags
 .Ed
 .Pp
 If not defined, or if the threads are
@@ -1466,7 +1694,7 @@ The message size.
 The current
 .Qq dot
 .Pq Sq \*[Gt]
-messsage.
+message.
 .It Ar \&%Q
 The message status flag.
 .It Ar \&%Z
@@ -1496,7 +1724,30 @@ For example, the default format is:
 set header-format \&"\&%??%P%Q%?* ?%3i \&%-21.20f \&%a \&%b \&%e \&%R \&%3K/%-5O \&\\"%q\\""
 .Ed
 .Pp
-Note:
+Note 1: The message status flag
+.Sq \&%Q
+will display the single character
+.Sq \+
+for the parent of a subthread.
+This will be overwritten by a
+.Sq T ,
+.Sq E ,
+.Sq \&* ,
+.Sq P ,
+.Sq U ,
+.Sq N ,
+.Sq M
+indicating, respectively, a tagged, modified, saved, preserved,
+unread, new, or modified message, in that order with the last matching
+condition being the one displayed.
+In the case hidden threads, the entire subthread is searched and the
+letters above will be displayed in lower case if the property is that
+of a hidden child with the case
+.Sq \&*
+being displayed as
+.Sq \&& .
+.Pp
+Note 2:
 .Ar \&%n
 and
 .Ar \&%t
@@ -1568,7 +1819,7 @@ If unset, no character set conversion is done.
 If set, decode the headers along with the body when
 .Ar mime-decode-message
 is set.
-The header decode follows the same rulse as the body (see
+The header decode follows the same rules as the body (see
 .Ar mime-decode-message ) .
 .It Ar mime-decode-insert
 When inserting
@@ -1771,7 +2022,6 @@ in a sub-shell rather than doing an
 .Xr exec 3
 (see
 .Va Shell ) .
-This is necessary for shell scripts.
 .It +
 Use this hook when selecting the part to display in a
 .Qq multipart/alternative