From a087d8b4125c731ba8f139fb9d0ae678e5f8a77e Mon Sep 17 00:00:00 2001 From: Didier Verna Date: Wed, 20 Jul 2005 13:42:29 +0000 Subject: [PATCH] nndiary documentation (at last !) --- lisp/ChangeLog | 8 + lisp/gnus-diary.el | 71 +------- lisp/nndiary.el | 187 ++++----------------- texi/ChangeLog | 21 ++- texi/gnus.texi | 398 ++++++++++++++++++++++++++++++++++++++++++++- 5 files changed, 460 insertions(+), 225 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 8aef6f7db..4765f3edc 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,11 @@ +2005-07-20 Didier Verna + + * gnus-diary.el: Remove the description comment (nndiary is now + properly documented in the Gnus manual). + Fix the spelling of "Back End". + * nndiary.el: Ditto. + Fix the copyright notice. + 2005-07-18 Romain Francoise * gnus-sum.el (gnus-summary-to-prefix, diff --git a/lisp/gnus-diary.el b/lisp/gnus-diary.el index 6af72cb25..ae752a4ee 100644 --- a/lisp/gnus-diary.el +++ b/lisp/gnus-diary.el @@ -1,6 +1,6 @@ -;;; gnus-diary.el --- Wrapper around the NNDiary Gnus backend +;;; gnus-diary.el --- Wrapper around the NNDiary Gnus back end -;; Copyright (c) 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. +;; Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. ;; Copyright (C) 1999, 2000, 2001 Didier Verna. ;; Author: Didier Verna @@ -33,63 +33,8 @@ ;; Description: ;; =========== -;; Gnus-Diary is a wrapper around the NNDiary Gnus backend. It is here to -;; make your nndiary-user life easier in different ways. So, you don't have -;; to use it if you don't want to. But, really, you should. - -;; Gnus-Diary offers the following features on top of the NNDiary backend: - -;; - A nice summary line format: -;; Displaying diary messages in standard summary line format (usually -;; something like ": ") 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 offers you a nice summary line format -;; which will do this. By default, a summary line will appear like this: -;; -;; : -;; -;; for example, here's how Joe's birthday is displayed in my -;; "nndiary:birhdays" summary buffer (the message is expirable, but will -;; never be deleted, as it specifies a regular event): -;; -;; E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week) - -;; - More article sorting functions: -;; Gnus-Diary adds a new sorting function called -;; `gnus-summary-sort-by-schedule'. This function lets you organize your -;; diary summary buffers from the closest event to the farthest one. - -;; - Automatic generation of diary group parameters: -;; When you create a new diary group, or visit one, Gnus-Diary checks your -;; group parameters, and if needed, sets the summary line format to the -;; diary-specific value, adds 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 (but not filled with proper -;; values yet). - -;; - An interactive mail-to-diary convertion function: -;; The function `gnus-diary-check-message' ensures that the current message -;; contains all the required diary headers, and prompts you for values / -;; correction if needed. This function is hooked in the nndiary backend so -;; that moving an article to an nndiary group will trigger it -;; automatically. It is also bound to `C-c D c' 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/validity. That way, you can very easily reschedule a diary -;; message for instance. - - -;; Usage: -;; ===== - -;; 0/ Don't use any `gnus-user-format-function-[d|D]'. Gnus-Diary provides -;; both of these (sorry if you used them before). -;; 1/ Add '(require 'gnus-diary) to your gnusrc file. -;; 2/ Customize your gnus-diary options to suit your needs. - +;; gnus-diary is a utility toolkit used on top of the nndiary back end. It is +;; now fully documented in the Gnus manual. ;; Bugs / Todo: @@ -103,7 +48,7 @@ (require 'gnus-art) (defgroup gnus-diary nil - "Utilities on top of the nndiary backend for Gnus." + "Utilities on top of the nndiary back end for Gnus." :version "22.1" :group 'gnus) @@ -136,7 +81,7 @@ There are currently two built-in format functions: :group 'gnus-diary) (defconst gnus-diary-version nndiary-version - "Current Diary backend version.") + "Current Diary back end version.") ;; Compatibility functions ================================================== @@ -332,7 +277,7 @@ Optional prefix (or REVERSE argument) means sort in reverse order." )) ;; Called when a group is subscribed. This is needed because groups created -;; because of mail splitting are *not* created with the backend function. +;; because of mail splitting are *not* created with the back end function. ;; Thus, `nndiary-request-create-group-hooks' is inoperative. (defun gnus-diary-maybe-update-group-parameters (group) (when (eq (car (gnus-find-method-for-group group)) 'nndiary) @@ -450,7 +395,7 @@ If ARG (or prefix) is non-nil, force prompting for all fields." ;; The end ================================================================== (defun gnus-diary-version () - "Current Diary backend version." + "Current Diary back end version." (interactive) (message "NNDiary version %s" nndiary-version)) diff --git a/lisp/nndiary.el b/lisp/nndiary.el index 6852bf4d0..953822ed2 100644 --- a/lisp/nndiary.el +++ b/lisp/nndiary.el @@ -1,7 +1,7 @@ -;;; nndiary.el --- A diary backend for Gnus +;;; nndiary.el --- A diary back end for Gnus -;; Copyright (C) 1999, 2000, 2001, 2003 -;; Free Software Foundation, Inc. +;; Copyright (C) 2001, 2003 Free Software Foundation, Inc. +;; Copyright (C) 1999, 2000, 2001 Didier Verna. ;; Author: Didier Verna ;; Maintainer: Didier Verna @@ -33,127 +33,8 @@ ;; Description: ;; =========== -;; This package implements NNDiary, a diary backend for Gnus. NNDiary is a -;; mail backend, pretty similar to nnml in its functionnning (it has all the -;; features of nnml, actually), but in which messages are treated 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. -;; - Send a (special) diary message to yourself (see below). -;; - 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, just like if it were -;; new and unread. -;; - Read your "new" messages, this one included, and start dreaming 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. - -;; Some more notes on the diary backend: -;; - NNDiary is a *real* mail backend. You *really* send real diary -;; messsages. This means for instance that you can give appointements 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 -;; `C-u a' instead of `C-u m' on a diary group and the message won't actually -;; be sent; just stored in the group. -;; - The events you want to remember need not be punctual. You can set up -;; reminders for regular dates (like once each week, each monday at 13:30 -;; and so on). Diary messages of this kind will never be deleted (unless -;; you do it explicitely). But that, you guessed. - - -;; Usage: -;; ===== - -;; 1/ NNDiary has two modes of operation: traditional (the default) and -;; autonomous. -;; a/ In traditional mode, NNDiary does not get new mail by itself. You -;; have to move mails from your primary mail backend to nndiary -;; groups. -;; b/ In autonomous mode, NNDiary retrieves its own mail and handles it -;; independantly of your primary mail backend. To use NNDiary in -;; autonomous mode, you have several things to do: -;; i/ Put (setq nndiary-get-new-mail t) in your gnusrc file. -;; ii/ Diary messages contain several `X-Diary-*' special headers. -;; You *must* arrange that these messages be split in a private -;; folder *before* Gnus treat them. You need this because Gnus -;; is not able yet to manage multiple backends for mail -;; retrieval. Getting them from a separate source will -;; compensate this misfeature to some extent, as we will see. -;; 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 -;; iii/ Customize the variables `nndiary-mail-sources' and -;; `nndiary-split-methods'. These are replacements for the usual -;; mail sources and split methods which, and will be used in -;; autonomous mode. `nndiary-mail-sources' defaults to -;; '(file :path "~/.nndiary"). -;; 2/ Install nndiary somewhere Emacs / Gnus can find it. Normally, you -;; *don't* have to '(require 'nndiary) anywhere. Gnus will do so when -;; appropriate as long as nndiary is somewhere in the load path. -;; 3/ Now, customize the rest of nndiary. In particular, you should -;; customize `nndiary-reminders', 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). -;; 4/ You *must* use the group timestamp feature of Gnus. This adds a -;; timestamp to each groups' parameters (please refer to the Gnus -;; documentation ("Group Timestamp" info node) to see how it's done. -;; 5/ Once you have done this, you may add a permanent nndiary virtual server -;; (something like '(nndiary "")) to your `gnus-secondary-select-methods'. -;; Yes, this server will be able to retrieve mails and split them when you -;; type `g' in the group buffer, just as if it were your only mail backend. -;; This is the benefit of using a private folder. -;; 6/ Hopefully, almost everything (see the TODO section below) will work as -;; expected when you restart Gnus: in the group buffer, `g' and `M-g' will -;; also get your new diary mails, `F' will find your new diary groups etc. - - -;; How to send diary messages: -;; ========================== - -;; There are 7 special headers in diary messages. These headers are of the -;; form `X-Diary-', the 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 but 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 = 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 have only one value (you -;; bet ;-). -;; A star doesn't mean "all possible values" (because it has no sense), but -;; "the current local time zone". - -;; As an example, here's how you would say "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 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: * -;; -;; -;; Sending a diary message is not different from sending any other kind of -;; mail, except that such messages are identified by the presence of these -;; special headers. - +;; nndiary is a mail back end designed to handle mails as diary event +;; reminders. It is now fully documented in the Gnus manual. ;; Bugs / Todo: @@ -161,43 +42,43 @@ ;; * Respooling doesn't work because contrary to the request-scan function, ;; Gnus won't allow me to override the split methods when calling the -;; respooling backend functions. +;; respooling back end functions. ;; * There's a bug in the time zone mechanism with variable TZ locations. ;; * We could allow a keyword like `ask' in X-Diary-* headers, that would mean ;; "ask for value upon reception of the message". ;; * We could add an optional header X-Diary-Reminders to specify a special ;; reminders value for this message. Suggested by Jody Klymak. ;; * We should check messages validity in other circumstances than just -;; moving an article from sonwhere else (request-accept). For instance, when -;; editing / saving and so on. +;; moving an article from somewhere else (request-accept). For instance, +;; when editing / saving and so on. ;; Remarks: ;; ======= -;; * nnoo. -;; NNDiary is very similar to nnml. This makes the idea of using nnoo (to -;; derive nndiary from nnml) natural. However, my experience with nnoo is -;; that for reasonably complex backends like this one, noo is a burden -;; rather than an help. It's tricky to use, not everything can be -;; inherited, what can be inherited and when is not very clear, and you've -;; got to be very careful because a little mistake can fuck up your your -;; other backends, especially because their variables will be use instead of -;; your real ones. Finally, I found it easier to just clone the needed -;; parts of nnml, and tracking nnml updates is not a big deal. +;; * nnoo. NNDiary is very similar to nnml. This makes the idea of using nnoo +;; (to derive nndiary from nnml) natural. However, my experience with nnoo +;; is that for reasonably complex back ends like this one, noo is a burden +;; rather than an help. It's tricky to use, not everything can be inherited, +;; what can be inherited and when is not very clear, and you've got to be +;; very careful because a little mistake can fuck up your other back ends, +;; especially because their variables will be use instead of your real ones. +;; Finally, I found it easier to just clone the needed parts of nnml, and +;; tracking nnml updates is not a big deal. ;; IMHO, nnoo is actually badly designed. A much simpler, and yet more ;; powerful one would be to make *real* functions and variables for a new -;; backend based on another. Lisp is a reflexive language so that's a very +;; back end based on another. Lisp is a reflexive language so that's a very ;; easy thing to do: inspect the function's form, replace occurences of ;; (even in strings) with , and you're done. ;; * nndiary-get-new-mail, nndiary-mail-source and nndiary-split-methods: ;; NNDiary has some experimental parts, in the sense Gnus normally uses only -;; one mail backends for mail retreival and splitting. This backend is also -;; an attempt to make it behave differently. For Gnus developpers: as you -;; can see if you snarf into the code, that was not a very difficult thing -;; to do. Something should be done about the respooling breakage though. +;; one mail back ends for mail retreival and splitting. This back end is +;; also an attempt to make it behave differently. For Gnus developpers: as +;; you can see if you snarf into the code, that was not a very difficult +;; thing to do. Something should be done about the respooling breakage +;; though. ;;; Code: @@ -220,10 +101,10 @@ (apply #'error args)))) -;; Backend behavior customization =========================================== +;; Back End behavior customization =========================================== (defgroup nndiary nil - "The Gnus Diary backend." + "The Gnus Diary back end." :version "22.1" :group 'gnus-diary) @@ -326,27 +207,27 @@ The hooks will be called with the article in the current buffer." :type 'boolean) -;; Backend declaration ====================================================== +;; Back End declaration ====================================================== ;; Well, most of this is nnml clonage. (nnoo-declare nndiary) (defvoo nndiary-directory (nnheader-concat gnus-directory "diary/") - "Spool directory for the nndiary backend.") + "Spool directory for the nndiary back end.") (defvoo nndiary-active-file (expand-file-name "active" nndiary-directory) - "Active file for the nndiary backend.") + "Active file for the nndiary back end.") (defvoo nndiary-newsgroups-file (expand-file-name "newsgroups" nndiary-directory) - "Newsgroups description file for the nndiary backend.") + "Newsgroups description file for the nndiary back end.") (defvoo nndiary-get-new-mail nil "Whether nndiary gets new mail and split it. -Contrary to traditional mail backends, this variable can be set to t -even if your primary mail backend also retreives mail. In such a case, +Contrary to traditional mail back ends, this variable can be set to t +even if your primary mail back end also retreives mail. In such a case, NDiary uses its own mail-sources and split-methods.") (defvoo nndiary-nov-is-evil nil @@ -367,10 +248,10 @@ all. This may very well take some time.") (defconst nndiary-version "0.2-b14" - "Current Diary backend version.") + "Current Diary back end version.") (defun nndiary-version () - "Current Diary backend version." + "Current Diary back end version." (interactive) (message "NNDiary version %s" nndiary-version)) @@ -631,7 +512,7 @@ all. This may very well take some time.") (deffoo nndiary-request-scan (&optional group server) ;; Use our own mail sources and split methods while Gnus doesn't let us have - ;; multiple backends for retrieving mail. + ;; multiple back ends for retrieving mail. (let ((mail-sources nndiary-mail-sources) (nnmail-split-methods nndiary-split-methods)) (setq nndiary-article-file-alist nil) diff --git a/texi/ChangeLog b/texi/ChangeLog index df471a831..53cd506b5 100644 --- a/texi/ChangeLog +++ b/texi/ChangeLog @@ -1,3 +1,8 @@ +2005-07-20 Didier Verna + + * gnus.texi (Email Based Diary): New. Proper documentation for the + nndiary back end and the gnus-diary library. + 2005-07-18 Romain Francoise * gnus.texi (To From Newsgroups): Mention new variables @@ -183,7 +188,7 @@ 2004-12-08 Reiner Steib - * gnusref.tex: Mention `gnus-summary-limit-to-recipient' and + * gnusref.tex: Mention `gnus-summary-limit-to-recipient' and `gnus-summary-sort-by-recipient'. 2004-12-08 Reiner Steib @@ -205,7 +210,7 @@ 2004-12-06 Reiner Steib - * gnus-news.texi: Mention `gnus-summary-limit-to-recipient' and + * gnus-news.texi: Mention `gnus-summary-limit-to-recipient' and `gnus-summary-sort-by-recipient'. * gnus.texi (Filtering Spam Using The Spam ELisp Package): Index @@ -452,7 +457,7 @@ 2004-05-28 Reiner Steib * gnus-faq.texi: Untabify. - ([6.3]): nnir.el is in contrib directory. + ([6.3]): nnir.el is in contrib directory. * message.texi (News Headers): Clarify how a unique ID is created. @@ -461,7 +466,7 @@ 2004-05-19 Andre Srinivasan * gnus.texi (Group Parameters): Added more on hooks. (Small - change.) + change.) 2004-05-19 Reiner Steib @@ -608,7 +613,7 @@ characters that can not be encoded using iso-8859-1. (Gnus Unplugged): Reference gnus-agent variable. (Agent Variables): Added gnus-agent. - + 2004-02-17 Katsumi Yamaoka @@ -783,7 +788,7 @@ (Blacklists and Whitelists, BBDB Whitelists) (Gmane Spam Reporting, Bogofilter, spam-stat spam filtering) (SpamOracle): mention that spam/ham processor variables are being - obsoleted + obsoleted (Extending the Spam ELisp package): add some new documentation for adding a new backend to spam.el @@ -807,7 +812,7 @@ 2003-12-31 Steve Youngs * gnus.texi (XEmacs): Update list of Gnus XEmacs package - requirements. + requirements. 2003-12-30 Reiner Steib @@ -1101,7 +1106,7 @@ 2003-06-24 Lars Magne Ingebrigtsen * gnus.texi (Summary Mail Commands): Make note of - Mail-Followup-To. + Mail-Followup-To. 2003-06-23 Jesper Harder diff --git a/texi/gnus.texi b/texi/gnus.texi index 3123824b6..ab12b26cc 100644 --- a/texi/gnus.texi +++ b/texi/gnus.texi @@ -624,6 +624,7 @@ Select Methods * 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 @@ -722,6 +723,25 @@ Combined Groups * 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. @@ -12207,6 +12227,7 @@ The different methods all have their peculiarities, of course. * 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 @@ -17691,6 +17712,381 @@ Articles marked as read in the @code{nnkiboze} group will have 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-}, @code{} 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{gnusrc} 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 +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. +@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{gnusrc} 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 of 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 +appointements 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 @@ -23177,7 +23573,7 @@ Now just set your summary line format to use @code{%uS}. Here's an example that formats the spam score in a 5-character field: @lisp -(setq gnus-summary-line-format +(setq gnus-summary-line-format "%U%R %10&user-date; $%5uS %6k %B %(%4L: %*%-25,25a%) %s \n") @end lisp -- 2.25.1