- quilt/mail.in:

  + Add -m and --prefix options so that the mail command can be
    used without invoking an editor.
  + Verify that each message generated will have a unique subject.
  + Verify that the introduction has a subject header.
  + Fix a bug in the heuristic for adding recipients.
  + Add a heuristic for extracting subject headers
  + Clarify some messages.
  + Add a test case.
  + Update the documentation.

1 files changed, 46 insertions, 22 deletions

diff --git a/doc/README.MAIL b/doc/README.MAIL
index 08df3fd..517a593 100644
--- a/doc/README.MAIL
+++ b/doc/README.MAIL
@@ -10,39 +10,52 @@ required.  The template body is used only for the introduction.
 
 In the template, the headers can be modified, additional headers added,
 and unneeeded headers can be removed.  The template header also contains
-a special Subject-Prefix header which defines a prefix to prefix each
-subject header with.  The @num@ and @total@ macros in the Subject-Prefix
-header are replaced with the patch number and the total number of
-patches, respectively. The patch number @num@ is zero-padded to the
-same width that @total@ has.
+a special Subject-Prefix header which defines a prefix for each subject
+header.  The @num@ and @total@ macros in the Subject-Prefix header are
+replaced with the patch number and the total number of patches,
+respectively. The patch number @num@ is zero-padded to the same width
+that @total@ has.
 
 Each message is assigned a unique Message-Id header, and all messages
 other than the introduction are made to refer to the introduction (using
 a References header) for proper message threading in mail clients.
 Patch filenames are stored in Content-Disposition headers so that mail
-clients know the original filename.  The message timestamps in Date
-headers in each message is incremented one second per message starting
-from the timestamp of the introduction.
+clients will know the original filename.  The message timestamps in Date
+headers in each message is incremented by one second per message, starting
+with the timestamp of the introduction.
 
 If a ~/.signature file exists, this file is appended to each message
 generated.
 
 Recipients and headers can be added, and existing headers can be
 replaced, individually in each message based on the headers in the
-introduction.  Quilt does not enforce a specific patch file format.
-Instead, to customize the messages generated, a filter function called
-quilt_mail_patch_filter may be defined in .quiltrc, or
-/etc/quilt.quiltrc if no ~/.quiltrc exists.  This function is passed the
-patch name as argument (without the $QUILT_PATCHES prefix). It shall
-read the patch from standard input, and write a RFC 2822 message header
-and the patch to standard output. Headers of the form ``Recipient-$X:
-...'' denote recipients to be added to the $X header (for example,
-``Recipient-Cc: agruen@suse.de'').  Headers of the form ``Replace-$X:
-...'' specify that header $X is to be replaced by this header (for
-eaxmple, ``Replace-Subject: Patch description''). All other headers
-are appended to the existing headers.
-
-A quilt_mail_patch_filter example is found in the example quilt.quiltrc.
+introduction.  Quilt does not enforce a specific patch file format. The
+mail command has a built-in heuristic for extracting subjects from
+patches, though:
+
+    * if The patch starts with something that looks like a mail
+      header, and there is a Subject header, use this as the subject,
+      or else
+
+    * if the patch has DESC a line followed by an EDESC line, use
+      the text in between as the subject, or else
+
+    * if the first paragraph is short enough to serve as a subject
+      (150 characters or less), use the first paragraph as the
+      subject.
+
+If no subject can be extracted from a patch, or there are duplicate
+subjects, the mail command will print an error message and abort.
+
+In case a patch header contains a line starting with `Cc:', `Acked-by:',
+or `Signed-off-by:', the email address specified is added to the
+CC header for this patch. If a patch header contains a line starting
+with `To:', the email address specified is added to To header for this
+patch.
+
+If the user specified in `To:', `Cc:', `Acked-by:', or `Signed-off-by:'
+equals the current user's name ($LOGNAME or $(whoami) if LOGNAME is
+undefined), this does not add a recipient.
 
 Each recipient will occur in the resulting message only once. Duplicates
 are filtered out. This happens as the headers are read, so the relative
@@ -54,3 +67,14 @@ characters must be quoted, and 8-bit characters must be encoded. In
 practice it probably makes little sense to use anything fancy right now;
 this area still needs some work.  Character set recognition and proper
 qualifying is also still missing.
+
+The heuristic can be overridden by defining a quilt_mail_patch_filter
+function in ~/.quiltrc or /etc/quilt.quiltrc.  This function is passed
+the patch name as argument (without the $QUILT_PATCHES prefix).  It
+shall read the patch from standard input, and write a RFC 2822 message
+header and the patch to standard output. Headers of the form
+``Recipient-$X: ...'' denote recipients to be added to the $X header
+(for example, ``Recipient-Cc: agruen@suse.de'').  Headers of the form
+``Replace-$X: ...'' specify that header $X is to be replaced by this
+header (for eaxmple, ``Replace-Subject: Patch description''). All other
+headers are appended to the existing headers.