6.8 Email Based Diary

This section describes a special mail back end called nndiary, and its companion library 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 Choosing a Mail Back End for that. Instead, it is used to treat some of your mails in a special way, namely, as event reminders.

Here is a typical scenario:

• 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.
• So you send a “reminder” message (actually, a diary one) to yourself.
• You forget all about it and keep on getting and reading new mail, as usual.
• 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.
• Read your “new” messages, this one included, and start dreaming again of the night you’re gonna have.
• Once the date is over (you actually fell asleep just after dinner), the message will be automatically deleted if it is marked as expirable.

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.

6.8.1 The NNDiary Back End

nndiary is a back end very similar to nnml (see section Mail Spool). Actually, it could appear as a mix of nnml and nndraft. If you know nnml, you’re already familiar with the message storing scheme of nndiary: one file per message, one directory per group.

Before anything, there is one requirement to be able to run nndiary properly: you must use the group timestamp feature of Gnus. This adds a timestamp to each group’s parameters. Group Timestamp to see how it’s done.

6.8.1.1 Diary Messages

nndiary messages are just normal ones, except for the mandatory presence of 7 special headers. These headers are of the form X-Diary-<something>, <something> being one of Minute, Hour, Dom, Month, Year, Time-Zone and Dow. Dom means “Day of Month”, and dow means “Day of Week”. These headers actually behave like crontab specifications and define the event date(s):

• For all headers except the Time-Zone one, a header value is either a star (meaning all possible values), or a list of fields (separated by a comma).
• A field is either an integer, or a range.
• A range is two integers separated by a dash.
• Possible integer values are 0–59 for Minute, 0–23 for Hour, 1–31 for Dom, 1–12 for Month, above 1971 for Year and 0–6 for Dow (0 meaning Sunday).
• As a special case, a star in either Dom or 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.
• The Time-Zone header is special in that it can only have one value (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 nndiary-headers.

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):

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: *

6.8.1.2 Running NNDiary

nndiary has two modes of operation: “traditional” (the default) and “autonomous”. In traditional mode, nndiary does not get new mail by itself. You have to move (B m) or copy (B c) mails from your primary mail back end to nndiary groups in order to handle them as diary messages. In autonomous mode, 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 nndiary: you really want to send and receive diary messages to your diary groups directly. So, 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 nndiary in autonomous mode, you have several things to do:

• Allow nndiary to retrieve new mail by itself. Put the following line in your ‘~/.gnus.el’ file:

  (setq nndiary-get-new-mail t)

• You must arrange for diary messages (those containing X-Diary-* headers) to be split in a private folder 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 ‘~/.nndiary’ (the default nndiary mail source file):

  :0 HD : * ^X-Diary .nndiary

Once this is done, you might want to customize the following two options that affect the diary mail retrieval and splitting processes:

Variable: nndiary-mail-sources

This is the diary-specific replacement for the standard mail-sources variable. It obeys the same syntax, and defaults to (file :path "~/.nndiary").

Variable: nndiary-split-methods

This is the diary-specific replacement for the standard nnmail-split-methods variable. It obeys the same syntax.

Finally, you may add a permanent nndiary virtual server (something like (nndiary "diary") should do) to your gnus-secondary-select-methods.

Hopefully, almost everything (see the TODO section in ‘nndiary.el’) will work as expected when you restart Gnus: in autonomous mode, typing g and M-g in the group buffer, will also get your new diary mails and split them according to your diary-specific rules, F will find your new diary groups etc.

6.8.1.3 Customizing NNDiary

Now that nndiary is up and running, it’s time to customize it. The custom group is called 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:

Variable: 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.

Variable: nndiary-week-starts-on-monday

Rather self-explanatory. Otherwise, Sunday is assumed (this is the default).

6.8.2 The Gnus Diary Library

Using nndiary manually (I mean, writing the headers by hand and so on) would be rather boring. Fortunately, there is a library called gnus-diary written on top of nndiary, that does many useful things for you.

In order to use it, add the following line to your ‘~/.gnus.el’ file:

(require 'gnus-diary)

Also, you shouldn’t use any gnus-user-format-function-[d|D] (see section Summary Buffer Lines). gnus-diary provides both of these (sorry if you used them before).

6.8.2.1 Diary Summary Line Format

Displaying diary messages in standard summary line format (usually something like ‘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.

gnus-diary provides two supplemental user formats to be used in summary line formats. D corresponds to a formatted time string for the next occurrence of the event (e.g., “Sat, Sep 22 01, 12:00”), while d corresponds to an approximate 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 nndiary+diary:birthdays summary buffer (note that the message is expirable, but will never be deleted, as it specifies a periodic event):

   E  Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week)

In order to get something like the above, you would normally add the following line to your diary groups’parameters:

(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n")

However, gnus-diary does it automatically (see section Diary Group Parameters). You can however customize the provided summary line format with the following user options:

Variable: gnus-diary-summary-line-format

Defines the summary line format used for diary groups (see section Summary Buffer Lines). gnus-diary uses it to automatically update the diary groups’parameters.

Variable: gnus-diary-time-format

Defines the format to display dates in diary summary buffers. This is used by the D user format. See the docstring for details.

Variable: 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 d user format. There are currently built-in functions for English and French; you can also define your own. See the docstring for details.

6.8.2.2 Diary Articles Sorting

gnus-diary provides new sorting functions (see section Sorting the Summary Buffer ) called gnus-summary-sort-by-schedule, gnus-thread-sort-by-schedule and gnus-article-sort-by-schedule. These functions let you organize your diary summary buffers from the closest event to the farthest one.

gnus-diary automatically installs 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 (see section Diary Group Parameters).

6.8.2.3 Diary Headers Generation

gnus-diary provides a function called gnus-diary-check-message to help you handle the 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 nndiary back end, so that moving or copying an article to a diary group will trigger it automatically. It is also bound to C-c C-f d in message-mode and 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.

6.8.2.4 Diary Group Parameters

When you create a new diary group, or visit one, 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 X-Diary-* headers to the group’s posting-style. It is then easier to send a diary message, because if you use C-u a or C-u m on a diary group to prepare a message, these headers will be inserted automatically (although not filled with proper values yet).

6.8.3 Sending or Not Sending

Well, assuming you’ve read all of the above, here are two final notes on mail sending with nndiary:

• nndiary is a real mail back end. You really send real diary messages for real. This means for instance that you can give appointments to anybody (provided they use Gnus and nndiary) by sending the diary message to them as well.
• However, since nndiary also has a request-post method, you can also use C-u a instead of 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.

This document was generated on January 25, 2015 using texi2html 1.82.