Edit docs

* doc/texinfo/programs/mail.texi: Reorder material. Document message
states. Rewrite description of message lists. Describe mailbox argument
in file, save, write, etc.
* doc/texinfo/mailutils.texi: Regenerate detailed menu

2 files changed, 857 insertions, 722 deletions

diff --git a/doc/texinfo/mailutils.texi b/doc/texinfo/mailutils.texi
index 6b249db38..b1a0a2724 100644
--- a/doc/texinfo/mailutils.texi
+++ b/doc/texinfo/mailutils.texi
@@ -179,6 +179,7 @@ Mailutils Configuration File
 * sql statement::
 * ldap statement::
 * tls statement::
+* tls-file-checks statement::
 * gsasl statement::
 
 Configuration File Syntax
@@ -201,8 +202,8 @@ Debugging
 @command{mail} --- Send and Receive Mail
 
 * Invoking Mail::            Command Line Options.
-* Specifying Messages::      How to Specify Message Sets.
 * Composing Mail::           Composing Mail.
+* MIME::                     How to Attach Files.
 * Reading Mail::             Reading Mail.
 * Scripting::                Scripting.
 * Mail Variables::           How to Alter the Behavior of @command{mail}.
@@ -226,6 +227,7 @@ Composing Mail
 
 Reading Mail
 
+* Command Syntax::           Syntax of mail internal commands.
 * Quitting the Program::
 * Obtaining Online Help::
 * Moving Within a Mailbox::
@@ -343,6 +345,7 @@ mailutils
 * mailutils info::                Show Mailutils configuration.
 * mailutils cflags::              Show compiler options.
 * mailutils ldflags::             List libraries required to link.
+* mailutils stat::                Show mailbox status.
 * mailutils query::               Query configuration values.
 * mailutils 2047::                Decode/encode email message headers.
 * mailutils filter::              Apply a chain of filters to the input.
@@ -374,6 +377,7 @@ Sieve Language
 * Comparators::
 * Tests::
 * Actions::
+* Extensions::
 * GNU Extensions::
 
 Syntax
@@ -398,6 +402,21 @@ Actions
 * Built-in Actions::
 * External Actions::
 
+Extensions
+
+* encoded-character::
+* relational::
+* variables::
+* environment::
+* numaddr::
+* editheader::
+* list::
+* moderator::
+* pipe::
+* spamd::
+* timestamp::
+* vacation::
+
 Date Input Formats
 
 * General date syntax::            Common rules.
diff --git a/doc/texinfo/programs/mail.texi b/doc/texinfo/programs/mail.texi
index 6e00933b1..52b91835f 100644
--- a/doc/texinfo/programs/mail.texi
+++ b/doc/texinfo/programs/mail.texi
@@ -5,30 +5,30 @@
 @pindex mail
 @UNREVISED
 
-@command{Mail} is an enhanced version of standard @command{/bin/mail} program.
-As well as its predecessor, it can be used either in sending mode or
-in reading mode.  @command{Mail} enters sending mode when one or more
-email addresses were specified in this command line.  In this mode the
-program waits until user finishes composing the message, then attempts
-to send it to the specified addresses and exits.
-See @ref{Composing Mail}, for a detailed description of this behavior.
+@command{Mail} is an enhanced version of POSIX @command{mailx} program.
+The program operates in two modes: @dfn{read} and @dfn{send}.
+
+@command{Mail} enters @dfn{send} mode when at least one email address
+was specified in its command line.  In this mode the program waits
+until user finishes composing the message, then attempts to send it to
+the specified addresses and exits. @xref{Composing Mail}, for a
+detailed description of this behavior.
 
 If the command line contained no email addresses, @command{mail} switches
-to reading mode.  In this mode it allows to read and manipulate the
-contents of the user system mailbox.  The @option{--file} (@option{-f})
-command line option allows to specify another mailbox name.  For more
-detail, see @ref{Reading Mail}.
+to reading mode.  In this mode it allows the user to read and manipulate the
+contents of the user system mailbox.  Use the @option{--file} (@option{-f})
+option to specify another mailbox name.  For more detail, see
+@ref{Reading Mail}.
 
-In addition to the Mailutils configuration file, @command{mail} loads
+In addition to the Mailutils configuration file, @command{mail} reads
 the traditional @samp{mailrc}-style configuration files.  @xref{Mail
 Configuration Files}, for a detailed description of their format.
 
 @menu
 * Invoking Mail::            Command Line Options.
-* Specifying Messages::      How to Specify Message Sets.
+* Reading Mail::             Reading Mail.
 * Composing Mail::           Composing Mail.
 * MIME::                     How to Attach Files.
-* Reading Mail::             Reading Mail.
 * Scripting::                Scripting.
 * Mail Variables::           How to Alter the Behavior of @command{mail}.
 * Mail Configuration Files:: Personal and System-wide Configuration Files.
@@ -42,6 +42,7 @@ General usage of @command{mail} program is:
 @example
       mail [@var{option}...] [@var{address}...]
 @end example
+
 @noindent
 If [@var{address}...] part is present, @command{mail} switches to
 mail sending mode, otherwise it operates in mail reading mode.
@@ -199,661 +200,6 @@ with @var{spool_path} being the full path to your mailspool directory
 The program also understands the common mailutils options
 (@pxref{Common Options}. 
 
-@node Specifying Messages
-@subsection How to Specify Message Sets
-
-Many mail commands such as print and delete can be given a @dfn{message list}
-to operate upon.  Wherever the message list is omitted, the command
-operates on the current message.
-
-The @dfn{message list} in its simplest form is one of:
-
-@table @asis
-@item .
-Selects current message.  It is equivalent to empty message list.
-@item *
-Selects all messages in the mailbox.
-@item ^
-Selects first non-deleted message.
-@item $
-Selects last non-deleted message.
-@end table
-
-In its complex form, the @dfn{message list} is a comma or whitespace-separated
-list of @dfn{message specifiers}.  A @dfn{message specifier} is one
-of
-
-@table @asis
-@item Message Number
-This specifier addresses the message with the given ordinal number
-in the mailbox.
-@item Message range
-@dfn{Message range} is specified as two message numbers separated by
-a dash.  It selects all messages with the number lying within that range.
-@item Attribute specifier
-An @dfn{Attribute specifier} is a colon followed by a single
-letter.  The @dfn{Attribute specifier} addresses all messages in the
-mailbox that have the given attribute.  These are the valid attribute
-specifiers:
-
-@table @samp
-@item :d
-Selects all deleted messages.
-@item :n
-Selects all recent messages, i.e. the messages that have neither been
-read nor seen so far.
-@item :o
-Selects all messages that have been seen.
-@item :r
-Selects all messages that have been read.
-@item :u
-Selects all messages that have @emph{not} been read.
-@item :t
-Selects all tagged messages.
-@item :T
-Selects all untagged messages.
-@end table
-@item Header match
-The @dfn{header match} is a string in the form:
-
-@example
-[@var{header}:]/@var{string}/
-@end example
-@noindent
-
-It selects all messages that contain header field @var{header} matching
-given @var{string}.  If the variable @code{regex} is set, the
-@var{string} is assumed to be a POSIX regexp. (All comparison is
-case-insensitive in either case).
-
-If @var{header}: part is omitted, it is assumed to be @samp{Subject:}.
-@item Message body match
-The @dfn{message body match} is a string in the form:
-
-@example
-:/@var{string}/
-@end example
-@noindent
-
-It selects all messages whose body matches the string.  The matching
-rules are the same as described under ``Header match''.
-@end table
-
-A @dfn{message specifier} can be followed by @dfn{message part
-specifier}, enclosed in a pair of brackets.  A @dfn{message part
-specifier} controls which part of a message should be operated upon.
-It is meaningful only for multipart messages.  A @dfn{message part
-specifier} is a comma or whitespace - separated list of part numbers
-or ranges.  Each part number can in turn be @dfn{message part specifier},
-thus allowing for operating upon multiply-encoded messages.
-
-The following are the examples of valid message lists:
-
-@node Composing Mail
-@subsection Composing Mail
-
-You can compose the message by simply typing the contents of it, line
-by line.  But usually this is not enough, you would need to edit
-your text, to quote some messages, etc.  @command{Mail} provides these
-capabilities through @dfn{compose escapes}.  The @dfn{compose escapes}
-are single-character commands, preceded by special @dfn{escape character},
-which defaults to @samp{~}.  The combination @code{escape character + command}
-is recognized as a compose escape only if it occurs at the beginning of
-a line.  If the escape character must appear at the beginning of a
-line, enter it twice.
-The actual escape character may be changed by setting the value of
-@code{escape} mail variable (@pxref{Mail Variables}).
-
-@menu
-* Quitting Compose Mode::
-* Getting Help on Compose Escapes::
-* Editing the Message::
-* Modifying the Headers::
-* Enclosing Another Message::
-* Adding a File to the Message::
-* Attaching a File to the Message::
-* Printing And Saving the Message::
-* Signing the Message::
-* Printing Another Message::
-* Inserting Value of a Mail Variable::
-* Executing Other Mail Commands::
-* Executing Shell Commands::
-@end menu
-
-@node Quitting Compose Mode
-@subsubsection Quitting Compose Mode
-@kyindex ~., mail escape
-@kyindex ~x, mail escape
-
-There are several commands allowing you to quit the compose mode.
-
-Typing the end-of-file character (@samp{C-D}) on a line alone finishes
-compose mode and sends the message to its destination.  The @samp{C-D}
-character looses its special meaning if @code{ignoreeof} mail variable
-is set.
-
-If mail variable @code{dot} is set, typing dot (@samp{.}) on a line
-alone achieves the same effect as @samp{C-D} above.
-
-Finally, using @samp{~.} escape always quits compose mode and sends
-out the composed message.
-
-To abort composing of a message without sending it, type interrupt
-character (by default, @samp{C-C}) twice.  This behavior is disabled
-when mail variable @code{ignore} is set.  In this case, you can use
-@samp{~x} escape to achieve the same effect.
-
-@node Getting Help on Compose Escapes
-@subsubsection Getting Help on Compose Escapes: ~?
-@kyindex ~?, mail escape
-
-The @samp{~?} escape prints on screen a brief summary of the available
-compose escapes.  @emph{Please note}, that @samp{~h} escape prompts
-for changing the header values, and does @emph{not} give help.
-
-@node Editing the Message
-@subsubsection Editing the Message: ~e and ~v
-@kyindex ~e, mail escape
-@kyindex ~v, mail escape
-
-If you are not satisfied with the message as it is, you can edit it
-using a text editor specified either by @code{EDITOR} or by
-@code{VISUAL} environment variables.  The @samp{~e} uses the former,
-and @samp{~v} uses the latter.
-
-By default both escapes allow you to edit only the body of the
-message.  However, if the @code{editheaders} variable is set,
-@command{mail} will load into the editor the complete text of
-the message with headers included, thus allowing you to change
-the headers as well.
-
-@node Modifying the Headers
-@subsubsection Modifying the Headers: ~h, ~t, ~c, ~b, ~s
-
-@cindex ~t, mail escape
-To add new addresses to the list of message recipients, use @samp{~t}
-command, e.g.:
-
-@example
-~t name1@@domain.net name2
-@end example
-
-@cindex ~c, mail escape
-@cindex ~b, mail escape
-To add addresses to @code{Cc} or @code{Bcc}, use @samp{~c} or @samp{~b}
-escapes respectively.
-
-@cindex ~s, mail escape
-To change the @code{Subject} header, use @samp{~s} escape, e.g.:
-
-@example
-~s "Re: your message"
-@end example
-
-@cindex ~h, mail escape
-Finally, to edit all headers, type @samp{~h} escape.  This will present
-you with the values of @code{To}, @code{Cc}, @code{Bcc}, and
-@code{Subject} headers allowing to edit them with normal text editing
-commands.
-
-@node Enclosing Another Message
-@subsubsection Enclosing Another Message: ~m and ~M
-@kyindex ~m, mail escape
-@kyindex ~M, mail escape
-
-If you are sending mail from within mail command mode, you can enclose
-the contents of any message sent to you by using @samp{~m} or @samp{~M}
-commands.  Typing @samp{~m} alone will enclose the contents of the
-current message, typing @samp{~m 12} will enclose the contents of
-message #12 and so on.
-
-The @samp{~m} uses retained and ignored lists when enclosing headers,
-the @samp{~M} encloses all header fields.
-
-In both cases, the contents of @code{indentprefix} mail variable is
-prepended to each line enclosed.
-
-@node Adding a File to the Message
-@subsubsection Adding a File to the Message: ~r and ~d
-
-@cindex ~r, mail escape
-@cindex ~<, mail escape
-To append the contents of file @var{filename} to the message, type
-
-@example
-~r @var{filename}
-@end example
-@noindent
-or
-
-@example
-~< @var{filename}
-@end example
-@noindent
-
-@cindex ~d, mail escape
-The @samp{~d} escape is a shorthand for
-
-@example
-~r dead.letter
-@end example
-
-@node Attaching a File to the Message
-@subsubsection Attaching a File to the Message
-@cindex ~+, mail escape
-The @samp{~+} escape attaches a file to the message.  It takes one to
-three arguments.  The first argument supplies the name of the file to
-attach:
-
-@example
-~+ myfile.txt
-@end example
-
-The file will be attached with default content-type
-@samp{application/octet-stream}, and encoding @samp{base64}
-(these can be altered by the @option{--content-type} and
-@option{--encoding} command line options, correspondingly).
-
-Optional second argument defines the content type to be used instead
-of the default one.  Optional third argument defines the encoding,
-e.g.:
-
-@example
-~+ myfile.html text/html base64
-@end example
-
-@cindex ~l, mail escape
-To list the files attached so far, use the @samp{~l} escape:
-
-@example
-~l
-multipart/mixed
-   1 myfile.html text/html base64
-@end example
-
-The first line of the output shows the content type of the message.
-Each subsequent line contains the ordinal number of the attachment,
-the name of the file, content-type and transfer encoding used.
-
-@cindex ~/, mail escape
-The @samp{~/} escape toggles the content type bewteen
-@samp{multipart/mixed}, and @samp{multipart/alternative}.  The new
-value of the content type is displayed on the screen.
-
-@cindex ~^, mail escape
-The @samp{~^} escape removes attachments.  Its argument is the number
-of the attachment to remove, e.g.:
-
-@example
-~^ 1
-@end example
-
-@node Printing And Saving the Message
-@subsubsection Printing And Saving the Message
-@kyindex ~p, mail escape
-@kyindex ~w, mail escape
-
-The @samp{~p} escape types the contents of the message entered so far,
-including headers, on your terminal.  You can save the message to
-an arbitrary file using @samp{~w} escape.  It takes the filename as its
-argument.
-
-@node Signing the Message
-@subsubsection Signing the Message: ~a and ~A
-@kyindex ~a, mail escape
-@kyindex ~A, mail escape
-
-To save you the effort of typing your signature at the end of each
-message, you can use @samp{~a} or @samp{~A} escapes.  If your signature
-occupies one line only, save it to the variable @code{sign} and use
-@samp{~a} escape to insert it.  Otherwise, if it is longer than one
-line, save it to a file, store the name of this file in the
-variable @code{Sign}, and use @samp{~A} escape to insert it into
-the message.
-
-@node Printing Another Message
-@subsubsection Printing Another Message: ~f and ~F
-@kyindex ~f, mail escape
-@kyindex ~F, mail escape
-
-Sometimes it is necessary to view the contents of another message,
-while composing.  These two escapes allow it.  Both take the message
-list as their argument.  If they are used without argument, the
-contents of the current message is printed.  The difference between
-@samp{~f} and @samp{~F} is that the former uses ignored and retained
-lists to select headers to be displayed, whereas the latter prints
-all headers.
-
-@node Inserting Value of a Mail Variable
-@subsubsection Inserting Value of a Mail Variable: ~i
-@kyindex ~i, mail escape
-
-The @samp{~i} escape enters the value of the named mail variable into
-the body of the message being composed.
-
-@node Executing Other Mail Commands
-@subsubsection Executing Other Mail Commands: ~: and ~-
-@kyindex ~:, mail escape
-@kyindex ~-, mail escape
-
-You can execute a mail command from within compose mode using @samp{~:}
-or @samp{~-} escapes.  For example, typing
-
-@example
-~: from :t
-@end example
-@noindent
-
-will display the from lines of all tagged messages.  Note, that executing
-mail-sending commands from within the compose mode is not allowed.
-An attempt to execute such a command will result in diagnostic message
-``Command not allowed in an escape sequence'' being displayed.
-Also, when starting compose mode immediately from the shell
-(e.g. running @samp{mail address@@domain}), most mail commands are
-meaningless, since there is no mailbox to operate upon.  In this case,
-the only commands that can reasonably be used are: @code{alias},
-@code{unalias}, @code{alternate}, @code{set}, and @code{unset}.
-
-@node Executing Shell Commands
-@subsubsection Executing Shell Commands: ~! and ~|
-@kyindex ~!, mail escape
-@kyindex ~|, mail escape
-
-The @samp{~!} escape executes specified command and returns you to
-@command{mail} compose mode without altering your message.  When used without
-arguments, it starts your login shell.  The @samp{~|} escape pipes the
-message composed so far through the given shell command and replaces the
-message with the output the command produced.  If the command produced
-no output, @command{mail} assumes that something went wrong and retains
-the old contents of your message.
-
-@c *********************************************************************
-
-@node MIME
-@subsection Composing Multipart Messages
-
-Multipart messages (or MIME, for short) can be used to send text in
-character set other than ASCII, attach non-text files, send multiple
-parts in alternative formats, etc.
-
-Technically speaking, the boolean variable @code{mime}
-controls this feature.  If it is set (@pxref{Setting and Unsetting
-the Variables}), @command{MIME} will create MIME messages by default.
-The variable can be set in the global or user configuration file
-(@pxref{Mail Configuration Files}), using the following command:
-
-@example
-set mime
-@end example
-
-It can also be set from the command line, using the @option{--mime}
-option.
-
-GNU @command{mail} automatically turns on the MIME mode, when it is
-requested to send a non-plaintext message, or a message in character
-set other than ASCII, when the encoding is specified, or when
-attachments are given.
-
-To send a message in another character set, specify it with the
-@option{--content-type} option:
-
-@example
-mail --content-type 'text/plain; charset=utf-8'
-@end example
-
-The @option{--encoding} specifies the encoding to use:
-
-@example
-mail --content-type 'text/plain; charset=utf-8' --encoding=base64
-@end example
-
-Its argument is any encoding supported by GNU mailutils.  The two most
-often used encodings are @samp{base64} and @samp{quoted-printable}.
-
-To specify the charset from @command{mail} interactive section, enable
-the ``edit headers'' mode (@code{set editheaders}) and add the
-needed @code{Content-Type} header manually.
-
-GNU @command{mail} also gives you a possibility to attach files to the
-message being sent.
-
-The simplest way to attach a file from command line is by using the
-@option{--attach} (@option{-A}) option.  Its argument specifies the
-file to attach.  For example, the following will attach the content
-of the file @file{archive.tar}:
-
-@example
-$ mail --attach=archive.tar
-@end example
-
-By default, the content type will be set to
-@samp{application/octet-stream}, and the attachment will be encoded
-using the @samp{base64} encoding.  To change the content type, use the
-@option{--content-type} option.  For example, to send an HTML
-attachment:
-
-@example
-$ mail --content-type=text/html --attach=in.html
-@end example
-
-The @option{--content-type} option affects all @option{--attach}
-options that follow it, and the message body (if any).  To change the
-content type, simply add another @option{--content-type} option.  For
-example, to send both the HTML file and the archive:
-
-@example
-$ mail --content-type=text/html --attach=in.html \
-       --content-type=application/x-tar --attach=archive.tar
-@end example
-
-Similarly, the encoding to use is set up by the @option{--encoding}
-option.  As well as @option{--content-type}, this option affects all
-attachments supplied after it in the command line as well as the
-message body read from the standard input, until changed by
-the eventual next instance of the same option.  Extending the above
-example:
-
-@example
-$ mail --content-type=text/html --encoding=quoted-printable \
-       --attach=in.html \
-       --content-type=application/x-tar --encoding=base64 \
-       --attach=archive.tar
-@end example
-
-Each attachment can also be assigned a @dfn{description} and a
-@dfn{file name}.  Normally, these are the same as the file name
-supplied with the @option{--attach} option.  However, you can change
-either or both of them using the @option{--content-name} and
-@option{--content-filename}, correspondingly.  Both of these options
-affect only the next @option{--attach} (or @option{--attach-fd}, see
-below) option.
-
-By default, the message will be assigned the content type
-@samp{multipart/mixed}.  To change it to @samp{multipart/alternative},
-use the @option{--alternative} command line option.  Using this option
-also sets the @samp{Content-Disposition} header of each attached
-message to @samp{inline}.
-
-All the examples above will enter the usual interactive shell,
-allowing you to compose the body of the message.  If that's not
-needed, the non-interactive use can be forced by redirecting
-@file{/dev/null} to the standard input, e.g.:
-
-@example
-$ mail --attach=archive.tar < /dev/null
-@end example
-
-This will normally produce a message saying:
-
-@example
-mail: Null message body; hope that's ok
-@end example
-
-To suppress this message, unset the @samp{nullbodymsg} variable,
-as shown in the example below:
-
-@example
-$ mail -E 'set nonullbodymsg' --attach=archive.tar < /dev/null
-@end example
-
-The option @option{--attach=-} forces @command{mail} to read the file
-to be attached from the standard input stream.  This option disables
-the interactive mode and sets @samp{nonullbodymsg} implicitly, so that
-the above example can be rewritten as:
-
-@example
-$ mail --attach=- < archive.tar
-@end example
-
-Special option is provided to facilitate the use of @command{mail}
-in scripts.  The @option{--attach-fd=@var{N}} instructs the program to
-read the data to be attached from the file descriptor @var{N}.  The
-above example is equivalent to:
-
-@example
-$ mail --attach-fd=0 < archive.tar
-@end example
-
-Attachments created with this option have neither filename nor 
-description set, so normally the use of @option{--content-name} and/or
-@option{--content-filename} is advised.
-
-The option @option{--skip-empty-attachments} instructs @command{mail}
-to skip creating attachments that would have zero-size body.  This
-option affects all attachments created by @option{--attach} and
-@option{--attach-fd} options appearing after it in the command line.
-It also affects the handling of the original message body.  To cancel
-its effect, use the @option{--no-skip-empty-attachments} option. 
-
-Here are some examples illustrating how it works.
-
-First, consider the following command line
-
-@example
-$ mail --attach=archive.tar </dev/null
-@end example
-
-Assume that @file{archive.tar} is not empty.
-
-This will create a MIME message of two parts: the first part having
-@samp{text/html} type and empty body, and the second part of type
-@samp{application/octet-stream}, with the content copied from the file
-@file{archive.tar}.
-
-Now, if you do:
-
-@example
-$ mail --attach=archive.tar --skip-empty-attachments </dev/null
-@end example
-
-@noindent
-then the created MIME message will contain only one part: that
-containing @file{archive.tar}.
-
-If the file @file{archive.tar} has zero length, the resulting archive
-will still contain the @samp{application/octet-stream} part of zero
-length.  However, if you place the @option{--skip-empty-attachments}
-option before @option{--attach}, then the produced message will be empty.
-
-The following Perl program serves as an example of using
-@command{mail} from a script to construct a MIME message on the fly.
-It scans all mounted file systems for executable files that have
-setuid or setgid bits set and reports the names of those files in
-separate attachments.  Each attachment is named after the mountpoint
-it describes.
-
-The script begins with the usual prologue stating the modules that
-will be used:
-
-@example
-#!/usr/bin/perl
-
-use strict;
-use autodie;
-@end example
-
-Then global variables are declared.  The @samp{@@rcpt} array contains
-the email addresses of the recipients:
-
-@example
-my @@rcpt= 'root@@example.com';
-@end example
-
-The @samp{@@cmd} variable holds the @command{mail} command line.  It
-will be augmented for each file system.  The initial value is set as
-follows:
-
-@example
-my @@cmd = ('mail',
-           '-E set nonullbodymsg',
-           '--content-type=text/plain');
-@end example
-
-The @command{find} utility will be used to locate the files.  The
-script will start as many instances as there are mountpoints.  Those
-instances will be run in parallel and their standard output streams
-will be connected to file descriptors passed to @command{mail}
-invocation in @option{--attach-fd} options.
-
-The descriptors will be held in @samp{@@fds} array.  This will prevent
-them from being wiped out by the garbage collector.  Furthermore, care
-should be taken to ensure that the @code{O_CLOEXEC} flag be not set
-for these descriptors.  This sample script takes a simplistic approach:
-it instructs Perl not to close first 255 descriptors when executing
-another programs:
-
-@example
-my @@fds;
-$^F = 255;
-@end example
-
-The following code obtains the list of mount points:
-
-@example
-open(my $in, '-|', 'mount -t nonfs,noproc,nosysfs,notmpfs');
-while (<$in>) @{
-    chomp;
-    if (/^\S+ on (?<mpoint>.+) type (?<fstype>.+) /) @{
-@end example
-
-For each mountpoint, the @command{find} command line is constructed
-and launched.  The file descriptor is pushed to the @samp{@@fds} array
-to prevent it from being collected by the garbage collector:
-
-@example
-	open(my $fd, '-|',
-	     "find $+@{mpoint@} -xdev -type f"
-             . " \\( -perm -u+x -o -perm -g+x -o -perm -o+x \\)"
-             . " \\( -perm -u+s -o -perm -g+s \\) -print");
-	push @@fds, $fd;
-@end example
-
-Now, the @command{mail} command is instructed to create next
-attachment from that file descriptor:
-
-@example
-        my $mpname = $+@{mpoint@};
-        $mpname =~ tr@{/@}@{%@}; 
-        push @@cmd,
-             "--content-name=Set[ug]id files on $+@{mpoint@} (type $+@{fstype@})",
-             "--content-filename=$mpname.list",
-             '--attach-fd=' . fileno($fd);
-    @}
-@}
-close $in;
-@end example
-
-Finally, the emails of the recipients are added to the command line,
-the standard input is closed to make sure @command{mail} won't enter
-the interactive mode and the constructed command is executed:
-
-@example
-push @@cmd, @@rcpt;
-close STDIN;
-system(@@cmd);
-@end example
-
-
 @c *********************************************************************
 
 @node Reading Mail
@@ -864,18 +210,22 @@ invoking @command{mail}:
 
 @table @code
 @item mail
-To read messages from your system mailbox.
+Read messages from your system mailbox.
+
 @item mail -f
 @itemx mail --file
-To read messages from your mailbox (@file{$HOME/mbox}).  If the
+
+Read messages from your mailbox (@file{$HOME/mbox}).  If the
 @option{--user} option (see below) is also given, read messages
 from that user's @file{mbox}.
+
 @item mail -f @var{path_to_mailbox}
 @itemx mail --file @var{path_to_mailbox}
-To read messages from the specified mailbox.
+Read messages from the specified mailbox.
+
 @item mail -u @var{user}
 @itemx mail --user=@var{user}
-To read messages from the system mailbox belonging to @var{user}.
+Read messages from the system mailbox belonging to @var{user}.
 @end table
 
 @emph{Please note}, that usual mailbox permissions won't allow you
@@ -904,14 +254,83 @@ $ mail --file=mymbox -i -n
 
 Unless you have started mail with @option{--norc} command line option,
 it will read the contents of the system-wide configuration file.
-Then it reads the contents of user configuration file, if any.
+Then it will read the contents of user configuration file, if it exists.
 For detailed description of these files, see @ref{Mail Configuration Files}.
 After this initial setup, @command{mail} displays the first page of header
-lines and enters interactive mode.  In interactive mode, @command{mail}
-displays its prompt (@samp{?}, if not set otherwise) and executes the
-commands the user enters.
+lines (unless the @option{-N} option has been given), followed by a prompt,
+indicating that it is waiting for regular commands.  Upon receiving a
+command, @command{mail} parses and executes it, displays the result on
+the screen, prints the prompt and waits for the next command.  This
+process is continued until @command{mail} receives any of the commands
+@samp{quit}, @samp{exit} or the end-of-file character (ASCII 4, or
+@kbd{C-D}).
+
+Each message in the mailbox has a state that affects how it is
+retained or deleted upon termination of the program.  The state is
+reflected in the header listing and can be changed during the session.
+The states are:
+
+@table @dfn
+@item new
+The message is present in the system mailbox and has not been read
+by the user or moved to any other state.  When @command{mail}
+terminates, messages in this state are retained in the system
+mailbox.  If @command{mail} was exited using the @code{quit} command,
+such messages are moved to the @samp{unread} state.  If @code{exit}
+command was used, their state is not changed.
+
+@item unread
+The message has been present in the system mailbox for more than one
+invocation of @command{mail} and has not been read by the user or
+moved to any other state.  When @command{mail} terminates, messages in
+this state are retained in the system mailbox.
+
+@item read
+The message has been read by the user, i.e. processed by one of the
+following commands: @code{copy}, @code{mbox}, @code{next},
+@code{pipe}, @code{prev}, @code{print}, @code{Print}, @code{struct},
+@code{top}, @code{type}, @code{Type}, @code{undelete}, or any of the
+following escapes (in message compose mode): @code{~f}, @code{~m},
+@code{~F}, @code{~M}.
+
+When @command{mail} terminates, messages in this state are handled
+depending on the mailbox they are in.  Read messages in the system
+mailbox are saved in the @samp{mbox}, unless the internal variable
+@samp{hold} is set.  Read messages in @samp{mbox} or in any other
+mailbox, excepting the system one, will be retained in their current
+location. 
+
+@item deleted
+The message has been processed by one of the following commands:
+@samp{delete}, @samp{dp}, @samp{dt}.  Messages in this state are
+ignored by any command, excepting @samp{undelete}, which changes their
+state back to @samp{read}.  Upon quitting the program, deleted
+messages are permanently removed from the mailbox.
+
+@item preserved
+The message has been processed by the @code{preserve} (@code{hold})
+command.  When @command{mail} quits, such messages are retained in
+the mailbox.
+
+@item saved
+The message has been processed by one of the following commands:
+@code{save}, @code{write}.  When @command{mail} quits, saved messages
+will be removed from the mailbox, unless the @samp{keepsave} variable
+is set.  When operating on the system mailbox, messages in this state
+are deleted, when the @command{quit} or @command{file} command is used
+to exit the current mailbox.
+@end table
+
+Unless the mailbox is empty, exactly one of its messages will be
+marked as @dfn{current message}.  Upon startup, current message is
+set to the first new message, if there is any, or the first unread
+message if there is any, or to the first message in the mailbox.  In
+the header listing, current message is marked with the @samp{>} sign
+at the beginning of the line.  Current message is changed by any of
+the following commands: @samp{dp}, @samp{prev}, @samp{next}.
 
 @menu
+* Command Syntax::           Syntax of mail internal commands.
 * Quitting the Program::
 * Obtaining Online Help::
 * Moving Within a Mailbox::
@@ -931,6 +350,120 @@ commands the user enters.
 @end menu
 
 @c **********************************
+@node Command Syntax
+@subsubsection Syntax of mail internal commands
+
+Commands have the following syntax:
+
+@example
+@var{command} [@var{msglist}] [@var{argument} ...]
+@end example
+
+A command is terminated by a newline character.  Empty command (i.e. a
+newline character alone) is equivalent to @samp{next} (@pxref{Moving
+Within a Mailbox, next}).
+
+In the syntax above, @var{command} is the command verb.  Each command
+has long and short (abbreviated) form.  Each of them can be used to
+invoke the command. 
+
+@anchor{Specifying Messages}
+@anchor{message list}
+Many mail commands take a list of messages (@var{msglist}) to operate
+upon, which defaults to current message.
+
+The list of messages in its simplest form is one of:
+
+@multitable @columnfractions 0.2 0.7
+@item .  @tab Selects current message.  It is equivalent to empty message list.
+@item *  @tab Selects all messages in the mailbox.
+@item ^  @tab Selects first non-deleted message.
+@item $  @tab Selects last non-deleted message.
+@end multitable
+
+In its complex form, the @dfn{message list} is a comma or whitespace-separated
+list of @dfn{message specifiers}.  A @dfn{message specifier} is one
+of
+
+@table @asis
+@item @var{n}
+(integer number)
+This specifier addresses the message with the given ordinal number
+in the mailbox.
+
+@item @var{n}-@var{m}
+All messages with ordinal numbers between @var{n} and @var{m}, inclusive.
+
+@item :@var{t}
+All messages of type @var{t}, where @var{t} can be any of:
+
+@table @samp
+@item d
+Deleted messages.
+@item :n
+New messages.
+@item :o
+Old messages (any message not in state @samp{read} or @samp{new}).
+@item :r
+Messages in state @samp{read}.
+@item :u
+Messages in state @samp{unread}.
+@item :t
+Selects all tagged messages.
+@item :T
+Selects all untagged messages.
+@end table
+
+@item [@var{header}:]/@var{string}[/]
+Header match.
+
+Selects all messages that contain header field @var{header} matching
+given @var{string}.  If the variable @code{regex} is set, the
+@var{string} is assumed to be a POSIX regexp. (All comparison is
+case-insensitive in either case).
+
+If @var{header}: part is omitted, it is assumed to be @samp{Subject:}.
+
+@item :/@var{string}[/]
+Message body match.
+
+Selects all messages with body matching the @var{string}.  The matching
+rules are the same as described above.
+@end table
+
+A @dfn{message specifier} can be followed by @dfn{message part
+specifier}, enclosed in a pair of brackets.  A @dfn{message part
+specifier} controls which part of a message should be operated upon.
+It is meaningful only for multipart messages.  A @dfn{message part
+specifier} is a comma or whitespace-separated list of part numbers
+or ranges.  Each part number can in turn be @dfn{message part specifier},
+thus allowing for operating upon multiply-encoded messages.
+
+The following are the examples of valid message lists:
+
+@table @asis
+@item 3
+Third message.
+
+@item 1-4 10
+Messages from 1 through 4 and message 10.
+
+@item 4-*