Manual: better document what address groups are (for)

diff --git a/ChangeLog b/ChangeLog
index ed1f067871c75b56a45950483dac346914336b54..f9a4391fc4f8cda38f1b273242e83fe390550414 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2009-07-23 16:49 +0200  Rocco Rutte  <pdmef@gmx.net>  (77ac8b5c2be6)
+
+       * group.c, group.h, init.c, init.h, pattern.c, protos.h, rfc822.c,
+       rfc822.h: Implement ungroup command. Closes #3304.
+
+2009-07-23 16:40 +0200  Rocco Rutte  <pdmef@gmx.net>  (7c4484ba9e4b)
+
+       * init.c, mutt.h, muttlib.c: Move remove_from_rx_list() to muttlib.c,
+       name it mutt_remove_from_rx_list()
+
+2009-07-22 15:25 +0200  Fabian Groffen  <grobian@gentoo.org>  (d41e043fa775)
+
+       * keymap.c: Use CRYPT_BACKEND_GPGME instead of non-existent
+       HAVE_GPGME
+
 2009-07-22 14:43 +0200  kees  <kees@outflux.net>  (848f08512bf3)
 
        * hcache.c, rfc822.h: Properly restore addresses from hcache using

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 5a2390848a90d42b867d905c9e40c2eaba66b7ca..6010a2eb725b95154876d4e4e19f041728c8a212 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -1938,10 +1938,27 @@ expressions).</para></listitem>
 </cmdsynopsis>
 
 <para>
-<command>group</command> is used to directly add either addresses or
-regular expressions to the specified group or groups. The different
-categories of arguments to the <command>group</command> command can be
-in any order. The flags <literal>-rx</literal> and
+Mutt supports grouping addresses logically into named groups. An address
+or address pattern can appear in several groups at the same time. These
+groups can be used in patterns (for searching, limiting and tagging) and
+in hooks by using group patterns. This can be useful to classify mail
+and take certain actions depending on in what groups the message is.
+For example, the mutt user's mailing list would fit into the categories
+<quote>mailing list</quote> and <quote>mutt-related</quote>. Using <link
+linkend="send-hook"><literal>send-hook</literal></link>, the sender can
+be set to a dedicated one for writing mailing list messages, and the
+signature could be set to a mutt-related one for writing to a mutt list
+&mdash; for other lists, the list sender setting still applies but a
+different signature can be selected. Or, given a group only containing
+recipients known to accept encrypted mail,
+<quote>auto-encryption</quote> can be achieved easily.
+</para>
+
+<para>
+The <command>group</command> command is used to directly add either
+addresses or regular expressions to the specified group or groups. The
+different categories of arguments to the <command>group</command>
+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.
@@ -1950,23 +1967,36 @@ expression or an email address, respectively.
 <para>
 These address groups can also be created implicitly by the <link
 linkend="alias"><command>alias</command></link>, <link
-linkend="lists">lists</link>, <link linkend="lists">subscribe</link> and
-<link linkend="alternates"><command>alternates</command></link> commands
-by specifying the optional <literal>-group</literal> option.
+linkend="lists"><command>lists</command></link>, <link
+linkend="lists"><command>subscribe</command></link> and <link
+linkend="alternates"><command>alternates</command></link> commands by
+specifying the optional <literal>-group</literal> option. For example,
 </para>
 
+<screen>
+alternates -group me address1 address2
+alternates -group me -group work address3
+</screen>
+
 <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.
+would create a group named <quote>me</quote> which contains all your
+addresses and a group named <quote>work</quote> which contains only your
+work address <emphasis>address3</emphasis>. Besides many other
+possibilities, this could be used to automatically mark your own
+messages in a mailing list folder as read or use a special signature for
+work-related messages.
 </para>
 
 <para>
-<command>ungroup</command> is used to remove addresses or regular
-expressions from the specified group or groups. The syntax is similar to
-the <command>group</command> command, however the special character
-<literal>*</literal> can be used to empty a group of all of its
-contents.
+The <command>ungroup</command> command is used to remove addresses or
+regular expressions from the specified group or groups. The syntax is
+similar to the <command>group</command> command, however the special
+character <literal>*</literal> can be used to empty a group of all of
+its contents. As soon as a group gets empty because all addresses and
+regular expressions have been removed, it'll internally be removed, too
+(i.e. there cannot be an empty group). When removing regular expressions
+from a group, the pattern must be specified exactly as given to the
+<command>group</command> command or <literal>-group</literal> argument.
 </para>
 
 </sect1>