--- /dev/null
+User's guide - Using PGP/GnuPG with Madmutt
+===========================================
+
+How do I use mutt with PGP, PGP5, or GnuPG?
+-------------------------------------------
+
+Go to the contrib subdirectory of the source tree. You'll find
+three files there, pgp2.rc, pgp5.rc, and gpg.rc. These files
+contain ready-to-use configurations for using mutt with pgp2, pgp5,
+and gpg.
+
+Include one of these files with your Madmutt config file (e.g. ~/.madmuttrc),
+and things should work out fine.
+
+You may wish to verify that all paths and the language parameters
+given to the PGP binaries match your needs.
+
+
+
+Frequently Asked Questions and Tips
+-----------------------------------
+
+Q: "People are sending PGP messages which Madmutt doesn't
+ recognize. What can I do?"
+
+A: The new way is to leave headers alone and use mutt's
+ check-traditional-pgp function, which can detect PGP messages at
+ runtime, and adjust content-types.
+
+ The old way is to configure your mail filter so it fixes headers:
+
+ Add the following lines to your ~/.procmailrc (you are
+ using procmail, aren't you?):
+
+ ------------------------------
+
+##
+## PGP
+##
+
+:0
+* !^Content-Type: message/
+* !^Content-Type: multipart/
+* !^Content-Type: application/pgp
+{
+ :0 fBw
+ * ^-----BEGIN PGP MESSAGE-----
+ * ^-----END PGP MESSAGE-----
+ | formail \
+ -i "Content-Type: application/pgp; format=text; x-action=encrypt"
+
+ :0 fBw
+ * ^-----BEGIN PGP SIGNED MESSAGE-----
+ * ^-----BEGIN PGP SIGNATURE-----
+ * ^-----END PGP SIGNATURE-----
+ | formail \
+ -i "Content-Type: application/pgp; format=text; x-action=sign"
+}
+
+
+ ------------------------------
+
+For users of maildrop, "Mark Weinem"
+<mark.weinem@unidui.uni-duisburg.de> suggests the following recipe:
+
+ ------------------------------
+
+BPGPM="-----BEGIN PGP MESSAGE-----"
+EPGPM="-----END PGP MESSAGE-----"
+BPGPS="-----BEGIN PGP SIGNATURE-----"
+EPGPS="-----END PGP SIGNATURE-----"
+
+if (!/^Content-Type: message/ && !/^Content-Type: multipart/ \
+ && !/^Content-Type: application\/pgp/)
+{
+if (/^$BPGPM/:b && /^$EPGPM/:b)
+ xfilter "reformail -A 'Content-Type: application/pgp; format=text; \
+ x-action=encrypt'"
+
+if (/^$BPGPS/:b && /^$EPGPS/:b)
+ xfilter "reformail -A 'Content-Type: application/pgp; format=text; \
+ x-action=sign'"
+}
+
+ ------------------------------
+
+
+
+Q: "I don't like that PGP/MIME stuff, but want to use the
+ old way of PGP-signing my mails. Can't you include
+ that with Madmutt?"
+
+A: No. Application/pgp is not really suited to a world with MIME,
+ non-textual body parts and similar things. Anyway, if you really
+ want to generate these old-style attachments, include the
+ following macro in your ~/.madmuttrc (line breaks for readability,
+ this is actually one line):
+
+ macro compose S "Fpgp +verbose=0 -fast
+ +clearsig=on\ny^T^Uapplication/pgp; format=text;
+ x-action=sign\n"
+
+
+There's a new answer, though: Set the pgp_autoinline
+configuration variable (it's a quad-option) to something different
+from "no" (that's the default). Madmutt will then try to use
+application/pgp whereever it makes sense. In particular, it does
+not make any sense with multiparts, or non-ASCII or non-text bodies.
+In all other cases, PGP/MIME is used unconditionally.
+
+Note that application/pgp is still strongly deprecated.
+
+
+
+Q: "I don't like all the ^Gs and various other verbosity
+ PGP is presenting me with."
+
+A: Roland Rosenfeld <roland@spinnaker.rhein.de> has found a quite
+ elegant solution to this problem: PGP has some pretty good foreign
+ language support. So we just introduce a language called "mutt"
+ which contains empty strings for the messages we don't want to see.
+ To use this, copy either language.txt or language50.txt (depending
+ on what PGP version you are using) to your $PGPPATH. Make sure the
+ PGP command formats pass "+language=pgp" to all the PGP binaries
+ (but not to pgpringng!).
+
+For PGP 2.6, a German version called "muttde" is available
+as well.
+
+
+Q: "My PGP signatures are being invalidated. BTW, I'm using Courier
+ MTA."
+
+A: The author of the Courier MTA believes that the standard specifying
+ multipart/signed is broken. For that reason, he has choosen to
+ implement his MTA in a way which does not assure that
+ multipart/signed body parts are left untouched.
+
+ We suggest that you abandon courier and change to qmail, postfix,
+ or exim.
+
+
+
+BACKGROUND
+==========
+
+Auxiliary Programs
+------------------
+
+Madmutt needs two auxiliary programs for its PGP support: pgpewrapng and
+pgpringng.
+
+
+1. pgpringng
+
+pgpringng is a key ring dumper. It extracts information from PGP's
+binary key ring and emits it in an (almost) readable output format
+understood by mutt's key selection routines. This output format
+mimics the one used by the GNU Privacy Guard (GPG).
+
+You'll need this program with PGP 2 and PGP 5.
+
+Command line options:
+
+ -k <key ring> Dump the contents of the key ring specified
+ as an argument to -k.
+
+ -2, -5 Use the default key ring for PGP 2 or 5,
+ respectively.
+
+ -s Dump the secret key ring.
+
+
+
+2. pgpewrapng
+
+This is a little C program which does some command line munging: The
+first argument is a command to be executed. When pgpewrapng
+encounters a "--" (dash-dash) argument, it will interpret the next
+argument as a prefix which is put in front of all following
+arguments.
+
+Example:
+
+ pgpewrapng pgpe file -- -r a b c
+
+will execute:
+
+ pgpe file -r a -r b -r c
+
+This script is needed with PGP 5 and with GPG, since their command
+line interfaces can't be properly served by mutt's format mechanism.
+
+
+
+The Configuration Interface
+---------------------------
+
+As usual within Madmutt, the configuration interface for the PGP
+commands relies on printf-like formats. For all PGP commands, the
+following %-sequences are defined.
+
+ %p The empty string when no passphrase is needed,
+ the string "PGPPASSFD=0" if one is needed.
+
+ This is mostly used in conditional % sequences.
+
+ %f Most PGP commands operate on a single file or a file
+ containing a message. %f expands to this file's name.
+
+ %s When verifying signatures, there is another temporary file
+ containing the detached signature. %s expands to this
+ file's name.
+
+ %a In "signing" contexts, this expands to the value of the
+ configuration variable $pgp_sign_as. You probably need to
+ use this within a conditional % sequence.
+
+ %r In many contexts, mutt passes key IDs to pgp. %r expands to
+ a list of key IDs.
+
+The following command formats are defined:
+
+ $pgp_decode_command Decode application/pgp messages. This
+ command operates with and without pass phrases.
+
+ $pgp_verify_command Verify a PGP/MIME signature.
+
+ $pgp_decrypt_command Decrypt a PGP/MIME encrypted MIME body.
+ This command always gets a pass phrase.
+
+ $pgp_sign_command Sign a PGP/MIME body. This command always
+ gets a pass phrase.
+
+
+ $pgp_encrypt_sign_command Encrypt and sign a MIME body. This
+ command always gets a pass phrase.
+
+ $pgp_encrypt_only_command Encrypt a MIME body, but don't sign it.
+
+ $pgp_import_command Import PGP keys from a file.
+
+ $pgp_export_command Export PGP keys to a file. The output must
+ be ASCII armored.
+
+ $pgp_verify_key_command Check a public key. This is used from the
+ key selection menu.
+
+ $pgp_list_secring_command List the secret keys matching some hints
+ given in %r.
+
+ $pgp_list_pubring_command List the public keys matching some hints
+ given in %r.
+
+The passphrase is always passed on stdin; all commands must send
+their output to stdout and stderr.
+
+
+