Docs: Improve documentation for BBDB anniversaries

doc/ChangeLog

@@ -1,3 +1,7 @@
+2009-02-27  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (Weekly/daily agenda): New section.
+
 2009-02-22  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Orgstruct mode): Describe `orgstruct++-mode'.

doc/org.texi

@@ -6051,6 +6051,44 @@ will be made in the agenda:
 %%(diary-anniversary  2 10 1869) Mahatma Gandhi would be %d years old
 @end example
 
+@subsubheading Anniversaries from BBDB
+@cindex BBDB, anniversaries
+@cindex anniversaries, from BBDB
+
+If you are using the Big Brothers Database to store your contacts, you will
+very likely prefer to store anniversaries in BBDB rather than in a
+separate Org or diary file.  Org supports this and will show BBDB
+anniversaries as part of the agenda.  All you need to do is to add the
+following to one your your agenda files:
+
+@example
+* Anniversaries
+  :PROPERTIES:
+  :CATEGORY: Anniv
+  :END
+%%(org-bbdb-anniversaries)
+@end example
+
+You can then go ahead and define anniversaries for a BBDB record.  Basically,
+you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
+record and then add the date in the format @code{YYYY-MM-DD}, followed by a
+space and the class of the anniversary (@samp{birthday} or @samp{wedding}, or
+a format string).  If you omit the class, it will default to @samp{birthday}.
+Here are a few examples, the header for the file @file{org-bbdb.el} contains more detailed
+information.
+
+@example
+1973-06-22
+1955-08-02 wedding
+2008-04-14 %s released version 6.01 of Org-mode, %d years ago
+@end example
+
+After a change to BBDB, or for the first agenda display during an Emacs
+session, the agenda display will suffer a short delay as Org updates its hash
+with anniversaries.  However, after that things will be very fast - much
+faster in fact than a long list of @samp{%%(diary-anniversary)} entries in an
+Org or Diary file.
+
 @subsubheading Appointment reminders
 @cindex @file{appt.el}
 @cindex appointment reminders

lisp/ChangeLog

@@ -1,3 +1,7 @@
+2009-02-27  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org-bbdb.el: Improve documentation.
+
 2009-02-26  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org-list.el (org-insert-item): Only consider insert empty lines

lisp/org-bbdb.el

@@ -49,25 +49,37 @@
 ;; %%(org-bbdb-anniversaries)
 ;;
 ;;
-;; The anniversaries are stored in BBDB in the field `anniversary'
-;; in the format
+;; To add an anniversary to a BBDB record, press `C-o' in the record.
+;; You will be prompted for the field name, in this case it must be
+;; "anniversary".  If this is the first time you are using this field,
+;; you need to confirm that it should be created.
 ;;
-;;     YYYY-MM-DD{ CLASS-OR-FORMAT-STRING}*
-;;     {\nYYYY-MM-DD CLASS-OR-FORMAT-STRING}*
+;; The format of an anniversary field stored in BBDB is the following
+;; (items in {} are optional):
+;;
+;;     YYYY-MM-DD{ CLASS-OR-FORMAT-STRING}
+;;     {\nYYYY-MM-DD CLASS-OR-FORMAT-STRING}...
 ;;
 ;; CLASS-OR-FORMAT-STRING is one of two things:
 ;;
-;;  * an identifier for a class of anniversaries (eg. birthday or
-;;    wedding) from `org-bbdb-anniversary-format-alist'.
-;;  * the (format) string displayed in the diary.
+;;  - an identifier for a class of anniversaries (eg. birthday or
+;;    wedding) from `org-bbdb-anniversary-format-alist' which then
+;;    defines the format tring for this class
+;;  - the (format) string displayed in the diary.
+;;
+;; You can enter multiple anniversaries for a single BBDB record by
+;; separating them with a newline character.  At the BBDB prompt for
+;; the field value, type `C-q C-j' to enter a newline between two
+;; anniversaries.
 ;;
-;; It defaults to the value of `org-bbdb-default-anniversary-format'
-;; ("birthday" by default).
+;; If you omit the CLASS-OR-FORMAT-STRING entirely, it defaults to the
+;; value of `org-bbdb-default-anniversary-format' ("birthday" by
+;; default).
 ;;
 ;; The substitutions in the format string are (in order):
-;;  * the name of the record containing this anniversary
-;;  * the number of years
-;;  * an ordinal suffix (st, nd, rd, th) for the year
+;;  - the name of the record containing this anniversary
+;;  - the number of years
+;;  - an ordinal suffix (st, nd, rd, th) for the year
 ;;
 ;; See the documentation of `org-bbdb-anniversary-format-alist' for
 ;; further options.