Document pattern groups in the manual

Sync with muttrc. Add some rationale for groups. Fix some style issues.
Fix quoting issue with $smtp_authenticators.

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 5e6af5dd02e19a201c4c0a73c18eb9cd89a7faab..c60f496e2f4f650d1ce8770476707aec181d5c7c 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -1523,11 +1523,56 @@ For a complete list, see the <link linkend="commands">command reference</link>.
 
 </sect1>
 
+<sect1 id="addrgroup">
+<title>Address groups</title>
+
+<para>
+Usage: <literal>group</literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; &lsqb; <literal>-rx</literal> <emphasis>EXPR</emphasis> &lsqb; ... &rsqb; &rsqb; &lsqb; <literal>-addr</literal> <emphasis>EXPR</emphasis> &lsqb; ... &rsqb; &rsqb;
+</para>
+
+<para>
+<literal>group</literal> is used to directly add either addresses or
+regular expressions to the specified group or groups. The different
+categories of arguments to the <literal>group</literal> command can be
+in any order. The flags <literal>-rx</literal> and
+<literal>-addr</literal> specify what the following strings (that cannot
+begin with a hyphen) should be interpreted as: either a regular
+expression or an email address, respectively.
+</para>
+
+<para>
+These address groups can also be created implicitely by the
+<link linkend="alias">alias</link>, <link linkend="lists">lists</link>,
+<link linkend="lists">subscribe</link> and
+<link linkend="alternates">alternates</link> commands by specifying the
+optional <literal>-group</literal> option.
+</para>
+
+<para>
+Once defined, these address groups can be used in
+<link linkend="patterns">patterns</link> to search for and limit the
+display to messages matching a group.
+</para>
+
+<para>
+Usage: <literal>ungroup</literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; &lsqb; * | &lsqb; &lsqb; <literal>-rx</literal> <emphasis>EXPR</emphasis> &lsqb; ... &rsqb; &rsqb; &lsqb; <literal>-addr</literal> <emphasis>EXPR</emphasis> &lsqb; ... &rsqb; &rsqb; &rsqb;
+</para>
+
+<para>
+<literal>ungroup</literal> is used to remove addresses or regular
+expressions from the specified group or groups. The syntax is similar to
+the <literal>group</literal> command, however the special character
+<literal>*</literal> can be used to empty a group of all of its
+contents.
+</para>
+
+</sect1>
+
 <sect1 id="alias">
 <title>Defining/Using aliases</title>
 
 <para>
-Usage: <literal>alias</literal> <emphasis>key</emphasis> <emphasis>address</emphasis> &lsqb; , <emphasis>address</emphasis>, ... &rsqb;
+Usage: <literal>alias</literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; <emphasis>key</emphasis> <emphasis>address</emphasis> &lsqb; , <emphasis>address</emphasis>, ... &rsqb;
 </para>
 
 <para>
@@ -1537,8 +1582,14 @@ a short string to a full address.
 </para>
 
 <para>
-<emphasis role="bold">Note:</emphasis> if you want to create an alias for a group (by specifying more than
-one address), you <emphasis role="bold">must</emphasis> separate the addresses with a comma (``,'').
+<emphasis role="bold">Note:</emphasis> if you want to create an alias for more than
+one address, you <emphasis role="bold">must</emphasis> separate the addresses with a comma (``,'').
+</para>
+
+<para>
+The optional <literal>-group</literal> argument to
+<literal>alias</literal> causes the aliased address(es) to be added to
+the named <emphasis>group</emphasis>.
 </para>
 
 <para>
@@ -2286,7 +2337,7 @@ unignore posted-to:
 <title>Alternative addresses</title>
 
 <para>
-Usage: <literal>&lsqb;un&rsqb;alternates</literal> <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb;
+Usage: <literal>&lsqb;un&rsqb;alternates</literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb;
 
 </para>
 
@@ -2308,6 +2359,11 @@ expressions, each of which can identify an address under which you
 receive e-mail.
 </para>
 
+<para>
+The <literal>-group</literal> flag causes all of the subsequent regular expressions
+to be added to the named group.
+</para>
+
 <para>
 The <literal>unalternates</literal> command can be used to write exceptions to
 <literal>alternates</literal> patterns. If an address matches something in an
@@ -2332,8 +2388,8 @@ is ``*'', <emphasis>all entries</emphasis> on <literal>alternates</literal> will
 
 <para>
 <literallayout>
-Usage: <literal>&lsqb;un&rsqb;lists</literal> <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb;
-Usage: <literal>&lsqb;un&rsqb;subscribe</literal> <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb;
+Usage: <literal>&lsqb;un&rsqb;lists</literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb;
+Usage: <literal>&lsqb;un&rsqb;subscribe</literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb;
 </literallayout>
 </para>
 
@@ -2361,7 +2417,7 @@ command.  To mark it as subscribed, use ``subscribe''.
 You can use regular expressions with both commands.  To mark all
 messages sent to a specific bug report's address on mutt's bug
 tracking system as list mail, for instance, you could say
-``subscribe &lsqb;0-9]*@bugs.guug.de''.  Often, it's sufficient to just
+``subscribe &lsqb;0-9&rsqb;*@bugs.guug.de''.  Often, it's sufficient to just
 give a portion of the list's e-mail address.
 </para>
 
@@ -2379,6 +2435,11 @@ or ``subscribe ^mutt-users@mutt&bsol;&bsol;.org$'' to
 match only mail from the actual list.
 </para>
 
+<para>
+The <literal>-group</literal> flag adds all of the subsequent regular expressions
+to the named group.
+</para>
+
 <para>
 The ``unlists'' command is used to remove a token from the list of
 known and subscribed mailing-lists. Use ``unlists *'' to remove all
@@ -3607,15 +3668,20 @@ messages:
 <tbody>
 <row><entry>~A</entry><entry>all messages</entry></row>
 <row><entry>~b EXPR</entry><entry>messages which contain EXPR in the message body</entry></row>
+<row><entry>=b STRING</entry><entry>messages which contain STRING in the message body. If IMAP is enabled, searches for STRING on the server, rather than downloading each message and searching it locally.</entry></row>
 <row><entry>~B EXPR</entry><entry>messages which contain EXPR in the whole message</entry></row>
 <row><entry>~c EXPR</entry><entry>messages carbon-copied to EXPR</entry></row>
+<row><entry>%c GROUP</entry><entry>messages carbon-copied to any member of GROUP</entry></row>
 <row><entry>~C EXPR</entry><entry>message is either to: or cc: EXPR</entry></row>
+<row><entry>%C GROUP</entry><entry>message is either to: or cc: to any member of GROUP</entry></row>
 <row><entry>~d &lsqb;MIN&rsqb;-&lsqb;MAX&rsqb;</entry><entry>messages with ``date-sent'' in a Date range</entry></row>
 <row><entry>~D</entry><entry>deleted messages</entry></row>
 <row><entry>~e EXPR</entry><entry>message which contains EXPR in the ``Sender'' field</entry></row>
+<row><entry>%e GROUP</entry><entry>message which contain a member of GROUP in the ``Sender'' field</entry></row>
 <row><entry>~E</entry><entry>expired messages</entry></row>
 <row><entry>~F</entry><entry>flagged messages</entry></row>
 <row><entry>~f EXPR</entry><entry>messages originating from EXPR</entry></row>
+<row><entry>%f GROUP</entry><entry>messages originating from any member of GROUP</entry></row>
 <row><entry>~g</entry><entry>cryptographically signed messages</entry></row>
 <row><entry>~G</entry><entry>cryptographically encrypted messages</entry></row>
 <row><entry>~h EXPR</entry><entry>messages which contain EXPR in the message header</entry></row>
@@ -3623,6 +3689,7 @@ messages:
 <row><entry>~i EXPR</entry><entry>message which match EXPR in the ``Message-ID'' field</entry></row>
 <row><entry>~k</entry><entry>message contains PGP key material</entry></row>
 <row><entry>~L EXPR</entry><entry>message is either originated or received by EXPR</entry></row>
+<row><entry>%L GROUP</entry><entry>message is either originated or received by any member of GROUP</entry></row>
 <row><entry>~l</entry><entry>message is addressed to a known mailing list</entry></row>
 <row><entry>~m &lsqb;MIN&rsqb;-&lsqb;MAX&rsqb;</entry><entry>message in the range MIN to MAX *)</entry></row>
 <row><entry>~n &lsqb;MIN&rsqb;-&lsqb;MAX&rsqb;</entry><entry>messages with a score in the range MIN to MAX *)</entry></row>
@@ -5946,7 +6013,7 @@ The following are the commands understood by mutt.
 <listitem>
 
 <para>
-<literal><link linkend="alias">alias</link></literal> <emphasis>key</emphasis> <emphasis>address</emphasis> &lsqb; , <emphasis>address</emphasis>, ... &rsqb;
+<literal><link linkend="alias">alias</link></literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; <emphasis>key</emphasis> <emphasis>address</emphasis> &lsqb; , <emphasis>address</emphasis>, ... &rsqb;
 </para>
 </listitem>
 <listitem>
@@ -5958,7 +6025,7 @@ The following are the commands understood by mutt.
 <listitem>
 
 <para>
-<literal><link linkend="alternates">alternates</link></literal> <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb;
+<literal><link linkend="alternates">alternates</link></literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb;
 </para>
 </listitem>
 <listitem>
@@ -6072,7 +6139,7 @@ The following are the commands understood by mutt.
 <listitem>
 
 <para>
-<literal><link linkend="lists">lists</link></literal> <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb; 
+<literal><link linkend="lists">lists</link></literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb; 
 </para>
 </listitem>
 <listitem>
@@ -6228,7 +6295,7 @@ The following are the commands understood by mutt.
 <listitem>
 
 <para>
-<literal><link linkend="lists">subscribe</link></literal> <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb; 
+<literal><link linkend="lists">subscribe</link></literal> &lsqb; <literal>-group</literal> <emphasis>name</emphasis> &lsqb; ... &rsqb; &rsqb; <emphasis>regexp</emphasis> &lsqb; <emphasis>regexp</emphasis> ... &rsqb; 
 </para>
 </listitem>
 <listitem>

diff --git a/doc/muttrc.man.head b/doc/muttrc.man.head
index d709c4789a2790e960e839fa42f4d5fc0e2e6cd2..d269a058c59fb7fffcaec6746a2baa2f65280f57 100644 (file)
--- a/doc/muttrc.man.head
+++ b/doc/muttrc.man.head
@@ -87,13 +87,20 @@ added to the named \fIgroup\fP.
 .IP
 \fBgroup\fP is used to directly add either addresses or regular expressions to
 the specified group or groups. The different categories of arguments to the
-\fBgroup\fP command can be in any order. The flags \fB-rx\fP and \fB-addr\fP
+\fBgroup\fP command can be in any order. The flags \fI-rx\fP and \fI-addr\fP
 specify what the following strings (that cannot begin with a hyphen) should be
 interpreted as: either a regular expression or an email address, respectively.
 \fBungroup\fP is used to remove addresses or regular expressions from the
 specified group or groups. The syntax is similar to the \fBgroup\fP command,
 however the special character \fB*\fP can be used to empty a group of all of
 its contents.
+.IP
+These address groups can also be created implicitely by the \fBalias\fP, \fBlists\fP,
+\fBsubscribe\fP and \fBalternates\fP commands by specifying the optional \fI-group\fP
+option.
+.IP
+Once defined, these address groups can be used in patterns to search for and limit the
+display to messages matching a group.
 .PP
 .nf
 \fBalternates\fP [\fB-group\fP \fIname\fP] \fIregexp\fP [ \fB,\fP \fIregexp\fP [ ... ]]
@@ -439,14 +446,14 @@ messages which contain \fIEXPR\fP in the whole message.
 ~c \fIEXPR\fP
 messages carbon-copied to \fIEXPR\fP
 .TP
-%c \fIgroup\fP
-messages carbon-copied to any member of \fIgroup\fP
+%c \fIGROUP\fP
+messages carbon-copied to any member of \fIGROUP\fP
 .TP
 ~C \fIEXPR\fP
 messages either to: or cc: \fIEXPR\fP
 .TP
-%C \fIgroup\fP
-messages either to: or cc: to any member of \fIgroup\fP
+%C \fIGROUP\fP
+messages either to: or cc: to any member of \fIGROUP\fP
 .TP
 ~d \fIMIN\fP-\fIMAX\fP
 messages with \(lqdate-sent\(rq in a Date range
@@ -457,8 +464,8 @@ deleted messages
 ~e \fIEXPR\fP
 messages which contain \fIEXPR\fP in the \(lqSender\(rq field
 .TP
-%e \fIgroup\fP
-messages which contain a member of \fIgroup\fP in the \(lqSender\(rq field
+%e \fIGROUP\fP
+messages which contain a member of \fIGROUP\fP in the \(lqSender\(rq field
 .TP
 ~E
 expired messages
@@ -466,8 +473,8 @@ expired messages
 ~f \fIEXPR\fP
 messages originating from \fIEXPR\fP
 .TP
-%f \fIgroup\fP
-messages originating form any member of \fIgroup\fP
+%f \fIGROUP\fP
+messages originating form any member of \fIGROUP\fP
 .TP
 ~F
 flagged messages
@@ -496,8 +503,8 @@ messages addressed to a known mailing list (defined by either \fBsubscribe\fP or
 ~L \fIEXPR\fP
 messages either originated or received by \fIEXPR\fP
 .TP
-%L \fIgroup\fP
-messages either originated or received by any member of \fIgroup\fP
+%L \fIGROUP\fP
+messages either originated or received by any member of \fIGROUP\fP
 .TP
 ~m \fIMIN\fP-\fIMAX\fP
 message in the range \fIMIN\fP to \fIMAX\fP
@@ -567,6 +574,9 @@ duplicated messages (see $duplicate_threads)
 .TP
 ~$
 unreferenced message (requries threaded view)
+.TP
+~(PATTERN)
+messages in threads containing messages matching a certain pattern, e.g. all threads containing messages from you: ~(~P)
 .PD 1
 .DT
 .PP

diff --git a/init.h b/init.h
index 230479e1a59f62f1a9a38fa09c94398c76f69d7d..3ef28e0e6e21997b772201b2937d82ef39b1afbe 100644 (file)
--- a/init.h
+++ b/init.h
@@ -2620,7 +2620,7 @@ struct option_t MuttVars[] = {
    ** This is a colon-delimited list of authentication methods mutt may
    ** attempt to use to log in to an SMTP server, in the order mutt should
    ** try them.  Authentication methods are any SASL mechanism, eg
-   ** 'digest-md5', 'gssapi' or 'cram-md5'.
+   ** ``digest-md5'', ``gssapi'' or ``cram-md5''.
    ** This parameter is case-insensitive. If this parameter is unset
    ** (the default) mutt will try all available methods, in order from
    ** most-secure to least-secure.