* gnus-util.el (gnus-read-event-char): Take an optional parameter even if

[elisp/gnus.git-] / texi / message.texi

diff --git a/texi/message.texi b/texi/message.texi
index 5ea0daa..0ba64bb 100644 (file)
--- a/texi/message.texi
+++ b/texi/message.texi
@@ -18,7 +18,8 @@
 
 This file documents Message, the Emacs message composition mode.
 
 
 This file documents Message, the Emacs message composition mode.
 

-Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 
+Free Software Foundation, Inc.

 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or

@@ -235,6 +236,23 @@ The value of @code{message-cancel-message} is inserted in the body of
 the cancel message.  The default is @samp{I am canceling my own
 article.}.
 
 the cancel message.  The default is @samp{I am canceling my own
 article.}.
 

+@cindex Cancel Locks
+@vindex message-insert-canlock
+@cindex canlock
+When Message posts news messages, it inserts @code{Cancel-Lock}
+headers by default.  This is a cryptographic header that ensures that
+only you can cancel your own messages, which is nice.  The downside
+is that if you lose your @file{.emacs} file (which is where Gnus
+stores the secret cancel lock password (which is generated
+automatically the first time you use this feature)), you won't be
+able to cancel your message.
+
+Whether to insert the header or not is controlled by the
+@code{message-insert-canlock} variable.
+
+Not many news servers respect the @code{Cancel-Lock} header yet, but
+this is expected to change in the future.
+

 
 @node Superseding
 @section Superseding
 
 @node Superseding
 @section Superseding

@@ -438,17 +456,17 @@ address, then no MFT is generated; otherwise, a MFT is added to the
 other headers and set to the value of all addresses in To: and Cc:
 
 @kindex C-c C-f C-a
 other headers and set to the value of all addresses in To: and Cc:
 
 @kindex C-c C-f C-a

-@findex message-gen-unsubscribed-mft
+@findex message-generate-unsubscribed-mail-followup-to

 @kindex C-c C-f C-m
 @findex message-goto-mail-followup-to
 Hm. ``So'', you ask, ``what if I send an email to a list I am not
 @kindex C-c C-f C-m
 @findex message-goto-mail-followup-to
 Hm. ``So'', you ask, ``what if I send an email to a list I am not

-subscribed to?  I want my MFT to say that I want an extra copy.''
-(This is supposed to be interpreted by others the same way as if there
-were no MFT, but you can use an explicit MFT to override someone
-else's to-address group parameter.)  The function
-@code{message-gen-unsubscribed-mft} might come in handy.  It is bound
-to @kbd{C-c C-f C-a} by default.  In any case, you can insert a MFT of
-your own choice; @kbd{C-c C-f C-m}
+subscribed to?  I want my MFT to say that I want an extra copy.''  (This
+is supposed to be interpreted by others the same way as if there were no
+MFT, but you can use an explicit MFT to override someone else's
+to-address group parameter.)  The function
+@code{message-generate-unsubscribed-mail-followup-to} might come in
+handy.  It is bound to @kbd{C-c C-f C-a} by default.  In any case, you
+can insert a MFT of your own choice; @kbd{C-c C-f C-m}

 (@code{message-goto-mail-followup-to}) will help you get started.
 
 @c @node Honoring an MFT post
 (@code{message-goto-mail-followup-to}) will help you get started.
 
 @c @node Honoring an MFT post

@@ -481,7 +499,7 @@ better than you do.
 
 @menu
 * Buffer Entry::        Commands after entering a Message buffer.
 
 @menu
 * Buffer Entry::        Commands after entering a Message buffer.

-* Header Commands::     Commands for moving to headers.
+* Header Commands::     Commands for moving headers or changing headers.

 * Movement::            Moving around in message buffers.
 * Insertion::           Inserting things into message buffers.
 * MIME::                @sc{mime} considerations.
 * Movement::            Moving around in message buffers.
 * Insertion::           Inserting things into message buffers.
 * MIME::                @sc{mime} considerations.

@@ -511,9 +529,10 @@ times, you will get back the un-edited message you're responding to.
 @node Header Commands
 @section Header Commands
 
 @node Header Commands
 @section Header Commands
 

-All these commands move to the header in question (except for the
-@samp{Importance:} related commands).  If it doesn't exist, it will be
-inserted.
+@subsection Commands for moving to headers
+
+These following commands move to the header in question.  If it doesn't
+exist, it will be inserted.

 
 @table @kbd
 
 
 @table @kbd
 

@@ -592,17 +611,123 @@ message to the receiver.  If the header is already present in the
 buffer, it cycles between the three valid values according to RFC
 1376: @samp{low}, @samp{normal} and @samp{high}.
 
 buffer, it cycles between the three valid values according to RFC
 1376: @samp{low}, @samp{normal} and @samp{high}.
 

+@item C-c C-f C-a
+@kindex C-c C-f C-a
+@findex message-generate-unsubscribed-mail-followup-to
+Insert a reasonable @samp{Mail-Followup-To:} header
+(@pxref{Mailing Lists}) in a post to an
+unsubscribed list.  When making original posts to a mailing list you are
+not subscribed to, you have to type in a @samp{Mail-Followup-To:} header
+by hand.  The contents, usually, are the addresses of the list and your
+own address.  This function inserts such a header automatically.  It
+fetches the contents of the @samp{To:} header in the current mail
+buffer, and appends the current @code{user-mail-address}.
+
+If the optional argument @code{include-cc} is non-nil, the addresses in
+the @samp{Cc:} header are also put into the @samp{Mail-Followup-To:}
+header.
+
+@end table
+
+@subsection  Commands to change headers
+
+@table @kbd
+
+@item C-c C-o
+@kindex C-c C-o
+@findex message-sort-headers
+@vindex message-header-format-alist
+Sort headers according to @code{message-header-format-alist}
+(@code{message-sort-headers}).
+
+@item C-c C-t
+@kindex C-c C-t
+@findex message-insert-to
+Insert a @code{To} header that contains the @code{Reply-To} or
+@code{From} header of the message you're following up
+(@code{message-insert-to}).
+
+@item C-c C-n
+@kindex C-c C-n
+@findex message-insert-newsgroups
+Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
+or @code{Newsgroups} header of the article you're replying to
+(@code{message-insert-newsgroups}).
+
+@item C-c C-l
+@kindex C-c C-l
+@findex message-to-list-only
+Send a message to the list only.  Remove all addresses but the list
+address from @code{To:} and @code{Cc:} headers.
+
+@item C-c M-n
+@kindex C-c M-n
+@findex message-insert-disposition-notification-to
+Insert a request for a disposition
+notification. (@code{message-insert-disposition-notification-to}).
+This means that if the recipient support RFC 2298 she might send you a
+notification that she received the message.
+

 @item M-x message-insert-importance-high
 @kindex M-x message-insert-importance-high
 @findex message-insert-importance-high
 @item M-x message-insert-importance-high
 @kindex M-x message-insert-importance-high
 @findex message-insert-importance-high

-Insert a @samp{Importance:} header with a value of @samp{high},
+@cindex Importance
+Insert an @samp{Importance} header with a value of @samp{high},

 deleting headers if necessary.
 
 @item M-x message-insert-importance-low
 @kindex M-x message-insert-importance-low
 @findex message-insert-importance-low
 deleting headers if necessary.
 
 @item M-x message-insert-importance-low
 @kindex M-x message-insert-importance-low
 @findex message-insert-importance-low

-Insert a @samp{Importance:} header with a value of @samp{low},
-deleting headers if necessary.
+@cindex Importance
+Insert an @samp{Importance} header with a value of @samp{low}, deleting
+headers if necessary.
+
+@item C-c C-f s
+@kindex C-c C-f s
+@findex message-change-subject
+@cindex Subject
+Change the current @samp{Subject} header.  Ask for new @samp{Subject}
+header and append @code{(was: <Old Subject>)}.  The old subject can be
+stripped on replying, see @code{message-subject-trailing-was-query}
+(@pxref{Message Headers}).
+
+@item C-c C-f x
+@kindex C-c C-f x
+@findex message-cross-post-followup-to
+@vindex message-cross-post-default
+@cindex X-Post
+@cindex cross-post
+Ask for an additional @samp{Newsgroups} and @samp{FollowUp-To} for a
+cross-post.  @code{message-cross-post-followup-to} mangles
+@samp{FollowUp-To} and @samp{Newsgroups} header to point to group.
+If @code{message-cross-post-default} is @code{nil} or if called with a
+prefix-argument @samp{Follow-Up} is set, but the message is not
+cross-posted.
+
+@item C-c C-f t
+@kindex C-c C-f t
+@findex message-reduce-to-to-cc
+Replace contents of @samp{To} header with contents of @samp{Cc} or
+@samp{Bcc} header.
+
+@item C-c C-f w
+@kindex C-c C-f w
+@findex message-insert-wide-reply
+Insert @samp{To} and @samp{Cc} headers as if you were doing a wide
+reply. 
+
+@item C-c C-f a
+@kindex C-c C-f a
+@findex message-add-archive-header
+@vindex message-archive-header
+@vindex message-archive-note
+@cindex X-No-Archive
+Insert @samp{X-No-Archive: Yes} in the header and a note in the body.
+The header and the note can be customized using
+@code{message-archive-header} and @code{message-archive-note}.  When
+called with a prefix argument, ask for a text to insert.  If you don't
+want the note in the body, set @code{message-archive-note} to
+@code{nil}.

 
 @end table
 
 
 @end table
 

@@ -625,9 +750,11 @@ Move to the signature of the message (@code{message-goto-signature}).
 @item C-a
 @kindex C-a
 @findex message-beginning-of-line
 @item C-a
 @kindex C-a
 @findex message-beginning-of-line

+@vindex message-beginning-of-line

 If at beginning of header value, go to beginning of line, else go to
 beginning of header value.  (The header value comes after the header
 If at beginning of header value, go to beginning of line, else go to
 beginning of header value.  (The header value comes after the header

-name and the colon.)
+name and the colon.)  This behaviour can be disabled by toggling
+the variable @code{message-beginning-of-line}.

 
 @end table
 
 
 @end table
 

@@ -670,13 +797,17 @@ Insert a signature at the end of the buffer
 @findex message-insert-headers
 Insert the message headers (@code{message-insert-headers}).
 
 @findex message-insert-headers
 Insert the message headers (@code{message-insert-headers}).
 

-@item C-c M-n
-@kindex C-c M-n
-@findex message-insert-disposition-notification-to
-Insert a request for a disposition
-notification. (@code{message-insert-disposition-notification-to}).
-This means that if the recipient support RFC 2298 she might send you a
-notification that she received the message.
+@item C-c M-m
+@kindex C-c M-m
+@findex message-mark-inserted-region
+Mark some region in the current article with enclosing tags.
+See @code{message-mark-insert-begin} and @code{message-mark-insert-end}.
+
+@item C-c M-f
+@kindex C-c M-f
+@findex message-mark-insert-file
+Insert a file in the current article with enclosing tags.
+See @code{message-mark-insert-begin} and @code{message-mark-insert-end}.

 
 @end table
 
 
 @end table
 

@@ -875,10 +1006,10 @@ care in handling it.
 @subsection Using PGP/MIME
 
 @sc{pgp/mime} requires an external OpenPGP implementation, such as GNU
 @subsection Using PGP/MIME
 
 @sc{pgp/mime} requires an external OpenPGP implementation, such as GNU

-Privacy Guard (@uref{http://www.gnupg.org/}).  It also requires an
-Emacs interface to it, such as Mailcrypt (available from
-@uref{http://www.nb.net/~lbudney/linux/software/mailcrypt.html}) or
-Florian Weimer's @code{gpg.el}.
+Privacy Guard (@uref{http://www.gnupg.org/}).  One Emacs interface to
+OpenPGP implementations, PGG (@pxref{Top, ,PGG, pgg, PGG Manual}), is
+included, but Mailcrypt and Florian Weimer's @code{gpg.el} are also
+supported.

 
 @vindex gpg-temp-directory
 Note, if you are using the @code{gpg.el} you must make sure that the
 
 @vindex gpg-temp-directory
 Note, if you are using the @code{gpg.el} you must make sure that the

@@ -944,33 +1075,20 @@ If point is before @samp{And} and you press @kbd{M-RET}, you'll get:
 
 @samp{*} says where point will be placed.
 
 
 @samp{*} says where point will be placed.
 

-@item C-c C-t
-@kindex C-c C-t
-@findex message-insert-to
-Insert a @code{To} header that contains the @code{Reply-To} or
-@code{From} header of the message you're following up
-(@code{message-insert-to}).
-
-@item C-c C-n
-@kindex C-c C-n
-@findex message-insert-newsgroups
-Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
-or @code{Newsgroups} header of the article you're replying to
-(@code{message-insert-newsgroups}).
-
-@item C-c C-o
-@kindex C-c C-o
-@findex message-sort-headers
-@vindex message-header-format-alist
-Sort headers according to @code{message-header-format-alist}
-(@code{message-sort-headers}).
-

 @item C-c M-r
 @kindex C-c M-r
 @findex message-rename-buffer
 Rename the buffer (@code{message-rename-buffer}).  If given a prefix,
 prompt for a new buffer name.
 
 @item C-c M-r
 @kindex C-c M-r
 @findex message-rename-buffer
 Rename the buffer (@code{message-rename-buffer}).  If given a prefix,
 prompt for a new buffer name.
 

+@item TAB
+@kindex TAB
+@findex message-tab
+@vindex message-tab-body-function
+If non-@code{nil} execute the function specified in
+@code{message-tab-body-function}.  Otherwise use the function bound to
+@kbd{TAB} in @code{text-mode-map} or @code{global-map}.
+

 @end table
 
 
 @end table
 
 

@@ -1120,15 +1238,29 @@ look sufficiently similar.
 
 @item message-generate-headers-first
 @vindex message-generate-headers-first
 
 @item message-generate-headers-first
 @vindex message-generate-headers-first

-If non-@code{nil}, generate all required headers before starting to
-compose the message.
+If @code{t}, generate all required headers before starting to
+compose the message.  This can also be a list of headers to generate:

 
 

-The variables @code{message-required-mail-headers} and
-@code{message-required-news-headers} specify which headers are required.
+@lisp
+(setq message-generate-headers-first
+      '(References))
+@end lisp
+
+@vindex message-required-headers
+The variables @code{message-required-headers},
+@code{message-required-mail-headers} and
+@code{message-required-news-headers} specify which headers are
+required.

 
 Note that some headers will be removed and re-generated before posting,
 because of the variable @code{message-deletable-headers} (see below).
 
 
 Note that some headers will be removed and re-generated before posting,
 because of the variable @code{message-deletable-headers} (see below).
 

+@item message-draft-headers
+@vindex message-draft-headers
+When running Message from Gnus, the message buffers are associated
+with a draft group.  @code{message-draft-headers} says which headers
+should be generated when a draft is written to the draft group.
+

 @item message-from-style
 @vindex message-from-style
 Specifies how @code{From} headers should look.  There are four valid
 @item message-from-style
 @vindex message-from-style
 Specifies how @code{From} headers should look.  There are four valid

@@ -1191,11 +1323,30 @@ responding to a message:
      "^\\(\\(\\([Rr][Ee]\\|[Ss][Vv]\\|[Aa][Ww]\\): *\\)+\\)")
 @end lisp
 
      "^\\(\\(\\([Rr][Ee]\\|[Ss][Vv]\\|[Aa][Ww]\\): *\\)+\\)")
 @end lisp
 

+@item message-subject-trailing-was-query
+@vindex message-subject-trailing-was-query
+@vindex message-subject-trailing-was-ask-regexp
+@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
+matched against @code{message-subject-trailing-was-ask-regexp}.  If
+@code{message-subject-trailing-was-query} is t, always strip the
+trailing old subject.  In this case,
+@code{message-subject-trailing-was-regexp} is used.
+

 @item message-alternative-emails
 @vindex message-alternative-emails
 A regexp to match the alternative email addresses.  The first matched
 address (not primary one) is used in the @code{From} field.
 
 @item message-alternative-emails
 @vindex message-alternative-emails
 A regexp to match the alternative email addresses.  The first matched
 address (not primary one) is used in the @code{From} field.
 

+@item message-allow-no-recipients
+@vindex message-allow-no-recipients
+Specifies what to do when there are no recipients other than
+@code{Gcc} or @code{Fcc}.  If it is @code{always}, the posting is
+allowed.  If it is @code{never}, the posting is not allowed.  If it is
+@code{ask} (the default), you are prompted.
+

 @end table
 
 
 @end table
 
 

@@ -1602,6 +1753,14 @@ This can also be a list of functions.  Each function can find the
 citation between @code{(point)} and @code{(mark t)}.  And each function
 should leave point and mark around the citation text as modified.
 
 citation between @code{(point)} and @code{(mark t)}.  And each function
 should leave point and mark around the citation text as modified.
 

+@item message-mark-insert-begin
+@vindex message-mark-insert-begin
+String to mark the beginning of some inserted text.
+
+@item message-mark-insert-end
+@vindex message-mark-insert-end
+String to mark the end of some inserted text.
+

 @item message-signature
 @vindex message-signature
 String to be inserted at the end of the message buffer.  If @code{t}
 @item message-signature
 @vindex message-signature
 String to be inserted at the end of the message buffer.  If @code{t}

@@ -1615,6 +1774,11 @@ If this variable is @code{nil}, no signature will be inserted at all.
 File containing the signature to be inserted at the end of the buffer.
 The default is @file{~/.signature}.
 
 File containing the signature to be inserted at the end of the buffer.
 The default is @file{~/.signature}.
 

+@item message-signature-insert-empty-line
+@vindex message-signature-insert-empty-line
+If @code{t} (the default value) an empty line is inserted before the
+signature separator.
+

 @end table
 
 Note that RFC1036bis says that a signature should be preceded by the three
 @end table
 
 Note that RFC1036bis says that a signature should be preceded by the three