[elpa] externals/gnorb 30afb67 068/449: Various docstring and comment edits.

[Stefan Monnier]

branch: externals/gnorb
commit 30afb67dc4af9bc48acc4544cf38990ed2e9002c
Author: Eric Abrahamsen <eric@ericabrahamsen.net>
Commit: Eric Abrahamsen <eric@ericabrahamsen.net>

    Various docstring and comment edits.
    
    Hopefully nothing important.
---
 README.org          |  3 +++
 lisp/gnorb-gnus.el  | 51 ++++++++++++++++++++++++---------------------------
 lisp/gnorb-org.el   | 10 ++++++++--
 lisp/gnorb-utils.el |  4 +++-
 4 files changed, 38 insertions(+), 30 deletions(-)

diff --git a/README.org b/README.org
index 3c270ab..2d17d55 100644
--- a/README.org
+++ b/README.org
@@ -191,3 +191,6 @@ summary or article buffer.
   received (or recently viewed) mails from the contact.
 - Consider merging `gnorb-org-handle-mail' and
   `gnorb-org-email-subtree' altogether.
+- Come up with some sort of way to have gnus posting styles attached
+  to BBDB records. Should have the full complement of regexp
+  predicates based on name, organization, xfields, etc.
diff --git a/lisp/gnorb-gnus.el b/lisp/gnorb-gnus.el
index 371c8c9..ba9db4b 100644
--- a/lisp/gnorb-gnus.el
+++ b/lisp/gnorb-gnus.el
@@ -58,7 +58,8 @@ search."
   :type 'list)
 
 (defcustom gnorb-gnus-mail-search-backend nil
-  "Mail search backend currently in use."
+  "Mail search backend currently in use. One of the three symbols
+notmuch, namazu, or mairix."
   :group 'gnorb-gnus
   :type 'symbol)
 
@@ -67,7 +68,10 @@ search."
   a Gnus message, even if the template being used hasn't
   specified the :gnus-attachments key.
 
-Basically behave as if all attachments have \":gnus-attachments t\".")
+Basically behave as if all attachments have \":gnus-attachments t\"."
+  :group 'gnorb-gnus
+  :type 'boolean)
+
 
 ;;; What follows is a very careful copy-pasta of bits and pieces from
 ;;; mm-decode.el and gnus-art.el. Voodoo was involved.
@@ -170,14 +174,14 @@ save them into `gnorb-tmp-dir'."
 
 ;; Possible workflow: multiple Org headers can be saved into a single
 ;; received Gnus message (but editing received messages is a pain in
-;; the butt, and often doesn't work). That can be done either by
-;; capturing from the message (ie creating a new Org heading), or by
-;; using the (as-yet unwritten) `gnorb-gnus-add-org-heading' (ie
-;; adding the ID of an existing Org heading). If that message is
-;; replied to from within Gnus (you didn't use
-;; `gnorb-org-handle-mail'), then all Org ID headers are carried over
-;; into the reply, and then when the message is sent, all the relevant
-;; IDs are prompted for TODO state-change. If you use
+;; the butt, and often doesn't work as expecte -- IMAP just makes new
+;; messages). That can be done either by capturing from the message
+;; (ie creating a new Org heading), or by using the (as-yet unwritten)
+;; `gnorb-gnus-add-org-heading' (ie adding the ID of an existing Org
+;; heading). If that message is replied to from within Gnus (you
+;; didn't use `gnorb-org-handle-mail'), then all Org ID headers are
+;; carried over into the reply, and then when the message is sent, all
+;; the relevant IDs are prompted for TODO state-change. If you use
 ;; `gnorb-org-handle-mail' to reply to a message, then only the
 ;; heading you "depart" from gets prompted -- any other headings are
 ;; left alone.
@@ -188,22 +192,16 @@ save them into `gnorb-tmp-dir'."
 ;; Also, when a message is sent, we should automatically push a link
 ;; to the sent message onto the link stack. That way, when we're
 ;; returned to the TODO and prompted for state change, a link to our
-;; message can be inserted into the state-change log.
+;; message can be inserted into the state-change log. Of course, that
+;; only works if you're using archiving, and there's a Fcc header
+;; present.
 
 ;; The model we're looking for is a single heading representing an
 ;; email conversation, bouncing back and forth between REPLY and WAIT
-;; (for instance) sates, with each state-change logged, and a link to
+;; (for instance) states, with each state-change logged, and a link to
 ;; the relevant message inserted into each log line. This might not
 ;; even require editing received messages at all.
 
-;; (defun gnorb-gnus-insert-org-header ()
-;;   (let ((id (org-id-get-create)))
-;;     (with-current-buffer
-;;     (org-capture-get :original-buffer)
-;;       (when (memq major-mode '(gnus-summary-mode gnus-article-mode)))
-;;       (gnus-with-article-buffer
-;;     ))))
-
 (defun gnorb-gnus-capture-abort-cleanup ()
   (when (and org-note-abort
             (org-capture-get :gnus-attachments))
@@ -255,13 +253,12 @@ current message; multiple header values returned as a 
string."
   "Call this function from a received gnus message to store a
 link to the message, prompt for a related Org heading, visit the
 heading, and either add a note or trigger a TODO state change.
-Set `gnorb-gnus-message-trigger-default' to either 'note or
-'todo; you can get the non-default behavior by calling this
-function with a prefix argument."
-  ;; this whole function isn't even going to be that awesome until we
-  ;; teach it how to guess the relevant org heading using message-ids
-  ;; from the References or In-Reply-To headers of the incoming
-  ;; message.
+Set `gnorb-trigger-todo-default' to 'note or 'todo (you can
+get the non-default behavior by calling this function with a
+prefix argument), or to 'prompt to always be prompted."
+  ;; this whole function isn't going to be that awesome until we teach
+  ;; it how to guess the relevant org heading using message-ids from
+  ;; the References or In-Reply-To headers of the incoming message.
   (interactive "P")
   (if (not (memq major-mode '(gnus-summary-mode gnus-article-mode)))
       (error "Only works in gnus summary or article mode")
diff --git a/lisp/gnorb-org.el b/lisp/gnorb-org.el
index d8288ce..4ff40d5 100644
--- a/lisp/gnorb-org.el
+++ b/lisp/gnorb-org.el
@@ -45,6 +45,7 @@ point.
 There's really no reason to use this instead of regular old
 `org-insert-link' with BBDB completion. But there might be in the
 future!"
+  ;; this needs to handle an active region.
   (interactive (list (gnorb-prompt-for-bbdb-record)))
   (let* ((name (bbdb-record-name rec))
         (link (concat "bbdb:" (org-link-escape name))))
@@ -59,6 +60,10 @@ future!"
   after the mail is sent.")
 
 (defun gnorb-org-restore-after-send ()
+  "After an email is sent, clean up the gnus summary buffer, put
+us back where we came from, and go through all the org ids that
+might have been in the outgoing message's headers and call
+`gnorb-org-do-restore-action' on each one."
   (when (eq major-mode 'gnus-summary-mode)
     (gnus-summary-exit nil t))
   (when (window-configuration-p gnorb-org-window-conf)
@@ -213,7 +218,7 @@ current heading."
           (pos (marker-position marker)))
       (switch-to-buffer buffer)
       (widen)
-      (goto-char pos)))
+      (goto-char pos))) 
   (unless (org-back-to-heading t)
     (error "Not in an org item"))
   (let ((mail-stuff (gnorb-org-extract-mail-stuff))
@@ -240,7 +245,8 @@ async, subtreep, visible-only, and body-only."
   "A list of ts and nils corresponding to Org's export options,
 to be used when exporting to a file. The options, in order, are
 async, subtreep, visible-only, and body-only."
-  :group 'gnorb-org)
+  :group 'gnorb-org
+  :type 'list)
 
 (defcustom gnorb-org-export-extensions
   '((latex ".tex")
diff --git a/lisp/gnorb-utils.el b/lisp/gnorb-utils.el
index 8ed9ad9..50f9b26 100644
--- a/lisp/gnorb-utils.el
+++ b/lisp/gnorb-utils.el
@@ -50,7 +50,9 @@
                     (length recs))
             (mapcar 'bbdb-record-name recs)))
       (setq recs (bbdb-search recs name name name nil nil)))
-    (car recs)))
+    (if recs
+       (car recs)
+      (error "No matching records"))))
 
 (defvar gnorb-tmp-dir (make-temp-file "emacs-gnorb" t)
   "Temporary directory where attachments etc are saved.")