From 1194ba0741d1d592482864af17f09302d06a4b1c Mon Sep 17 00:00:00 2001 From: christos Date: Sun, 3 Dec 2006 18:09:09 +0000 Subject: [PATCH] Document the new threading etc. features. From Anon Ymous. --- usr.bin/mail/mail.1 | 406 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 328 insertions(+), 78 deletions(-) diff --git a/usr.bin/mail/mail.1 b/usr.bin/mail/mail.1 index 4ab121e9d4cb..b83e6af5fc33 100644 --- a/usr.bin/mail/mail.1 +++ b/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