[PATCH] Document pattern groups in the manual
This patch is more or less copy'n'paste work to "sync" the manual
documentation on pattern groups with muttrc(5).
And while I'm at it, add some lines to muttrc(5) saying what these
groups are useful for. And while I'm at it, fix some style issues.
As reviewing the updated muttrc(5) revealed, there was a quoting issue
in init.h with the docs for $smtp_authenticators which is fixed, too.
---
doc/manual.xml.head | 89 ++++++++++++++++++++++++++++++++++++++++++++------
doc/muttrc.man.head | 32 ++++++++++++------
init.h | 2 +-
3 files changed, 100 insertions(+), 23 deletions(-)
diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 5e6af5d..c60f496 100644
--- 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> [ <literal>-group</literal>
<emphasis>name</emphasis> [ ... ] ] [
<literal>-rx</literal> <emphasis>EXPR</emphasis> [ ... ] ]
[ <literal>-addr</literal> <emphasis>EXPR</emphasis> [ ... ]
]
+</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> [ <literal>-group</literal>
<emphasis>name</emphasis> [ ... ] ] [ * | [ [
<literal>-rx</literal> <emphasis>EXPR</emphasis> [ ... ] ]
[ <literal>-addr</literal> <emphasis>EXPR</emphasis> [ ... ]
] ]
+</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> [ , <emphasis>address</emphasis>, ... ]
+Usage: <literal>alias</literal> [ <literal>-group</literal>
<emphasis>name</emphasis> [ ... ] ] <emphasis>key</emphasis>
<emphasis>address</emphasis> [ , <emphasis>address</emphasis>, ... ]
</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>[un]alternates</literal> <emphasis>regexp</emphasis>
[ <emphasis>regexp</emphasis> ... ]
+Usage: <literal>[un]alternates</literal> [
<literal>-group</literal> <emphasis>name</emphasis> [ ... ] ]
<emphasis>regexp</emphasis> [ <emphasis>regexp</emphasis> ... ]
</para>
@@ -2309,6 +2360,11 @@ 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
<literal>alternates</literal> command, but you nonetheless do not think it is
@@ -2332,8 +2388,8 @@ is ``*'', <emphasis>all entries</emphasis> on
<literal>alternates</literal> will
<para>
<literallayout>
-Usage: <literal>[un]lists</literal> <emphasis>regexp</emphasis>
[ <emphasis>regexp</emphasis> ... ]
-Usage: <literal>[un]subscribe</literal> <emphasis>regexp</emphasis>
[ <emphasis>regexp</emphasis> ... ]
+Usage: <literal>[un]lists</literal> [ <literal>-group</literal>
<emphasis>name</emphasis> [ ... ] ] <emphasis>regexp</emphasis>
[ <emphasis>regexp</emphasis> ... ]
+Usage: <literal>[un]subscribe</literal> [
<literal>-group</literal> <emphasis>name</emphasis> [ ... ] ]
<emphasis>regexp</emphasis> [ <emphasis>regexp</emphasis> ... ]
</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 [0-9]*@bugs.guug.de''. Often, it's sufficient to just
+``subscribe [0-9]*@bugs.guug.de''. Often, it's sufficient to just
give a portion of the list's e-mail address.
</para>
@@ -2380,6 +2436,11 @@ 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
tokens.
@@ -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 [MIN]-[MAX]</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 [MIN]-[MAX]</entry><entry>message in the
range MIN to MAX *)</entry></row>
<row><entry>~n [MIN]-[MAX]</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> [ , <emphasis>address</emphasis>, ... ]
+<literal><link linkend="alias">alias</link></literal> [
<literal>-group</literal> <emphasis>name</emphasis> [ ... ] ]
<emphasis>key</emphasis> <emphasis>address</emphasis> [ ,
<emphasis>address</emphasis>, ... ]
</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> [ <emphasis>regexp</emphasis> ... ]
+<literal><link linkend="alternates">alternates</link></literal> [
<literal>-group</literal> <emphasis>name</emphasis> [ ... ] ]
<emphasis>regexp</emphasis> [ <emphasis>regexp</emphasis> ... ]
</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> [ <emphasis>regexp</emphasis> ... ]
+<literal><link linkend="lists">lists</link></literal> [
<literal>-group</literal> <emphasis>name</emphasis> [ ... ] ]
<emphasis>regexp</emphasis> [ <emphasis>regexp</emphasis> ... ]
</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> [ <emphasis>regexp</emphasis> ... ]
+<literal><link linkend="lists">subscribe</link></literal> [
<literal>-group</literal> <emphasis>name</emphasis> [ ... ] ]
<emphasis>regexp</emphasis> [ <emphasis>regexp</emphasis> ... ]
</para>
</listitem>
<listitem>
diff --git a/doc/muttrc.man.head b/doc/muttrc.man.head
index d709c47..d269a05 100644
--- 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 230479e..3ef28e0 100644
--- 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.
--
1.5.0.3.920.g51d7f