[Emacs-diffs] Changes to emacs/man/gnus.texi,v

[Reiner Steib]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Reiner Steib <rsteib>   07/05/09 19:07:32

Index: gnus.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/gnus.texi,v
retrieving revision 1.112
retrieving revision 1.113
diff -u -b -r1.112 -r1.113
--- gnus.texi   1 May 2007 23:00:38 -0000       1.112
+++ gnus.texi   9 May 2007 19:07:32 -0000       1.113
@@ -623,6 +623,7 @@
 * 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
@@ -720,6 +721,25 @@
 * 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.
@@ -12343,6 +12363,7 @@
 * 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
 
@@ -17878,6 +17899,381 @@
 their @acronym{NOV} lines removed from the @acronym{NOV} file.
 
 
address@hidden Email Based Diary
address@hidden Email Based Diary
address@hidden diary
address@hidden email based diary
address@hidden 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:
+
address@hidden @bullet
address@hidden
+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.
address@hidden
+So you send a ``reminder'' message (actually, a diary one) to yourself.
address@hidden
+You forget all about it and keep on getting and reading new mail, as usual.
address@hidden
+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.
address@hidden
+Read your ``new'' messages, this one included, and start dreaming again
+of the night you're gonna have.
address@hidden
+Once the date is over (you actually fell asleep just after dinner), the
+message will be automatically deleted if it is marked as expirable.
address@hidden 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.
+
address@hidden
+* 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.
address@hidden menu
+
+
address@hidden The NNDiary Back End
address@hidden The NNDiary Back End
address@hidden nndiary
address@hidden the nndiary back end
+
address@hidden is a back end very similar to @code{nnml} (@pxref{Mail
+Spool}).  Actually, it could appear as a mix of @code{nnml} and
address@hidden  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
address@hidden 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.
+
address@hidden
+* Diary Messages::              What makes a message valid for nndiary.
+* Running NNDiary::             NNDiary has two modes of operation.
+* Customizing NNDiary::         Bells and whistles.
address@hidden menu
+
address@hidden Diary Messages
address@hidden Diary Messages
address@hidden nndiary messages
address@hidden nndiary mails
+
address@hidden messages are just normal ones, except for the mandatory
+presence of 7 special headers.  These headers are of the form
address@hidden<something>}, @code{<something>} being one of
address@hidden, @code{Hour}, @code{Dom}, @code{Month}, @code{Year},
address@hidden and @code{Dow}.  @code{Dom} means ``Day of Month'', and
address@hidden means ``Day of Week''.  These headers actually behave like
+crontab specifications and define the event date(s):
+
address@hidden @bullet
address@hidden
+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).
address@hidden
+A field is either an integer, or a range.
address@hidden
+A range is two integers separated by a dash.
address@hidden
+Possible integer values are 0--59 for @code{Minute}, 0--23 for
address@hidden, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971
+for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday).
address@hidden
+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.
address@hidden
+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
address@hidden
address@hidden 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):
+
address@hidden
+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: *
address@hidden example
+
address@hidden Running NNDiary
address@hidden Running NNDiary
address@hidden running nndiary
address@hidden nndiary operation modes
+
address@hidden 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:
+
address@hidden @bullet
address@hidden
+Allow @code{nndiary} to retrieve new mail by itself.  Put the following
+line in your @file{~/.gnus.el} file:
+
address@hidden
+(setq nndiary-get-new-mail t)
address@hidden lisp
address@hidden
+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
address@hidden/.nndiary} (the default @code{nndiary} mail source file):
+
address@hidden
+:0 HD :
+* ^X-Diary
+.nndiary
address@hidden example
address@hidden itemize
+
+Once this is done, you might want to customize the following two options
+that affect the diary mail retrieval and splitting processes:
+
address@hidden nndiary-mail-sources
+This is the diary-specific replacement for the standard
address@hidden variable.  It obeys the same syntax, and defaults to
address@hidden(file :path "~/.nndiary")}.
address@hidden defvar
+
address@hidden nndiary-split-methods
+This is the diary-specific replacement for the standard
address@hidden variable.  It obeys the same syntax.
address@hidden defvar
+
+  Finally, you may add a permanent @code{nndiary} virtual server
+(something like @code{(nndiary "diary")} should do) to your
address@hidden
+
+  Hopefully, almost everything (see the TODO section in
address@hidden) 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.
+
address@hidden Customizing NNDiary
address@hidden Customizing NNDiary
address@hidden customizing nndiary
address@hidden 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:
+
address@hidden nndiary-reminders
+This is the list of times when you want to be reminded of your
+appointements (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.
address@hidden defvar
+
address@hidden nndiary-week-starts-on-monday
+Rather self-explanatory.  Otherwise, Sunday is assumed (this is the
+default).
address@hidden defvar
+
+
address@hidden The Gnus Diary Library
address@hidden The Gnus Diary Library
address@hidden gnus-diary
address@hidden 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
address@hidden 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:
+
address@hidden
+(require 'gnus-diary)
address@hidden 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).
+
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Diary Summary Line Format
address@hidden Diary Summary Line Format
address@hidden diary summary buffer line
address@hidden 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
address@hidden:birthdays} summary buffer (note that the message is
+expirable, but will never be deleted, as it specifies a periodic event):
+
address@hidden
+   E  Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week)
address@hidden example
+
+In order to get something like the above, you would normally add the
+following line to your diary groups'parameters:
+
address@hidden
+(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n")
address@hidden 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:
+
address@hidden 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.
address@hidden defvar
+
address@hidden 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.
address@hidden defvar
+
address@hidden 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.
address@hidden defvar
+
address@hidden Diary Articles Sorting
address@hidden Diary Articles Sorting
address@hidden diary articles sorting
address@hidden diary summary lines sorting
address@hidden gnus-summary-sort-by-schedule
address@hidden gnus-thread-sort-by-schedule
address@hidden gnus-article-sort-by-schedule
+
address@hidden provides new sorting functions (@pxref{Sorting the
+Summary Buffer} ) called @code{gnus-summary-sort-by-schedule},
address@hidden and
address@hidden  These functions let you organize
+your diary summary buffers from the closest event to the farthest one.
+
address@hidden automatically installs
address@hidden 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}).
+
address@hidden Diary Headers Generation
address@hidden Diary Headers Generation
address@hidden diary headers generation
address@hidden gnus-diary-check-message
+
address@hidden provides a function called
address@hidden 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.
+
address@hidden Diary Group Parameters
address@hidden Diary Group Parameters
address@hidden 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
address@hidden 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).
+
address@hidden Sending or Not Sending
address@hidden Sending or Not Sending
+
+Well, assuming you've read of of the above, here are two final notes on
+mail sending with @code{nndiary}:
+
address@hidden @bullet
address@hidden
address@hidden is a @emph{real} mail back end.  You really send real diary
+messsages for real.  This means for instance that you can give
+appointements to anybody (provided they use Gnus and @code{nndiary}) by
+sending the diary message to them as well.
address@hidden
+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.
address@hidden itemize
+
 @node Gnus Unplugged
 @section Gnus Unplugged
 @cindex offline