This file documents Message, the Emacs message composition mode.
Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
-2004, 2005, 2006 Free Software Foundation, Inc.
+2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* Variables:: Customizing the message buffers.
* Compatibility:: Making Message backwards compatible.
* Appendices:: More technical things.
+* GNU Free Documentation License:: The license for this documentation.
* Index:: Variable, function and concept index.
* Key Index:: List of Message mode keys.
@end menu
it is not a member of @samp{Newsgroups}, and insert a note in the body.
If @code{message-cross-post-default} is @code{nil} or if this command is
called with a prefix-argument, only the @samp{FollowUp-To} header will
-be set but the the target newsgroup will not be added to the
+be set but the target newsgroup will not be added to the
@samp{Newsgroups} header. The function to insert a note is controlled
by the @code{message-cross-post-note-function} variable.
automatically add the @code{Content-Type} and
@code{Content-Transfer-Encoding} headers.
-@findex mml-attach
+@findex mml-attach-file
@kindex C-c C-a
The most typical thing users want to use the multipart things in
@acronym{MIME} for is to add ``attachments'' to mail they send out.
-This can be done with the @kbd{C-c C-a} command (@kbd{M-x mml-attach}),
+This can be done with the @kbd{C-c C-a} command (@kbd{M-x mml-attach-file}),
which will prompt for a file name and a @acronym{MIME} type.
@vindex mml-dnd-protocol-alist
Using the @acronym{MML} language, Message is able to create digitally
signed and digitally encrypted messages. Message (or rather
@acronym{MML}) currently support @acronym{PGP} (RFC 1991),
-@acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}. Instructing
-@acronym{MML} to perform security operations on a @acronym{MIME} part is
-done using the @kbd{C-c C-m s} key map for signing and the @kbd{C-c C-m
-c} key map for encryption, as follows.
+@acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}.
+@menu
+* Signing and encryption:: Signing and encrypting commands.
+* Using S/MIME:: Using S/MIME
+* Using PGP/MIME:: Using PGP/MIME
+* PGP Compatibility:: Compatibility with older implementations
+@end menu
+
+@node Signing and encryption
+@subsection Signing and encrypting commands
+
+Instructing @acronym{MML} to perform security operations on a
+@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for
+signing and the @kbd{C-c C-m c} key map for encryption, as follows.
@table @kbd
@item C-c C-m s s
other properly. Thus, we now describe what external libraries or
programs are required to make things work, and some small general hints.
+@node Using S/MIME
@subsection Using S/MIME
@emph{Note!} This section assume you have a basic familiarity with
you are on a secure single user machine) simply press @code{RET} at
the passphrase prompt.
+@node Using PGP/MIME
@subsection Using PGP/MIME
@acronym{PGP/MIME} requires an external OpenPGP implementation, such
implementations such as PGP 2.x and PGP 5.x are also supported. One
Emacs interface to the PGP implementations, PGG (@pxref{Top, ,PGG,
pgg, PGG Manual}), is included, but Mailcrypt and Florian Weimer's
-@code{gpg.el} are also supported.
+@code{gpg.el} are also supported. @xref{PGP Compatibility}.
+
+@cindex gpg-agent
+Message internally calls GnuPG (the @command{gpg} command) to perform
+data encryption, and in certain cases (decrypting or signing for
+example), @command{gpg} requires user's passphrase. Currently the
+recommended way to supply your passphrase to @command{gpg} is to use the
+@command{gpg-agent} program.
+
+To use @command{gpg-agent} in Emacs, you need to run the following
+command from the shell before starting Emacs.
+
+@example
+eval `gpg-agent --daemon`
+@end example
+
+This will invoke @command{gpg-agent} and set the environment variable
+@code{GPG_AGENT_INFO} to allow @command{gpg} to communicate with it.
+It might be good idea to put this command in your @file{.xsession} or
+@file{.bash_profile}. @xref{Invoking GPG-AGENT, , , gnupg, Using the
+GNU Privacy Guard}.
+
+Once your @command{gpg-agent} is set up, it will ask you for a
+passphrase as needed for @command{gpg}. Under the X Window System,
+you will see a new passphrase input dialog appear. The dialog is
+provided by PIN Entry (the @command{pinentry} command), and as of
+version 0.7.2, @command{pinentry} cannot cooperate with Emacs on a
+single tty. So, if you are using a text console, you may need to put
+a passphrase into gpg-agent's cache beforehand. The following command
+does the trick.
+
+@example
+gpg --use-agent --sign < /dev/null > /dev/null
+@end example
+
+The Lisp variable @code{pgg-gpg-use-agent} controls whether to use
+@command{gpg-agent}. See also @xref{Caching passphrase, , , pgg, The
+PGG Manual}.
+
+
+@node PGP Compatibility
+@subsection Compatibility with older implementations
@vindex gpg-temp-directory
Note, if you are using the @code{gpg.el} you must make sure that the
@vindex message-subject-trailing-was-regexp
Controls what to do with trailing @samp{(was: <old subject>)} in subject
lines. If @code{nil}, leave the subject unchanged. If it is the symbol
-@code{ask}, query the user what do do. In this case, the subject is
+@code{ask}, query the user what to do. In this case, the subject is
matched against @code{message-subject-trailing-was-ask-regexp}. If
@code{message-subject-trailing-was-query} is @code{t}, always strip the
trailing old subject. In this case,
Valid checks are:
@table @code
-@item subject-cmsg
-Check the subject for commands.
-@item sender
-@cindex Sender
-Insert a new @code{Sender} header if the @code{From} header looks odd.
-@item multiple-headers
-Check for the existence of multiple equal headers.
-@item sendsys
-@cindex sendsys
-Check for the existence of version and sendsys commands.
-@item message-id
-Check whether the @code{Message-ID} looks ok.
-@item from
-Check whether the @code{From} header seems nice.
-@item long-lines
-@cindex long lines
-Check for too long lines.
-@item control-chars
-Check for invalid characters.
-@item size
-Check for excessive size.
-@item new-text
-Check whether there is any new text in the messages.
-@item signature
-Check the length of the signature.
@item approved
@cindex approved
Check whether the article has an @code{Approved} header, which is
something only moderators should include.
+@item continuation-headers
+Check whether there are continuation header lines that don't begin with
+whitespace.
+@item control-chars
+Check for invalid characters.
@item empty
Check whether the article is empty.
-@item invisible-text
-Check whether there is any invisible text in the buffer.
-@item empty-headers
-Check whether any of the headers are empty.
@item existing-newsgroups
Check whether the newsgroups mentioned in the @code{Newsgroups} and
@code{Followup-To} headers exist.
-@item valid-newsgroups
-Check whether the @code{Newsgroups} and @code{Followup-to} headers
-are valid syntactically.
+@item from
+Check whether the @code{From} header seems nice.
+@item illegible-text
+Check whether there is any non-printable character in the body.
+@item invisible-text
+Check whether there is any invisible text in the buffer.
+@item long-header-lines
+Check for too long header lines.
+@item long-lines
+@cindex long lines
+Check for too long lines in the body.
+@item message-id
+Check whether the @code{Message-ID} looks syntactically ok.
+@item multiple-headers
+Check for the existence of multiple equal headers.
+@item new-text
+Check whether there is any new text in the messages.
+@item newsgroups
+Check whether the @code{Newsgroups} header exists and is not empty.
+@item quoting-style
+Check whether text follows last quoted portion.
@item repeated-newsgroups
Check whether the @code{Newsgroups} and @code{Followup-to} headers
contains repeated group names.
+@item reply-to
+Check whether the @code{Reply-To} header looks ok.
+@item sender
+@cindex Sender
+Insert a new @code{Sender} header if the @code{From} header looks odd.
+@item sendsys
+@cindex sendsys
+Check for the existence of version and sendsys commands.
+@item shoot
+Check whether the domain part of the @code{Message-ID} header looks ok.
@item shorten-followup-to
Check whether to add a @code{Followup-to} header to shorten the number
of groups to post to.
+@item signature
+Check the length of the signature.
+@item size
+Check for excessive size.
+@item subject
+Check whether the @code{Subject} header exists and is not empty.
+@item subject-cmsg
+Check the subject for commands.
+@item valid-newsgroups
+Check whether the @code{Newsgroups} and @code{Followup-to} headers
+are valid syntactically.
@end table
-All these conditions are checked by default.
+All these conditions are checked by default, except for @code{sender}
+for which the check is disabled by default if
+@code{message-insert-canlock} is non-@code{nil} (@pxref{Canceling News}).
@item message-ignored-news-headers
@vindex message-ignored-news-headers
@table @code
@item message-generate-new-buffers
@vindex message-generate-new-buffers
-If non-@code{nil}, generate new buffers. The default is @code{t}. If
-this is a function, call that function with three parameters: The type,
-the to address and the group name. (Any of these may be @code{nil}.)
-The function should return the new buffer name.
+Controls whether to create a new message buffer to compose a message.
+Valid values include:
+
+@table @code
+@item nil
+Generate the buffer name in the Message way (e.g., *mail*, *news*, *mail
+to whom*, *news on group*, etc.) and continue editing in the existing
+buffer of that name. If there is no such buffer, it will be newly
+created.
+
+@item unique
+@item t
+Create the new buffer with the name generated in the Message way. This
+is the default.
+
+@item unsent
+Similar to @code{unique} but the buffer name begins with "*unsent ".
+
+@item standard
+Similar to @code{nil} but the buffer name is simpler like *mail
+message*.
+@end table
+@table @var
+@item function
+If this is a function, call that function with three parameters: The
+type, the To address and the group name (any of these may be
+@code{nil}). The function should return the new buffer name.
+@end table
+
+The default value is @code{unique}.
@item message-max-buffers
@vindex message-max-buffers
@end table
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+@include doclicense.texi
@node Index
@chapter Index