@copying
Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
-2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* Various:: General purpose settings.
* The End:: Farewell and goodbye.
* Appendices:: Terminology, Emacs intro, @acronym{FAQ}, History, Internals.
+* GNU Free Documentation License:: The license for this documentation.
* Index:: Variable, function and concept index.
* Key Index:: Key Index.
* IMAP:: Using Gnus as a @acronym{IMAP} client.
* Other Sources:: Reading directories, files, SOUP packets.
* Combined Groups:: Combining groups into one group.
+* Email Based Diary:: Using mails to manage diary events in Gnus.
* Gnus Unplugged:: Reading news and mail offline.
Server Buffer
* Virtual Groups:: Combining articles from many groups.
* Kibozed Groups:: Looking through parts of the newsfeed for articles.
+Email Based Diary
+
+* The NNDiary Back End:: Basic setup and usage.
+* The Gnus Diary Library:: Utility toolkit on top of nndiary.
+* Sending or Not Sending:: A final note on sending diary messages.
+
+The NNDiary Back End
+
+* Diary Messages:: What makes a message valid for nndiary.
+* Running NNDiary:: NNDiary has two modes of operation.
+* Customizing NNDiary:: Bells and whistles.
+
+The Gnus Diary Library
+
+* Diary Summary Line Format:: A nicer summary buffer line format.
+* Diary Articles Sorting:: A nicer way to sort messages.
+* Diary Headers Generation:: Not doing it manually.
+* Diary Group Parameters:: Not handling them manually.
+
Gnus Unplugged
* Agent Basics:: How it all is supposed to work.
@chapter Starting Gnus
@cindex starting up
-If you are haven't used Emacs much before using Gnus, read @ref{Emacs
-for Heathens} first.
+If you haven't used Emacs much before using Gnus, read @ref{Emacs for
+Heathens} first.
@kindex M-x gnus
@findex gnus
automatically when entering a group with the @kbd{SPACE} command.
Which article this is is controlled by the
@code{gnus-auto-select-subject} variable. Valid values for this
-variable is:
+variable are:
@table @code
@item auto-expire
@cindex auto-expire
+@cindex expiring mail
If the group parameter has an element that looks like @code{(auto-expire
. t)}, all articles read will be marked as expirable. For an
alternative approach, @pxref{Expiring Mail}.
@item total-expire
@cindex total-expire
+@cindex expiring mail
If the group parameter has an element that looks like
@code{(total-expire . t)}, all read articles will be put through the
expiry process, even if they are not marked as expirable. Use with
@item C-c C-x
@kindex C-c C-x (Group)
@findex gnus-group-expire-articles
+@cindex expiring mail
Run all expirable articles in the current group through the expiry
process (if any) (@code{gnus-group-expire-articles}). That is, delete
all expirable articles in the group that have been around for a while.
@item C-c C-M-x
@kindex C-c C-M-x (Group)
@findex gnus-group-expire-all-groups
+@cindex expiring mail
Run all expirable articles in all groups through the expiry process
(@code{gnus-group-expire-all-groups}).
@item C-c C-x
@kindex C-c C-x (Topic)
@findex gnus-topic-expire-articles
+@cindex expiring mail
Run all expirable articles in the current group or topic through the
expiry process (if any)
(@code{gnus-topic-expire-articles}). (@pxref{Expiring Mail}).
@item v
@kindex v (Group)
@cindex keys, reserved for users (Group)
-The key @kbd{v} is reserved for users. You can bind it key to some
-function or better use it as a prefix key. For example:
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key. For example:
@lisp
(define-key gnus-group-mode-map (kbd "v j d")
@kindex v (Summary)
@cindex keys, reserved for users (Summary)
-The key @kbd{v} is reserved for users. You can bind it key to some
-function or better use it as a prefix key. For example:
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key. For example:
@lisp
(define-key gnus-summary-mode-map (kbd "v -") "LrS") ;; lower subthread
@end lisp
used for marking articles in such a way that other commands will
process these articles. For instance, if you process mark four
articles and then use the @kbd{*} command, Gnus will enter these four
-commands into the cache. For more information,
+articles into the cache. For more information,
@pxref{Process/Prefix}.
@table @kbd
@code{nil}, no pre-fetching will be done.
@vindex gnus-async-prefetch-article-p
-@findex gnus-async-read-p
+@findex gnus-async-unread-p
There are probably some articles that you don't want to pre-fetch---read
articles, for instance. The @code{gnus-async-prefetch-article-p}
variable controls whether an article is to be pre-fetched. This
function should return non-@code{nil} when the article in question is
-to be pre-fetched. The default is @code{gnus-async-read-p}, which
+to be pre-fetched. The default is @code{gnus-async-unread-p}, which
returns @code{nil} on read articles. The function is called with an
article data structure as the only parameter.
@vindex gnus-cite-parse-max-size
@item gnus-cite-parse-max-size
-If the article size if bigger than this variable (which is 25000 by
-default), no citation highlighting will be performed.
+If the article size in bytes is bigger than this variable (which is
+25000 by default), no citation highlighting will be performed.
@item gnus-cite-max-prefix
@vindex gnus-cite-max-prefix
message ID or a mail address. If it is one of the symbols @code{mid} or
@code{mail}, Gnus will always assume that the string is a message ID or
a mail address, respectively. If this variable is set to the symbol
-@code{ask}, always query the user what do do. If it is a function, this
+@code{ask}, always query the user what to do. If it is a function, this
function will be called with the string as its only argument. The
function must return @code{mid}, @code{mail}, @code{invalid} or
@code{ask}. The default value is the function
@item B e
@kindex B e (Summary)
@findex gnus-summary-expire-articles
+@cindex expiring mail
Run all expirable articles in the current group through the expiry
process (@code{gnus-summary-expire-articles}). That is, delete all
expirable articles in the group that have been around for a while.
@item B C-M-e
@kindex B C-M-e (Summary)
@findex gnus-summary-expire-articles-now
+@cindex expiring mail
Delete all the expirable articles in the group
(@code{gnus-summary-expire-articles-now}). This means that @strong{all}
articles eligible for expiry in the current group will
Remove the @code{To} header if it only contains the address identical to
the current group's @code{to-list} parameter.
@item cc-list
-Remove the @code{CC} header if it only contains the address identical to
+Remove the @code{Cc} header if it only contains the address identical to
the current group's @code{to-list} parameter.
@item date
Remove the @code{Date} header if the article is less than three days
old.
@item long-to
-Remove the @code{To} header if it is very long.
+Remove the @code{To} and/or @code{Cc} header if it is very long.
@item many-to
-Remove all @code{To} headers if there are more than one.
+Remove all @code{To} and/or @code{Cc} headers if there are more than one.
@end table
To include these three elements, you could say something like:
type of the part. This variable is ignored if the value of the
controlling variable is a predicate list, as described above.
+@ifinfo
+@c Avoid sort of redundant entries in the same section for the printed
+@c manual, but add them in info to allow `i gnus-treat-foo-bar RET' or
+@c `i foo-bar'.
+@vindex gnus-treat-buttonize
+@vindex gnus-treat-buttonize-head
+@vindex gnus-treat-capitalize-sentences
+@vindex gnus-treat-overstrike
+@vindex gnus-treat-strip-cr
+@vindex gnus-treat-strip-headers-in-body
+@vindex gnus-treat-strip-leading-blank-lines
+@vindex gnus-treat-strip-multiple-blank-lines
+@vindex gnus-treat-strip-pem
+@vindex gnus-treat-strip-trailing-blank-lines
+@vindex gnus-treat-unsplit-urls
+@vindex gnus-treat-wash-html
+@vindex gnus-treat-date-english
+@vindex gnus-treat-date-iso8601
+@vindex gnus-treat-date-lapsed
+@vindex gnus-treat-date-local
+@vindex gnus-treat-date-original
+@vindex gnus-treat-date-user-defined
+@vindex gnus-treat-date-ut
+@vindex gnus-treat-from-picon
+@vindex gnus-treat-mail-picon
+@vindex gnus-treat-newsgroups-picon
+@vindex gnus-treat-display-smileys
+@vindex gnus-treat-body-boundary
+@vindex gnus-treat-display-x-face
+@vindex gnus-treat-display-face
+@vindex gnus-treat-emphasize
+@vindex gnus-treat-fill-article
+@vindex gnus-treat-fill-long-lines
+@vindex gnus-treat-hide-boring-headers
+@vindex gnus-treat-hide-citation
+@vindex gnus-treat-hide-citation-maybe
+@vindex gnus-treat-hide-headers
+@vindex gnus-treat-hide-signature
+@vindex gnus-treat-strip-banner
+@vindex gnus-treat-strip-list-identifiers
+@vindex gnus-treat-highlight-citation
+@vindex gnus-treat-highlight-headers
+@vindex gnus-treat-highlight-signature
+@vindex gnus-treat-play-sounds
+@vindex gnus-treat-translate
+@vindex gnus-treat-x-pgp-sig
+@vindex gnus-treat-unfold-headers
+@vindex gnus-treat-fold-headers
+@vindex gnus-treat-fold-newsgroups
+@vindex gnus-treat-leading-whitespace
+@end ifinfo
+
The following treatment options are available. The easiest way to
customize this is to examine the @code{gnus-article-treat} customization
group. Values in parenthesis are suggested sensible values. Others are
@xref{Smileys}.
+@vindex gnus-treat-display-x-face
@item gnus-treat-display-x-face (head)
@xref{X-Face}.
+@vindex gnus-treat-display-face
@item gnus-treat-display-face (head)
@xref{Face}.
+@vindex gnus-treat-emphasize
@item gnus-treat-emphasize (t, head, integer)
+@vindex gnus-treat-fill-article
@item gnus-treat-fill-article (t, integer)
+@vindex gnus-treat-fill-long-lines
@item gnus-treat-fill-long-lines (t, integer)
+@vindex gnus-treat-hide-boring-headers
@item gnus-treat-hide-boring-headers (head)
+@vindex gnus-treat-hide-citation
@item gnus-treat-hide-citation (t, integer)
+@vindex gnus-treat-hide-citation-maybe
@item gnus-treat-hide-citation-maybe (t, integer)
+@vindex gnus-treat-hide-headers
@item gnus-treat-hide-headers (head)
+@vindex gnus-treat-hide-signature
@item gnus-treat-hide-signature (t, last)
+@vindex gnus-treat-strip-banner
@item gnus-treat-strip-banner (t, last)
+@vindex gnus-treat-strip-list-identifiers
@item gnus-treat-strip-list-identifiers (head)
@xref{Article Hiding}.
+@vindex gnus-treat-highlight-citation
@item gnus-treat-highlight-citation (t, integer)
+@vindex gnus-treat-highlight-headers
@item gnus-treat-highlight-headers (head)
+@vindex gnus-treat-highlight-signature
@item gnus-treat-highlight-signature (t, last, integer)
@xref{Article Highlighting}.
+@vindex gnus-treat-play-sounds
@item gnus-treat-play-sounds
+@vindex gnus-treat-translate
@item gnus-treat-translate
+@vindex gnus-treat-x-pgp-sig
@item gnus-treat-x-pgp-sig (head)
+@vindex gnus-treat-unfold-headers
@item gnus-treat-unfold-headers (head)
+@vindex gnus-treat-fold-headers
@item gnus-treat-fold-headers (head)
+@vindex gnus-treat-fold-newsgroups
@item gnus-treat-fold-newsgroups (head)
+@vindex gnus-treat-leading-whitespace
@item gnus-treat-leading-whitespace (head)
@xref{Article Header}.
@kindex v (Article)
@cindex keys, reserved for users (Article)
-The key @kbd{v} is reserved for users. You can bind it key to some
-function or better use it as a prefix key.
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key.
A few additional keystrokes are available:
@item gnus-single-article-buffer
@vindex gnus-single-article-buffer
+@cindex article buffers, several
If non-@code{nil}, use the same article buffer for all the groups.
(This is the default.) If @code{nil}, each group will have its own
article buffer.
@cindex User-Agent
This variable controls which information should be exposed in the
-User-Agent header. It can be one of the symbols @code{gnus} (show only
-Gnus version), @code{emacs-gnus} (show only Emacs and Gnus versions),
-@code{emacs-gnus-config} (same as @code{emacs-gnus} plus system
-configuration), @code{emacs-gnus-type} (same as @code{emacs-gnus} plus
-system type) or a custom string. If you set it to a string, be sure to
-use a valid format, see RFC 2616.
+User-Agent header. It can be a list of symbols or a string. Valid
+symbols are @code{gnus} (show Gnus version) and @code{emacs} (show Emacs
+version). In addition to the Emacs version, you can add @code{codename}
+(show (S)XEmacs codename) or either @code{config} (show system
+configuration) or @code{type} (show system type). If you set it to a
+string, be sure to use a valid format, see RFC 2616.
@end table
* IMAP:: Using Gnus as a @acronym{IMAP} client.
* Other Sources:: Reading directories, files, SOUP packets.
* Combined Groups:: Combining groups into one group.
+* Email Based Diary:: Using mails to manage diary events in Gnus.
* Gnus Unplugged:: Reading news and mail offline.
@end menu
@item v
@kindex v (Server)
@cindex keys, reserved for users (Server)
-The key @kbd{v} is reserved for users. You can bind it key to some
-function or better use it as a prefix key.
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key.
@item a
@kindex a (Server)
two categories: direct connection functions (four pre-made), and
indirect ones (two pre-made).
+@item nntp-never-echoes-commands
+@vindex nntp-never-echoes-commands
+Non-@code{nil} means the nntp server never echoes commands. It is
+reported that some nntps server doesn't echo commands. So, you may want
+to set this to non-@code{nil} in the method for such a server setting
+@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for
+example. The default value is @code{nil}. Note that the
+@code{nntp-open-connection-functions-never-echo-commands} variable
+overrides the @code{nil} value of this variable.
+
+@item nntp-open-connection-functions-never-echo-commands
+@vindex nntp-open-connection-functions-never-echo-commands
+List of functions that never echo commands. Add or set a function which
+you set to @code{nntp-open-connection-function} to this list if it does
+not echo commands. Note that a non-@code{nil} value of the
+@code{nntp-never-echoes-commands} variable overrides this variable. The
+default value is @code{(nntp-open-network-stream)}.
+
@item nntp-prepare-post-hook
@vindex nntp-prepare-post-hook
A hook run just before posting an article. If there is no
@code{nnmail-split-header-length-limit} are excluded from the split
function.
-@vindex nnmail-mail-splitting-charset
@vindex nnmail-mail-splitting-decodes
-By default the splitting codes @acronym{MIME} decodes headers so you
-can match on non-@acronym{ASCII} strings. The
-@code{nnmail-mail-splitting-charset} variable specifies the default
-charset for decoding. The behavior can be turned off completely by
-binding @code{nnmail-mail-splitting-decodes} to @code{nil}, which is
-useful if you want to match articles based on the raw header data.
+@vindex nnmail-mail-splitting-charset
+By default, splitting does not decode headers, so you can not match on
+non-@acronym{ASCII} strings. But it is useful if you want to match
+articles based on the raw header data. To enable it, set the
+@code{nnmail-mail-splitting-decodes} variable to a non-@code{nil} value.
+In addition, the value of the @code{nnmail-mail-splitting-charset}
+variable is used for decoding non-@acronym{MIME} encoded string when
+@code{nnmail-mail-splitting-decodes} is non-@code{nil}. The default
+value is @code{nil} which means not to decode non-@acronym{MIME} encoded
+string. A suitable value for you will be @code{undecided} or be the
+charset used normally in mails you are interested in.
@vindex nnmail-resplit-incoming
By default, splitting is performed on all incoming messages. If you
rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP
@end example
-Alter this script to fit find the @samp{movemail} you want to use.
+Alter this script to fit the @samp{movemail} and temporary
+file you want to use.
@item directory
@item mail-source-delete-old-incoming-confirm
@vindex mail-source-delete-old-incoming-confirm
-If non-@code{nil}, ask for for confirmation before deleting old incoming
+If non-@code{nil}, ask for confirmation before deleting old incoming
files. This variable only applies when
@code{mail-source-delete-incoming} is a positive number.
@node Expiring Mail
@subsection Expiring Mail
@cindex article expiry
+@cindex expiring mail
Traditional mail readers have a tendency to remove mail articles when
you mark them as read, in some way. Gnus takes a fundamentally
@item nnimap-expunge-search-string
@cindex expunging
@vindex nnimap-expunge-search-string
+@cindex expiring @acronym{IMAP} mail
This variable contain the @acronym{IMAP} search command sent to server when
searching for articles eligible for expiring. The default is
messages instead of the internal article date. See section 6.4.4 of
RFC 2060 for more information on valid strings.
+However, if @code{nnimap-search-uids-not-since-is-evil}
+is true, this variable has no effect since the search logic
+is reversed, as described below.
+
@item nnimap-authinfo-file
@vindex nnimap-authinfo-file
seem to need this under some circumstances; it was reported that
Courier 1.7.1 did.
+@item nnimap-nov-is-evil
+@vindex nnimap-nov-is-evil
+@cindex Courier @acronym{IMAP} server
+@cindex @acronym{NOV}
+
+Never generate or use a local @acronym{NOV} database. Defaults to the
+value of @code{gnus-agent}.
+
+Using a @acronym{NOV} database usually makes header fetching much
+faster, but it uses the @code{UID SEARCH UID} command, which is very
+slow on some servers (notably some versions of Courier). Since the Gnus
+Agent caches the information in the @acronym{NOV} database without using
+the slow command, this variable defaults to true if the Agent is in use,
+and false otherwise.
+
+@item nnimap-search-uids-not-since-is-evil
+@vindex nnimap-search-uids-not-since-is-evil
+@cindex Courier @acronym{IMAP} server
+@cindex expiring @acronym{IMAP} mail
+
+Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE
+@var{date}} command, which is slow on some @acronym{IMAP} servers
+(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE
+@var{date}} and prune the list of expirable articles within Gnus.
+
+When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a
+list of expirable articles and asks the IMAP server questions like ``Of
+these articles, which ones are older than a week?'' While this seems
+like a perfectly reasonable question, some IMAP servers take a long time
+to answer it, since they seemingly go looking into every old article to
+see if it is one of the expirable ones. Curiously, the question ``Of
+@emph{all} articles, which ones are newer than a week?'' seems to be
+much faster to answer, so setting this variable causes Gnus to ask this
+question and figure out the answer to the real question itself.
+
+This problem can really sneak up on you: when you first configure Gnus,
+everything works fine, but once you accumulate a couple thousand
+messages, you start cursing Gnus for being so slow. On the other hand,
+if you get a lot of email within a week, setting this variable will
+cause a lot of network traffic between Gnus and the IMAP server.
+
@end table
@menu
@node Expiring in IMAP
@subsection Expiring in IMAP
-@cindex expiring imap mail
+@cindex expiring @acronym{IMAP} mail
Even though @code{nnimap} is not a proper @code{nnmail} derived back
end, it supports most features in regular expiring (@pxref{Expiring
your server must support permanent storage of client specific flags on
messages. Most do, fortunately.
+If expiring @acronym{IMAP} mail seems very slow, try setting the server
+variable @code{nnimap-search-uids-not-since-is-evil}.
+
@table @code
@item nnmail-expiry-wait
their @acronym{NOV} lines removed from the @acronym{NOV} file.
+@node Email Based Diary
+@section Email Based Diary
+@cindex diary
+@cindex email based diary
+@cindex calendar
+
+This section describes a special mail back end called @code{nndiary},
+and its companion library @code{gnus-diary}. It is ``special'' in the
+sense that it is not meant to be one of the standard alternatives for
+reading mail with Gnus. See @ref{Choosing a Mail Back End} for that.
+Instead, it is used to treat @emph{some} of your mails in a special way,
+namely, as event reminders.
+
+Here is a typical scenario:
+
+@itemize @bullet
+@item
+You've got a date with Andy Mc Dowell or Bruce Willis (select according
+to your sexual preference) in one month. You don't want to forget it.
+@item
+So you send a ``reminder'' message (actually, a diary one) to yourself.
+@item
+You forget all about it and keep on getting and reading new mail, as usual.
+@item
+From time to time, as you type `g' in the group buffer and as the date
+is getting closer, the message will pop up again to remind you of your
+appointment, just as if it were new and unread.
+@item
+Read your ``new'' messages, this one included, and start dreaming again
+of the night you're gonna have.
+@item
+Once the date is over (you actually fell asleep just after dinner), the
+message will be automatically deleted if it is marked as expirable.
+@end itemize
+
+The Gnus Diary back end has the ability to handle regular appointments
+(that wouldn't ever be deleted) as well as punctual ones, operates as a
+real mail back end and is configurable in many ways. All of this is
+explained in the sections below.
+
+@menu
+* The NNDiary Back End:: Basic setup and usage.
+* The Gnus Diary Library:: Utility toolkit on top of nndiary.
+* Sending or Not Sending:: A final note on sending diary messages.
+@end menu
+
+
+@node The NNDiary Back End
+@subsection The NNDiary Back End
+@cindex nndiary
+@cindex the nndiary back end
+
+@code{nndiary} is a back end very similar to @code{nnml} (@pxref{Mail
+Spool}). Actually, it could appear as a mix of @code{nnml} and
+@code{nndraft}. If you know @code{nnml}, you're already familiar with
+the message storing scheme of @code{nndiary}: one file per message, one
+directory per group.
+
+ Before anything, there is one requirement to be able to run
+@code{nndiary} properly: you @emph{must} use the group timestamp feature
+of Gnus. This adds a timestamp to each group's parameters. @ref{Group
+Timestamp} to see how it's done.
+
+@menu
+* Diary Messages:: What makes a message valid for nndiary.
+* Running NNDiary:: NNDiary has two modes of operation.
+* Customizing NNDiary:: Bells and whistles.
+@end menu
+
+@node Diary Messages
+@subsubsection Diary Messages
+@cindex nndiary messages
+@cindex nndiary mails
+
+@code{nndiary} messages are just normal ones, except for the mandatory
+presence of 7 special headers. These headers are of the form
+@code{X-Diary-<something>}, @code{<something>} being one of
+@code{Minute}, @code{Hour}, @code{Dom}, @code{Month}, @code{Year},
+@code{Time-Zone} and @code{Dow}. @code{Dom} means ``Day of Month'', and
+@code{dow} means ``Day of Week''. These headers actually behave like
+crontab specifications and define the event date(s):
+
+@itemize @bullet
+@item
+For all headers except the @code{Time-Zone} one, a header value is
+either a star (meaning all possible values), or a list of fields
+(separated by a comma).
+@item
+A field is either an integer, or a range.
+@item
+A range is two integers separated by a dash.
+@item
+Possible integer values are 0--59 for @code{Minute}, 0--23 for
+@code{Hour}, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971
+for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday).
+@item
+As a special case, a star in either @code{Dom} or @code{Dow} doesn't
+mean ``all possible values'', but ``use only the other field''. Note
+that if both are star'ed, the use of either one gives the same result.
+@item
+The @code{Time-Zone} header is special in that it can only have one
+value (@code{GMT}, for instance). A star doesn't mean ``all possible
+values'' (because it makes no sense), but ``the current local time
+zone''. Most of the time, you'll be using a star here. However, for a
+list of available time zone values, see the variable
+@code{nndiary-headers}.
+@end itemize
+
+As a concrete example, here are the diary headers to add to your message
+for specifying ``Each Monday and each 1st of month, at 12:00, 20:00,
+21:00, 22:00, 23:00 and 24:00, from 1999 to 2010'' (I'll let you find
+what to do then):
+
+@example
+X-Diary-Minute: 0
+X-Diary-Hour: 12, 20-24
+X-Diary-Dom: 1
+X-Diary-Month: *
+X-Diary-Year: 1999-2010
+X-Diary-Dow: 1
+X-Diary-Time-Zone: *
+@end example
+
+@node Running NNDiary
+@subsubsection Running NNDiary
+@cindex running nndiary
+@cindex nndiary operation modes
+
+@code{nndiary} has two modes of operation: ``traditional'' (the default)
+and ``autonomous''. In traditional mode, @code{nndiary} does not get new
+mail by itself. You have to move (@kbd{B m}) or copy (@kbd{B c}) mails
+from your primary mail back end to nndiary groups in order to handle them
+as diary messages. In autonomous mode, @code{nndiary} retrieves its own
+mail and handles it independently from your primary mail back end.
+
+One should note that Gnus is not inherently designed to allow several
+``master'' mail back ends at the same time. However, this does make
+sense with @code{nndiary}: you really want to send and receive diary
+messages to your diary groups directly. So, @code{nndiary} supports
+being sort of a ``second primary mail back end'' (to my knowledge, it is
+the only back end offering this feature). However, there is a limitation
+(which I hope to fix some day): respooling doesn't work in autonomous
+mode.
+
+In order to use @code{nndiary} in autonomous mode, you have several
+things to do:
+
+@itemize @bullet
+@item
+Allow @code{nndiary} to retrieve new mail by itself. Put the following
+line in your @file{~/.gnus.el} file:
+
+@lisp
+(setq nndiary-get-new-mail t)
+@end lisp
+@item
+You must arrange for diary messages (those containing @code{X-Diary-*}
+headers) to be split in a private folder @emph{before} Gnus treat them.
+Again, this is needed because Gnus cannot (yet ?) properly handle
+multiple primary mail back ends. Getting those messages from a separate
+source will compensate this misfeature to some extent.
+
+As an example, here's my procmailrc entry to store diary files in
+@file{~/.nndiary} (the default @code{nndiary} mail source file):
+
+@example
+:0 HD :
+* ^X-Diary
+.nndiary
+@end example
+@end itemize
+
+Once this is done, you might want to customize the following two options
+that affect the diary mail retrieval and splitting processes:
+
+@defvar nndiary-mail-sources
+This is the diary-specific replacement for the standard
+@code{mail-sources} variable. It obeys the same syntax, and defaults to
+@code{(file :path "~/.nndiary")}.
+@end defvar
+
+@defvar nndiary-split-methods
+This is the diary-specific replacement for the standard
+@code{nnmail-split-methods} variable. It obeys the same syntax.
+@end defvar
+
+ Finally, you may add a permanent @code{nndiary} virtual server
+(something like @code{(nndiary "diary")} should do) to your
+@code{gnus-secondary-select-methods}.
+
+ Hopefully, almost everything (see the TODO section in
+@file{nndiary.el}) will work as expected when you restart Gnus: in
+autonomous mode, typing @kbd{g} and @kbd{M-g} in the group buffer, will
+also get your new diary mails and split them according to your
+diary-specific rules, @kbd{F} will find your new diary groups etc.
+
+@node Customizing NNDiary
+@subsubsection Customizing NNDiary
+@cindex customizing nndiary
+@cindex nndiary customization
+
+Now that @code{nndiary} is up and running, it's time to customize it.
+The custom group is called @code{nndiary} (no, really ?!). You should
+browse it to figure out which options you'd like to tweak. The following
+two variables are probably the only ones you will want to change:
+
+@defvar nndiary-reminders
+This is the list of times when you want to be reminded of your
+appointments (e.g. 3 weeks before, then 2 days before, then 1 hour
+before and that's it). Remember that ``being reminded'' means that the
+diary message will pop up as brand new and unread again when you get new
+mail.
+@end defvar
+
+@defvar nndiary-week-starts-on-monday
+Rather self-explanatory. Otherwise, Sunday is assumed (this is the
+default).
+@end defvar
+
+
+@node The Gnus Diary Library
+@subsection The Gnus Diary Library
+@cindex gnus-diary
+@cindex the gnus diary library
+
+Using @code{nndiary} manually (I mean, writing the headers by hand and
+so on) would be rather boring. Fortunately, there is a library called
+@code{gnus-diary} written on top of @code{nndiary}, that does many
+useful things for you.
+
+ In order to use it, add the following line to your @file{~/.gnus.el} file:
+
+@lisp
+(require 'gnus-diary)
+@end lisp
+
+ Also, you shouldn't use any @code{gnus-user-format-function-[d|D]}
+(@pxref{Summary Buffer Lines}). @code{gnus-diary} provides both of these
+(sorry if you used them before).
+
+
+@menu
+* Diary Summary Line Format:: A nicer summary buffer line format.
+* Diary Articles Sorting:: A nicer way to sort messages.
+* Diary Headers Generation:: Not doing it manually.
+* Diary Group Parameters:: Not handling them manually.
+@end menu
+
+@node Diary Summary Line Format
+@subsubsection Diary Summary Line Format
+@cindex diary summary buffer line
+@cindex diary summary line format
+
+Displaying diary messages in standard summary line format (usually
+something like @samp{From Joe: Subject}) is pretty useless. Most of
+the time, you're the one who wrote the message, and you mostly want to
+see the event's date.
+
+ @code{gnus-diary} provides two supplemental user formats to be used in
+summary line formats. @code{D} corresponds to a formatted time string
+for the next occurrence of the event (e.g. ``Sat, Sep 22 01, 12:00''),
+while @code{d} corresponds to an approximative remaining time until the
+next occurrence of the event (e.g. ``in 6 months, 1 week'').
+
+ For example, here's how Joe's birthday is displayed in my
+@code{nndiary+diary:birthdays} summary buffer (note that the message is
+expirable, but will never be deleted, as it specifies a periodic event):
+
+@example
+ E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week)
+@end example
+
+In order to get something like the above, you would normally add the
+following line to your diary groups'parameters:
+
+@lisp
+(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n")
+@end lisp
+
+However, @code{gnus-diary} does it automatically (@pxref{Diary Group
+Parameters}). You can however customize the provided summary line format
+with the following user options:
+
+@defvar gnus-diary-summary-line-format
+Defines the summary line format used for diary groups (@pxref{Summary
+Buffer Lines}). @code{gnus-diary} uses it to automatically update the
+diary groups'parameters.
+@end defvar
+
+@defvar gnus-diary-time-format
+Defines the format to display dates in diary summary buffers. This is
+used by the @code{D} user format. See the docstring for details.
+@end defvar
+
+@defvar gnus-diary-delay-format-function
+Defines the format function to use for displaying delays (remaining
+times) in diary summary buffers. This is used by the @code{d} user
+format. There are currently built-in functions for English and French;
+you can also define your own. See the docstring for details.
+@end defvar
+
+@node Diary Articles Sorting
+@subsubsection Diary Articles Sorting
+@cindex diary articles sorting
+@cindex diary summary lines sorting
+@findex gnus-summary-sort-by-schedule
+@findex gnus-thread-sort-by-schedule
+@findex gnus-article-sort-by-schedule
+
+@code{gnus-diary} provides new sorting functions (@pxref{Sorting the
+Summary Buffer} ) called @code{gnus-summary-sort-by-schedule},
+@code{gnus-thread-sort-by-schedule} and
+@code{gnus-article-sort-by-schedule}. These functions let you organize
+your diary summary buffers from the closest event to the farthest one.
+
+@code{gnus-diary} automatically installs
+@code{gnus-summary-sort-by-schedule} as a menu item in the summary
+buffer's ``sort'' menu, and the two others as the primary (hence
+default) sorting functions in the group parameters (@pxref{Diary Group
+Parameters}).
+
+@node Diary Headers Generation
+@subsubsection Diary Headers Generation
+@cindex diary headers generation
+@findex gnus-diary-check-message
+
+@code{gnus-diary} provides a function called
+@code{gnus-diary-check-message} to help you handle the @code{X-Diary-*}
+headers. This function ensures that the current message contains all the
+required diary headers, and prompts you for values or corrections if
+needed.
+
+ This function is hooked into the @code{nndiary} back end, so that
+moving or copying an article to a diary group will trigger it
+automatically. It is also bound to @kbd{C-c D c} in @code{message-mode}
+and @code{article-edit-mode} in order to ease the process of converting
+a usual mail to a diary one.
+
+ This function takes a prefix argument which will force prompting of
+all diary headers, regardless of their presence or validity. That way,
+you can very easily reschedule an already valid diary message, for
+instance.
+
+@node Diary Group Parameters
+@subsubsection Diary Group Parameters
+@cindex diary group parameters
+
+When you create a new diary group, or visit one, @code{gnus-diary}
+automatically checks your group parameters and if needed, sets the
+summary line format to the diary-specific value, installs the
+diary-specific sorting functions, and also adds the different
+@code{X-Diary-*} headers to the group's posting-style. It is then easier
+to send a diary message, because if you use @kbd{C-u a} or @kbd{C-u m}
+on a diary group to prepare a message, these headers will be inserted
+automatically (although not filled with proper values yet).
+
+@node Sending or Not Sending
+@subsection Sending or Not Sending
+
+Well, assuming you've read all of the above, here are two final notes on
+mail sending with @code{nndiary}:
+
+@itemize @bullet
+@item
+@code{nndiary} is a @emph{real} mail back end. You really send real diary
+messsages for real. This means for instance that you can give
+appointments to anybody (provided they use Gnus and @code{nndiary}) by
+sending the diary message to them as well.
+@item
+However, since @code{nndiary} also has a @code{request-post} method, you
+can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the
+message won't actually be sent; just stored locally in the group. This
+comes in very handy for private appointments.
+@end itemize
+
@node Gnus Unplugged
@section Gnus Unplugged
@cindex offline
@findex gnus-agent-expire-group
@cindex agent expiry
@cindex Gnus agent expiry
-@cindex expiry
+@cindex expiry, in Gnus agent
The Agent back end, @code{nnagent}, doesn't handle expiry. Well, at
least it doesn't handle it like other back ends. Instead, there are
@example
#!/bin/sh
-emacs -batch -l ~/.emacs -l ~/.gnus.el gnus-agent-batch >/dev/null 2>&1
+emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1
@end example
@section Image Enhancements
XEmacs, as well as Emacs 21@footnote{Emacs 21 on MS Windows doesn't
-support images yet.}, is able to display pictures and stuff, so Gnus has
-taken advantage of that.
+support images, Emacs 22 does.} and up, are able to display pictures and
+stuff, so Gnus has taken advantage of that.
@menu
* X-Face:: Display a funky, teensy black-and-white image.
has image support the default action is to display the face before the
@code{From} header. If there's no native @code{X-Face} support, Gnus
will try to convert the @code{X-Face} header using external programs
-from the @code{pbmplus} package and friends. For XEmacs it's faster if
-XEmacs has been compiled with @code{X-Face} support. The default action
-under Emacs without image support is to fork off the @code{display}
-program.
+from the @code{pbmplus} package and friends, see below. For XEmacs it's
+faster if XEmacs has been compiled with @code{X-Face} support. The
+default action under Emacs without image support is to fork off the
+@code{display} program.
-On a GNU/Linux system, the @code{display} program is from the
+On a GNU/Linux system, the @code{display} program is included in the
ImageMagick package. For external conversion programs look for packages
with names like @code{netpbm}, @code{libgr-progs} and @code{compface}.
-
-The variable that controls this is the
-@code{gnus-article-x-face-command} variable. If this variable is a
+On Windows, you may use the packages @code{netpbm} and @code{compface}
+from @url{http://gnuwin32.sourceforge.net}. You need to add the
+@code{bin} directory to your @code{PATH} environment variable.
+@c In fact only the following DLLs and binaries seem to be required:
+@c compface1.dll uncompface.exe libnetpbm10.dll icontopbm.exe
+
+The variable @code{gnus-article-x-face-command} controls which programs
+are used to display the @code{X-Face} header. If this variable is a
string, this string will be executed in a sub-shell. If it is a
function, this function will be called with the face as the argument.
-If @code{gnus-article-x-face-too-ugly} (which is a regexp) matches
-the @code{From} header, the face will not be shown.
+If @code{gnus-article-x-face-too-ugly} (which is a regexp) matches the
+@code{From} header, the face will not be shown.
(Note: @code{x-face} is used in the variable/function names, not
@code{xface}).
(gnus-registry-initialize)
(spam-initialize)
-;; @r{I like @kbd{C-s} for marking spam}
-(define-key gnus-summary-mode-map "\C-s" 'gnus-summary-mark-as-spam)
-
(setq
spam-log-to-registry t ; @r{for spam autodetection}
spam-use-BBDB t
the default value of @samp{spam}.
@end defvar
-@defvar spam-ifile-database-path
+@defvar spam-ifile-database
This is the filename for the ifile database. It is not specified by
default, so ifile will use its own default database name.
@subsection Dired
@cindex dired
-@code{gnus-dired-minor-mode} provided some useful functions for dired
+@code{gnus-dired-minor-mode} provides some useful functions for dired
buffers. It is enabled with
@lisp
(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
@table @kbd
@item C-c C-m C-a
@findex gnus-dired-attach
+@cindex attachments, selection via dired
Send dired's marked files as an attachment (@code{gnus-dired-attach}).
You will be prompted for a message buffer.
@page
@include gnus-faq.texi
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+@include doclicense.texi
+
@node Index
@chapter Index
@printindex cp
HCoop / bpt / emacs.git / blobdiff