- Add mail command, doc/README.MAIL and example ``mail'' command

  filter in quilt.quiltrc.
- Bump version to 0.38.

1 files changed, 56 insertions, 0 deletions

diff --git a/doc/README.MAIL b/doc/README.MAIL
new file mode 100644
index 0000000..08df3fd
--- /dev/null
+++ b/doc/README.MAIL
@@ -0,0 +1,56 @@
+QUILT MAIL COMMAND
+==================
+
+The mail command starts up the system editor ($EDITOR, or vi if $EDITOR
+is undefined) with an template in Internet Message Format (RFC 2822).
+This template is used to generate an introduction, as well as one
+message for each patch in the series file.  The template is used as
+follows: The headers are used in each message generated, and modified as
+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.
+
+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.
+
+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.
+
+Each recipient will occur in the resulting message only once. Duplicates
+are filtered out. This happens as the headers are read, so the relative
+order of the To, Cc, and Bcc headers should not be changed.
+
+Recipients are checked for RFC 2822 conformance (at least that is the
+intention; actually the checks are not perfect). This means that special
+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.