| blob | be4c73a2b4f7c82d676c7423cf8491c62b070097 |
1 ;;; gnus-diary.el --- Wrapper around the NNDiary Gnus backend
3 ;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005,
4 ;; 2006, 2007 Free Software Foundation, Inc.
6 ;; Author: Didier Verna <didier@xemacs.org>
7 ;; Maintainer: Didier Verna <didier@xemacs.org>
8 ;; Created: Tue Jul 20 10:42:55 1999
9 ;; Keywords: calendar mail news
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published
15 ;; by the Free Software Foundation; either version 2 of the License,
16 ;; or (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful, but
19 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 ;; General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with this program; if not, write to the Free Software
25 ;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
26 ;; MA 02110-1301, USA.
29 ;;; Commentary:
31 ;; Contents management by FCM version 0.1.
33 ;; Description:
34 ;; ===========
36 ;; Gnus-Diary is a wrapper around the NNDiary Gnus backend. It is here to
37 ;; make your nndiary-user life easier in different ways. So, you don't have
38 ;; to use it if you don't want to. But, really, you should.
40 ;; Gnus-Diary offers the following features on top of the NNDiary backend:
42 ;; - A nice summary line format:
43 ;; Displaying diary messages in standard summary line format (usually
44 ;; something like "<From Joe>: <Subject>") is pretty useless. Most of the
45 ;; time, you're the one who wrote the message, and you mostly want to see
46 ;; the event's date. Gnus-Diary offers you a nice summary line format
47 ;; which will do this. By default, a summary line will appear like this:
48 ;;
49 ;; <Event Date>: <Subject> <Remaining time>
50 ;;
51 ;; for example, here's how Joe's birthday is displayed in my
52 ;; "nndiary:birhdays" summary buffer (the message is expirable, but will
53 ;; never be deleted, as it specifies a regular event):
54 ;;
55 ;; E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week)
57 ;; - More article sorting functions:
58 ;; Gnus-Diary adds a new sorting function called
59 ;; `gnus-summary-sort-by-schedule'. This function lets you organize your
60 ;; diary summary buffers from the closest event to the farthest one.
62 ;; - Automatic generation of diary group parameters:
63 ;; When you create a new diary group, or visit one, Gnus-Diary checks your
64 ;; group parameters, and if needed, sets the summary line format to the
65 ;; diary-specific value, adds the diary-specific sorting functions, and
66 ;; also adds the different `X-Diary-*' headers to the group's
67 ;; posting-style. It is then easier to send a diary message, because if
68 ;; you use `C-u a' or `C-u m' on a diary group to prepare a message, these
69 ;; headers will be inserted automatically (but not filled with proper
70 ;; values yet).
72 ;; - An interactive mail-to-diary convertion function:
73 ;; The function `gnus-diary-check-message' ensures that the current message
74 ;; contains all the required diary headers, and prompts you for values /
75 ;; correction if needed. This function is hooked in the nndiary backend so
76 ;; that moving an article to an nndiary group will trigger it
77 ;; automatically. It is also bound to `C-c D c' in message-mode and
78 ;; article-edit-mode in order to ease the process of converting a usual
79 ;; mail to a diary one. This function takes a prefix argument which will
80 ;; force prompting of all diary headers, regardless of their
81 ;; presence/validity. That way, you can very easily reschedule a diary
82 ;; message for instance.
85 ;; Usage:
86 ;; =====
88 ;; 0/ Don't use any `gnus-user-format-function-[d|D]'. Gnus-Diary provides
89 ;; both of these (sorry if you used them before).
90 ;; 1/ Add '(require 'gnus-diary) to your gnusrc file.
91 ;; 2/ Customize your gnus-diary options to suit your needs.
95 ;; Bugs / Todo:
96 ;; ===========
99 ;;; Code:
106 "Utilities on top of the nndiary backend for Gnus."
111 "*Summary line format for nndiary groups."
117 "*Time format to display appointements in nndiary summary buffers.
118 Please refer to `format-time-string' for information on possible values."
123 "*Function called to format a diary delay string.
124 It is passed two arguments. The first one is non-nil if the delay is in
125 the past. The second one is of the form ((NUM . UNIT) ...) where NUM is
126 an integer and UNIT is one of 'year 'month 'week 'day 'hour or 'minute.
130 There are currently two built-in format functions:
131 `gnus-diary-delay-format-english' (the default)
132 `gnus-diary-delay-format-french'"
142 ;; Compatibility functions ==================================================
153 ;; Summary line format ======================================================
157 "maintenant!"
158 ;; Keep only a precision of two degrees
162 del)
182 str))))
187 "now!"
188 ;; Keep only a precision of two degrees
192 del)
199 str)
204 ;; Same as `nndiary-schedule', but given a set of headers HEADERS
208 headers))))
211 nndiary-headers))
213 ;; #### NOTE: Gnus sometimes gives me a HEADER not corresponding to any
214 ;; message, with all fields set to nil here. I don't know what it is for, and
215 ;; I just ignore it.
216 ;;;###autoload
218 ;; Returns an aproximative delay string for the next occurence of this
219 ;; message. The delay is given only in the first non zero unit.
220 ;; Code partly stolen from article-make-date-line
227 "?????"
230 delay)
233 ;; This is a bit convoluted, but basically we go through the time
234 ;; units for years, weeks, etc, and divide things to see whether
235 ;; that results in positive answers.
242 unit num)
248 ))
250 ;; #### NOTE: Gnus sometimes gives me a HEADER not corresponding to any
251 ;; message, with all fields set to nil here. I don't know what it is for, and
252 ;; I just ignore it.
253 ;;;###autoload
255 ;; Returns a formatted time string for the next occurence of this message.
262 ;; Article sorting functions ================================================
282 "Sort nndiary summary buffers by schedule of appointements.
283 Optional prefix (or REVERSE argument) means sort in reverse order."
293 gnus-summary-sort-by-schedule
295 gnus-newsgroup-name))
301 ;; Group parameters autosetting =============================================
304 ;; Ensure that nndiary groups have convenient group parameters:
305 ;; - a posting style containing X-Diary headers
306 ;; - a nice summary line format
307 ;; - NNDiary specific sorting by schedule functions
308 ;; In general, try not to mess with what the user might have modified.
310 ;; Posting style:
316 ))
317 nndiary-headers)
319 ;; Summary line format:
323 ;; Sorting by schedule:
334 ))
336 ;; Called when a group is subscribed. This is needed because groups created
337 ;; because of mail splitting are *not* created with the backend function.
338 ;; Thus, `nndiary-request-create-group-hooks' is inoperative.
345 ;; Now that we have `gnus-subscribe-newsgroup-hooks', this is not needed
346 ;; anymore. Maybe I should remove this completely.
353 ;; Diary Message Checking ===================================================
356 ;; History variable for header value prompting
357 )
360 "Narrow the current buffer to the header part.
361 Point is left at the beginning of the region.
362 The buffer is assumed to contain a message, but the format is unknown."
370 ))
373 "Add a header to the current buffer.
374 The buffer is assumed to contain a message, but the format is unknown."
384 ))
387 "Ensure that the current message is a valid for NNDiary.
388 This function checks that all NNDiary required headers are present and
389 valid, and prompts for values / correction otherwise.
391 If ARG (or prefix) is non-nil, force prompting for all fields."
398 value invalid)
399 ;; First, try to find the header, and checks for validity:
413 ;; #### NOTE: this (along with the `gnus-diary-add-header'
414 ;; function) could be rewritten in a better way, in particular
415 ;; not to blindly remove an already present header and reinsert
416 ;; it somewhere else afterwards.
419 ))
420 ;; Now, loop until a valid value is provided:
429 nil t value
430 gnus-diary-header-value-history)
432 gnus-diary-header-value-history))))
441 ))
442 nndiary-headers)
443 ))
452 ;; The end ==================================================================
455 "Current Diary backend version."
465 ;;; arch-tag: 98467e70-337e-4ddc-b92d-45d403ff1b4b
466 ;;; gnus-diary.el ends here