[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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:

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] 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):

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] 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:

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] 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).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] 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).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] 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).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

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