[elpa] externals/gnorb e7b8a8b 233/449: First full draft of manual

[Stefan Monnier]

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

    First full draft of manual
    
    * NEWS: Note version one.
    * README.org: Move most of the information to the manual.
    * gnorb.org: Finish manual.
    * gnorb.texi: Exported .texi manual
---
 NEWS       |  14 +-
 README.org | 474 ++------------------------------------------
 gnorb.org  | 507 ++++++++++++++++++++++++++++++++++++++++++++++-
 gnorb.texi | 657 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 1187 insertions(+), 465 deletions(-)

diff --git a/NEWS b/NEWS
index 7a1367b..728f219 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,11 @@
+GNU Emacs Gnorb NEWS -- history of user-visible changes.  -*- org -*-
 
-Local variables:
-coding: utf-8
-mode: outline
-end:
+* Version 1 [2014-10-07 Tue]
+** First Elpa Version
+** Email Tracking
+The mechanism for email tracking has changed since Gnorb was made
+available on Elpa. See the manual for set-up instructions.
+** Directory Structure
+The directory structure has changed since Gnorb was made available on
+Elpa. There is no longer a lisp/ directory -- all *.el files are now
+at the top level.
diff --git a/README.org b/README.org
index 06dab1c..cbb13af 100644
--- a/README.org
+++ b/README.org
@@ -5,465 +5,27 @@ Glue code between the Gnus, Org, and BBDB packages for Emacs.
 This package connects Emacs-based email, project management, and
 contact management a little more closely together. The goal is to
 reduce friction when manipulating TODOs, contacts, messages, and
-files. An underlying principle is that one should stay in the Org
-Agenda as much as possible: Gnus should serve as input/output for the
-Agenda, and BBDB should serve as an alternate view on information.
-This isn't actually enforced, of course, it's just an ideal.
+files.
 
-Put "gnorb/lisp" in your load path, then either require "gnorb" to
-load everything, or pick bits and pieces: "gnorb-gnus", "gnorb-org",
-or "gnorb-bbdb".
+Probably the most interesting thing Gnorb does is tracking
+correspondences between Gnus email messages and Org headings. Rather
+than "turning your inbox into a TODO list", as some software puts it,
+Gnorb (kind of) does the opposite: turning your TODO headings into
+mini mailboxes.
 
-*Note for existing users*: Gnorb recently shifted to exclusively using
-the registry to track email TODOs, and this will require some
-configuration changes, please see 
[[id:5780bc9d-0756-4213-b805-2f9a2216fe15][Using Gnorb for Tracking Email 
TODOs]]
-below.
+*Note for previous users*: If you were using Gnorb from Github before
+it shifted to the Elpa repository, the email tracking mechanism has
+changed, please see the manual for details.
 
-Recommended keybindings/integration measures are shown below. Copy
-them into your init files and edit as you see fit.
+** Installation
 
-Code in this package is aimed at the development (git) versions of
-Gnus, Org, and BBDB (that means BBDB 3: upgrade, already!). I'll try
-to make it work with the most recent stable releases of those
-packages, but I'm not promising anything.
+It's easiest to install Gnorb from Elpa: run `list-packages' and look
+for it there.
 
-Most of the functions listed later in this README are fairly discrete:
-they do one thing only, and (I hope) don't require anything special in
-terms of file formats or workflow. A few exceptions to that are listed
-below.
-** Using Gnorb for Tracking Email TODOs
-:PROPERTIES:
-:ID:       5780bc9d-0756-4213-b805-2f9a2216fe15
-:END:
+Or clone the Git repo at https://github.com/girzel/gnorb, and add the
+top-level directory to your load path.
 
-Tracking correspondences between Org TODOs and email messages is one
-of the more complicated things that Gnorb does, and thus requires a
-little setup. Tracking relies on the Gnus registry, so that must be
-installed (ie you've called `gnus-registry-initialize' somewhere). It
-also relies on Org ids, so you'll want to require 'org-id, and set
-`org-id-track-globally' to t (that's the default anyway).
-
-Once that's done, call `gnorb-tracking-initialize' after loading
-Gnorb.
-
-In addition, Gnorb can provide the very useful service of opening nnir
-*Summary* buffers containing all the messages linked to from a given
-subtree, see [[id:89ec2ade-5686-402e-a23c-2af36325d1f3][Showing gnus messages 
from links in Org buffers]] below.
-
-NOTE: If you were using an earlier version of Gnorb that stored
-correspondences in Org properties, you can transition to the newer
-system with the function `gnorb-registry-transition-from-props'. See
-the docstring for details.
-
-*** Capture templates for emails
-Most people will be using plain capture templates to create TODOs from
-messages. When the TODO is made, Gnorb will record the connection
-between the message and the TODO, using the Gnus registry. Later, you
-can call `gnorb-org-handle-mail' on the TODO: Gnorb will find the
-associated message and start a reply to it.
-
-If you've made a TODO that doesn't have any messages associated with
-it yet (for instance, a TODO reminding you to email someone), then
-Gnorb will look for gnus:, mailto:, or bbdb: links in the subtree, and
-act on them accordingly.
-
-The option `gnorb-org-mail-scan-scope' determines how many paragraphs
-of the subtree will be scanned for links. 0 means only the heading
-text, a positive integer means the heading plus that many paragraphs
-of body text, and any other non-nil value means the whole subtree will
-be scanned.
-
-Your capture templates should therefore put links where
-`gnorb-org-handle-mail' can find them. Say your capture template looks
-like this:
-
-#+BEGIN_SRC emacs-lisp
-  '("r" "Work-related Reply" entry (file+headline "~/org/job.org" "Emails")
-    "** REPLY %:fromname\n%?Received on %:date-timestamp-inactive, link: %a"
-    :gnus-attachments t)
-
-#+END_SRC
-
-In this case, you'll want to set `gnorb-org-mail-scan-scope' to at
-least 1, to scan the first paragraph of body text.
-
-The same goes for "remind me to email so-and-so" TODOs. The mailto: or
-bbdb: link pointing at so-and-so should be located where
-`gnorb-org-handle-mail' can find it.
-
-In fact, you can use any Org TODO as a starting point for
-`gnorb-org-handle-mail'. Gnorb will do its best to find mail-related
-information from the subtree, but if it can't it will simply start
-composing a blank message. When the message is sent, it will be
-associated with the TODO.
-
-*** Tracking conversations
-You can use Gnorb to remind you to reply to a message, to track
-extended email conversations, or to manage complex email-centric
-projects.
-
-The principle is simple: Incoming and outgoing messages are all
-associated with an Org heading, or its sub-headings. Outgoing messages
-are created by calling `gnorb-org-handle-mail' on an Org TODO, which
-starts a reply or a new message, depending on the state of the TODO.
-Incoming messages are associated with TODOs by calling
-`gnorb-gnus-incoming-do-todo' on the message, and choosing the TODO.
-
-In both cases, you'll be asked to "trigger an action" on the TODO in
-question. Actions including changing TODO state (and associating the
-message with the TODO), taking a note (and associating the message),
-just associating the message, and doing nothing at all. We're also
-planning trigger actions that will capture new headings as children or
-siblings of the original TODO, but that's not done yet. You can also
-provide your own actions.
-
-In this way, a single TODO collects an entire conversation of emails.
-If you have subtrees as a part of the original TODO, each subtree has
-its own collection of emails, which are inherited by the parent. To
-view all these messages in a single Gnus *Summary* buffer, see 
[[id:89ec2ade-5686-402e-a23c-2af36325d1f3][Showing
-gnus messages from links in Org buffers]] below.
-*** Hinting in Gnus
-When you receive new mails that might be relevant to existing Org
-TODOs, Gnorb can alert you to that fact. When
-`gnorb-gnus-hint-relevant-article' is t (the default), Gnorb will
-display a message in the minibuffer when opening potentially relevant
-messages. You can then use `gnorb-gnus-incoming-to-todo' to trigger an
-action on the relevant TODO.
-
-This hinting can happen in the Gnus summary buffer as well. If you use
-the escape indicated by `gnorb-gnus-summary-mark-format-letter" as
-part of your `gnus-summary-line-format', articles that are relevant to
-TODOs will be marked with a special character in the Summary buffer,
-as determined by `gnorb-gnus-summary-mark'. By default, the format
-letter is "g" (meaning it is used as "%ug" in the format line), and
-the mark is "¡".
-** Showing gnus messages from links in Org buffers
-:PROPERTIES:
-:ID:       89ec2ade-5686-402e-a23c-2af36325d1f3
-:END:
-Sometimes you've got an Org subtree tracking many relevant Gnus
-messages, and you'd like to see all those message in a single Gnus
-summary buffer. Gnorb can do this, but you'll have to add a new
-backend to your list of Gnus servers. If that makes your skin crawl a
-little, it probably should. But no fear! The server essentially does
-nothing but provide a place for nnir to hang searches.
-
-Add an entry like this to your `gnus-secondary-select-methods':
-
-(nngnorb "Purely Decorative Server Name")
-
-And restart Gnus. Now, on any given Org subtree, you can call
-`gnorb-org-view', and you'll be presented with an nnir Summary buffer
-containing all the messages connected to the subtree. If you reply to
-any messages from this buffer, your reply will also be tracked as part
-of the subtree.
-
-As a bonus, it's possible to go into Gnus' *Server* buffer, find the
-line specifying your nngnorb server, and hit "G" (aka
-`gnus-group-make-nnir-group'). At the query prompt, enter an Org-style
-tags-todo Agenda query string (eg "+work-computer", or what have you).
-Gnorb will find all headings matching this query, scan their subtrees
-for gnus links, and then give you a Summary buffer containing all the
-linked messages. This is dog-slow at the moment; it will get faster.
-** Recent mails from BBDB contacts
-If you're using a recent git version of BBDB (circa mid-May 2014 or
-later), you can give your BBDB contacts a special field which will
-collect links to recent emails from that contact. The default name of
-the field is "messages", but you can customize that name using the
-`gnorb-bbdb-messages-field' option.
-
-Gnorb will not collect links by default: you need to call
-`gnorb-bbdb-open-link' on a contact once to start the process.
-Thereafter, opening mails from that contact will store a link to the
-message.
-
-Once some links are stored, `gnorb-bbdb-open-link' will open them: Use
-a prefix arg to the function call to select particular messages to
-open. There are several options controlling how all this works; see
-the gnorb-bbdb user options section below for details.
-** BBDB posting styles
-Gnorb comes with a BBDB posting-style system, inspired by (copied
-from) gnus-posting-styles. You can specify how messages are composed
-to specific contacts, by matching on contact field values (the same
-way gnus-posting-styles matches on group names). See the docstring of
-`gnorb-bbdb-posting-styles' for details.
-
-In order not to be too intrusive, Gnorb doesn't alter the behavior of
-`bbdb-mail', the usual mail-composition function. Instead it provides
-an alternate `gnorb-bbdb-mail', which does exactly the same thing, but
-first processes the new mail according to `gnorb-bbdb-posting-styles'.
-If you want to use this feature regularly, you can rebind "m" in
-`bbdb-mode-map' to `gnorb-bbdb-mail'.
-** Using attach with org capture
-Set the new :gnus-attachments key to "t" in a capture template that
-you use on mail messages, and you'll be queried to re-attach the
-message's attachments onto the newly-captured heading. Or set
-`gnorb-gnus-capture-always-attach' to "t" to have Gnorb do this for
-all capture templates.
-** Restoring window layout
-Many Gnorb functions alter the window layout and value of point. In
-most of these cases, you can restore the previous layout using the
-interactive function `gnorb-restore-layout'.
-** Gnorb-BBDB
-*** Interactive Functions
-**** gnorb-bbdb-tag-agenda
-Give BBDB records an org-tag field (customizable), then call this
-function on the current records(s) to open an Org agenda tags search
-using those tags. Only shows TODOs by default: use a prefix argument
-to show all tagged headings.
-**** gnorb-bbdb-mail-search
-Search for all mail messages from the record(s) displayed. Currently
-supports the notmuch, mairix, and namazu search backends; set
-`gnorb-gnus-mail-search-backend' to one of those symbol values.
-**** gnorb-bbdb-cite-contact
-Prompt for a BBDB record and insert a string of the type "Bob Smith
-<bob@smith.com>".
-**** gnorb-bbdb-mail
-Exactly like `bbdb-mail', except it runs the records through
-`gnorb-bbdb-posting-styles' first, and alters the composed message
-accordingly.
-**** gnorb-bbdb-open-link
-Open a message linked to from within a BBDB record's
-`gnorb-bbdb-messages-field'. Use prefix args to select the exact
-message. If a record is not yet collecting links, use this function to
-start the collection process.
-*** User Options
-**** gnorb-bbdb-org-tag-field
-The name of the BBDB xfield that holds Org-related tags. Specified as
-a string with the ":" separator between tags, same as for Org
-headings. Defaults to 'org-tag.
-**** gnorb-bbdb-messages-field
-The name of the BBDB xfield that holds links to recently-received
-messages from this contact. Defaults to 'messages.
-**** gnorb-bbdb-collect-N-messages
-Collect at most this many links to messages from this contact.
-Defaults to 5.
-**** gnorb-bbdb-define-recent
-What does "recently-received" mean? Possible values are 'seen and
-'received. When set to 'seen, the most recently-opened messages are
-collected. When set to 'received, the most recently-received (by Date
-header) messages are collected. Defaults to 'seen.
-**** gnorb-bbdb-message-link-format-multi
-How is a single message's link formatted in the multi-line BBDB layout
-format? Defaults to "%:count. %D: %:subject" (see the docstring for
-details).
-**** gnorb-bbdb-message-link-format-one
-How is a single message's link formatted in the one-line BBDB layout
-format? Defaults to nil (see the docstring for details).
-**** gnorb-bbdb-posting-styles
-Styles to use for influencing the format of mails composed to the BBDB
-record(s) under point (see the docstring for details).
-*** Suggested Keybindings
-#+BEGIN_SRC emacs-lisp
-  (eval-after-load "gnorb-bbdb"
-    '(progn
-       (define-key bbdb-mode-map (kbd "O") 'gnorb-bbdb-tag-agenda)
-       (define-key bbdb-mode-map (kbd "S") 'gnorb-bbdb-mail-search)
-       (define-key bbdb-mode-map (kbd "m") 'gnorb-bbdb-mail)
-       (define-key bbdb-mode-map (kbd "l") 'gnorb-bbdb-open-link)
-       (global-set-key (kbd "C-c C") 'gnorb-bbdb-cite-contact)))
-#+END_SRC
-** Gnorb-Org
-*** Functions
-**** gnorb-org-contact-link
-Prompt for a BBDB record and insert a link to that record at
-point.
-**** gnorb-org-handle-mail
-This function does its best to interpret the heading under point as an
-email action.
-
-If the heading text contains a link to a Gnus message then start a
-reply to that message, otherwise start composing a new message. If the
-heading contains mailto links or BBDB links, put those addresses in
-the "To" field of the new message (or reply). If the heading has
-org-attach'ed attachments, prompt to attach them to the outgoing
-message.
-
-When the message is sent, return to the original Org buffer. If the
-heading's TODO keyword is a member of `gnorb-org-mail-todos' (by
-default, "MAIL" and "REPLY"), then call `org-agenda-todo' and prompt
-to mark the TODO as done. Set that option to nil to prompt for all
-TODO keywords.
-
-This works best with a matching capture template: the template stores
-a link to the message under point within the headline text, and this
-command replies to that message in a DWIM style.
-
-**** gnorb-org-email-subtree
-Call on a Org subtree to export the subtree as either text or a file.
-Then compose a message with the text in the message body, or the file
-attached to the message. See the `gnorb-org-email-subtree-*' user
-options for influencing this process.
-
-There's a little overlap with org-mime, but this function allows for
-exporting the subtree as a file, and does not compose a MIME-multipart
-HTML message. I may look into integrating it a bit with org-mime
-later.
-
-This function also overlaps with `gnorb-org-handle-mail'. The only
-difference is that it will first prompt to export the subtree of the
-heading under point. After that, it behaves much like
-`gnorb-org-handle-mail'.
-
-Use `gnorb-org-handle-mail' when the primary purpose of the heading is
-as a TODO reminding you to send or reply to an email. Any text under
-the heading will be disregarded.
-
-Use `gnorb-org-email-subtree' when the primary purpose of the heading
-is the text (or tables or lists or...) of its subtree, and you just
-happen to want to email that content to someone.
-
-**** gnorb-org-popup-bbdb
-Pop up a BBDB buffer relevant to the current Org display. This works
-differently depending on whether you're in the Agenda, or in a regular
-Org file.
-
-In an Agenda buffer currently displaying an `org-tags-view' search (ie
-called with the "m" or "M" keys), it will look through your BBDB
-database and pop up a BBDB buffer displaying all records that match
-the current tags search.
-
-In a regular file, it will look at the heading under point for bbdb:
-links, and pop up a BBDB buffer showing those records.
-**** gnorb-org-view
-If you've got a 'nngnorb backend installed in your gnus select
-methods, you can use this function on a subtree to scan it for gnus
-links and open all linked messages in a nnir summary buffer.
-*** User Options
-**** gnorb-org-mail-scan-strategies
-This option provides various strategies for how the
-`gnorb-org-handle-mail' and `gnorb-org-email-subtree' functions act on
-links within the subtree at point. Three different options are
-provided, for flexibility -- see the docstring for details.
-**** gnorb-org-capture-collect-link-p
-When this is set to t, the capture process will always store a link to
-the Gnus message or BBDB record under point, even when the link isn't
-part of the capture template. It can then be added to the captured
-heading with org-insert-link, as usual.
-**** gnorb-org-agenda-popup-bbdb
-Set to t to automatically pop up the BBDB buffer displaying records
-corresponding to the Org Agenda tags search underway. If this is nil
-you can always do it manually with the command of the same name.
-**** gnorb-org-bbdb-popup-layout
-Controls the layout of the Agenda-related BBDB popup, takes the same
-values as bbdb-pop-up-layout.
-*** Suggested Keybindings
-#+BEGIN_SRC emacs-lisp
-  (eval-after-load "gnorb-org"
-    '(progn
-       (org-defkey org-mode-map (kbd "C-c C") 'gnorb-org-contact-link)
-       (org-defkey org-mode-map (kbd "C-c H") 'gnorb-org-handle-mail)
-       (org-defkey org-mode-map (kbd "C-c e") 'gnorb-org-view)
-       (org-defkey org-mode-map (kbd "C-c E") 'gnorb-org-email-subtree)
-       (org-defkey org-mode-map (kbd "C-c V") 'gnorb-org-popup-bbdb)
-       (setq gnorb-org-agenda-popup-bbdb t)
-       (eval-after-load "org-agenda"
-         '(progn (org-defkey org-agenda-mode-map (kbd "H") 
'gnorb-org-handle-mail)
-                 (org-defkey org-agenda-mode-map (kbd "V") 
'gnorb-org-popup-bbdb)))))
-#+END_SRC
-** Gnorb-Gnus
-*** Functions
-**** gnorb-gnus-article-org-attach
-When called on an email with attached files, prompt for an Org heading
-and attach the files to that heading using org-attach.
-**** gnorb-gnus-incoming-do-todo
-Call on an incoming message that should trigger a state change or a
-note on an existing TODO. You'll be asked to locate the appropriate
-TODO, and the action will depend in part on the value of
-`gnorb-gnus-message-trigger-default', which see. If the incoming
-message refers to messages that are already tracked in a conversation,
-Gnorb will prompt you with the relevant TODO.
-**** gnorb-gnus-outgoing-do-todo
-Call this while composing a new message (ie in message-mode), or
-immediately after sending a message. If the message is a new one (ie
-it's not part of an email conversation that's already being tracked) a
-new TODO will be made from it. This is handy when you need to make
-sure you get a response, for instance. New TODOs are created using the
-capture process, and you'll need to specify a capture template to use
-for outgoing messages: see `gnorb-gnus-new-todo-capture-key'.
-
-If you call this on a message that's part of an already-tracked
-conversation, you'll be prompted to change TODO state or leave a note
-on that conversation.
-*** User Options
-**** gnorb-gnus-mail-search-backend
-Specifies the search backend that you use for searching mails.
-Currently supports notmuch, mairix, and namazu: set this option to one
-of those symbols.
-**** gnorb-gnus-capture-always-attach
-Treat all capture templates as if they had the :gnus-attachments key
-set to "t". This only has any effect if you're capturing from a Gnus
-summary or article buffer.
-**** gnorb-trigger-todo-default
-Set to either 'note or 'todo to tell `gnorb-gnus-incoming-do-todo'
-what to do by default. You can reach the non-default behavior by
-calling that function with a prefix argument. Alternately, set to
-'prompt to always prompt for the appropriate action.
-**** gnorb-gnus-trigger-refile-targets
-If you use `gnorb-gnus-incoming-do-todo' on an incoming message, Gnorb
-will try to locate a TODO heading that's relevant to that message. If
-it can't, it will prompt you for one, using the refile interface. This
-option will be used as the value of `org-refile-targets' during that
-process: see the docstring of `org-refile-targets' for the appropriate
-syntax.
-**** gnorb-gnus-new-todo-capture-key
-Set this to a single-character string pointing at an Org capture
-template to use when creating TODOs from outgoing messages. The
-template is a regular capture template, with a few exceptions. If Gnus
-helps you archive outgoing messages (ie you have
-`gnus-message-archive-group' set to something, and your outgoing
-messages have a "Fcc" header), a link to that message will be made,
-and you'll be able to use all the escapes related to gnus messages. If
-you don't archive outgoing messages, you'll still be able to use the
-%:subject, %:to, %:toname, %:toaddress, and %:date escapes in the
-capture template.
-**** gnorb-gnus-hint-relevant-article
-Set to "t" (the default) to have Gnorb give you a hint in the
-minibuffer when opening messages that might be relevant to existing
-Org TODOs.
-**** gnorb-gnus-summary-mark-format-letter
-The formatting letter to use as part of your
-`gnus-summary-line-format', to indicate messages which might be
-relevant to Org TODOs. Defaults to "g", meaning it should be used as
-"%ug" in the format line.
-**** gnorb-gnus-summary-mark
-The mark used to indicate relevant messages in the Summary buffer,
-when `gnorb-gnus-summary-mark-format-letter' is present in the format
-line. Defaults to "¡".
-*** Suggested Keybindings
-#+BEGIN_SRC emacs-lisp
-  (eval-after-load "gnorb-gnus"
-    '(progn
-       (define-key gnus-summary-mime-map "a" 'gnorb-gnus-article-org-attach)
-       (define-key gnus-summary-mode-map (kbd "C-c t") 
'gnorb-gnus-incoming-do-todo)
-       (push '("attach to org heading" . gnorb-gnus-mime-org-attach)
-             gnus-mime-action-alist)
-       ;; The only way to add mime button command keys is by redefining
-       ;; gnus-mime-button-map, possibly not ideal. Ideal would be a
-       ;; setter function in gnus itself.
-       (push '(gnorb-gnus-mime-org-attach "a" "Attach to Org heading")
-             gnus-mime-button-commands)
-       (setq gnus-mime-button-map
-             (let ((map (make-sparse-keymap)))
-               (define-key map gnus-mouse-2 'gnus-article-push-button)
-               (define-key map gnus-down-mouse-3 'gnus-mime-button-menu)
-               (dolist (c gnus-mime-button-commands)
-                 (define-key map (cadr c) (car c)))
-               map))))
-
-  (eval-after-load "message"
-    '(progn
-       (define-key message-mode-map (kbd "C-c t") 
'gnorb-gnus-outgoing-do-todo)))
-#+END_SRC
-** Wishlist TODO
-- Support adding X-Org-Id headers to Gnus messages, which point at
-  relevant Org headings (possibly not really useful).
-- Provide a command that, when in the Org Agenda, does an email search
-  for messages received in the visible date span, or day under point,
-  etc. Make it work in the calendar, as well?
-- Look into message tagging in Gnus -- what are the options? Is it
-  possible to search for tagged messages when we do an Org agenda tag
-  search?
-- Allow automatic org-tagging of BBDB contacts: when messages from a
-  contact are associated with an Org heading, make it possible for the
-  contact to inherit that heading's tags.
+If you want to use Gnorb for tracking emails with TODOs, you'll need
+to add a nngnorb server to your `gnus-secondary-select-methods'
+variable, then call `gnorb-tracking-initialize' in your init files.
+Again, see the manual for details.
diff --git a/gnorb.org b/gnorb.org
index 7fab228..b03098b 100644
--- a/gnorb.org
+++ b/gnorb.org
@@ -1,2 +1,507 @@
+#+TEXINFO_CLASS: info
+#+TEXINFO_HEADER: @syncodeindex pg cp
+#+TITLE: Gnorb Manual
+#+SUBTITLE: for version 1, updated 3 October, 2014
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: Gnorb: (gnorb)
+#+TEXINFO_DIR_DESC: Glue code for Gnus, Org, and BBDB
+#+OPTIONS: *:nil num:t toc:nil
+* Introduction
 
-* Gnorb
+Gnorb provides glue code between the Gnus, Org, and BBDB packages.
+It's aimed at supporting email-based project management, and generally
+making it easier to keep track of email communication.
+
+Much of the code consists of single-use convenience functions, but
+tracking email conversations with Org requires is more complicated,
+and requires a bit of setup.
+
+Gnorb can be used in a modular fashion, by selectively loading the
+files "gnorb-org", "gnorb-gnus" or "gnorb-bbdb" instead of plain old
+"gnorb". The package as a whole is rather Org-centric, though, and it
+won't do much of interest without "gnorb-org".
+
+This means that Gnorb doesn't have hard requirements to any of the
+three base libraries. For the libraries you are using, however, you'll
+get best results from using the most recent stable version (yes, that
+means BBDB 3). Some of the features in Gnorb only work with
+development versions of these libraries (those cases are noted below).
+* Installation
+Gnorb is best installed via the Elpa package manager -- look for it in
+`list-packages'.
+
+You can also clone the source code from
+https://github.com/girzel/gnorb, and put the "gnorb" directory on your
+load-path. The Github site is also a good place to report bugs and
+other issues.
+* Setup
+Loading "gnorb" will make the basic functions available. Using Gnorb
+for email tracking takes a bit more setup, however:
+
+1. Email tracking is done via the Gnus registry, so that must be
+   activated with 'gnus-registry-initialize'.
+2. It also requires the org-id package to be loaded, and
+   `org-id-track-globally' set to t (that's the default value, so
+   simply loading the package should be enough).
+3. Add a nngnorb entry to your `gnus-secondary-select-methods'
+   variable. It will look like (nngnorb "Server name"). This does
+   nothing but provide a place to hang nnir searches.
+4. Then put a call to `gnorb-tracking-initialize' in your init files,
+   at some point after the Gnus registry is initialized.
+5. If you're not using a local archive method for saving your sent
+   messages (ie you're using IMAP), you'll also need to tell Gnorb
+   where to find your sent messages. Set the variable
+   `gnorb-gnus-sent-groups' to a list of strings; each string should
+   indicate a fully-qualified group name, eg "nnimap+SERVER:GROUP".
+
+Lastly, Gnorb doesn't bind any keys by default; see the 
[[id:de1b2579-86c2-4bb1-b77e-3467a3d2b3c7][Suggested
+Keybindings]] section below for possibilities.
+* Email Tracking
+The most interesting thing Gnorb does is using Org headings to track
+email conversations. This can mean anything from reminding yourself to
+write to your mother, to conducting delicate business negotiations
+over email, to running an email-based bug tracker.
+
+Gnorb assists in this process by using the Gnus registry to track
+correspondences between emails and Org headings -- specifically,
+message IDs are associated with Org heading ids. As a conversation
+develops, messages are collected on a heading (and/or its children).
+You can compose new messages directly from the Org heading, and Gnorb
+will automatically associate your sent message with the conversation.
+You can open temporary Gnus *Summary* buffers holding all the messages
+associated with an Org subtree, and reply from there. When you receive
+new messages relevant to a conversation, Gnorb will notice them and
+prompt you to associate them with the appropriate Org heading.
+Attachments on incoming messages can be automatically saved as
+attachments on Org headings, using org-attach.
+
+In general, the goal is to keep track of whole conversations, reduce
+friction when moving between Gnus and Org, and keep you in the Org
+agenda rather than in Gnus.
+** Email-Related Commands
+Email tracking starts in one of three ways:
+
+1. With an Org heading that represents an email TODO. Call
+   `gnorb-org-handle-mail' (see below) on the heading to compose a new
+   message, and start the tracking process.
+2. By calling org-capture on a received message. Any heading captured
+   from a message will automatically be associated with that message.
+3. By calling `gnorb-gnus-outgoing-do-todo' in a message composition
+   buffer -- see below.
+
+There are three main email-related commands:
+
+1. `gnorb-org-handle-mail' is called on an Org heading to compose a
+   new message. By default, this will begin a reply to the most recent
+   message in the conversation. If there are no associated messages to
+   reply to (or you call the function with a double prefix arg), Gnorb
+   will look for mailto: or bbdb: links in the heading, and compose a
+   new message to them.
+   
+   The sent message will be associated with the Org heading, and
+   you'll be brought back to the heading and asked to trigger an
+   action on it.
+   
+   `gnorb-email-subtree' is an alternative entry-point to
+   `gnorb-org-handle-mail'. It does the same thing as the latter, but
+   first exports the body of the subtree as either text or a file,
+   then inserts the text into the message body, or attaches the file
+   to the message, depending on what you've chosen.
+2. `gnorb-gnus-incoming-do-todo' is called on a message in a Gnus
+   *Summary* buffer. You'll be prompted for an Org heading, taken to
+   that heading, and asked to trigger an action on it.
+3. `gnorb-gnus-outgoing-do-todo' is called in message mode, while
+   composing a new message. 
+    
+   If called without a prefix arg, a new Org heading will be created
+   after the message is sent, and the sent message associated with it.
+   The new heading will be created as a capture heading, using the
+   template specified by the `gnorb-gnus-new-todo-capture-key' option.
+   
+   If you call this function with a prefix arg, you'll be prompted to
+   choose an existing Org heading instead. After the the message is
+   sent, you'll be taken to that heading and prompted to trigger an
+   action on it.
+   
+   It's also possible to call this function *after* a message is sent,
+   in case you forgot. Gnorb saves information about the most recently
+   sent message for this purpose.
+
+Because these three commands all express a similar intent, but are
+called in different modes, it can make sense to give each of them the
+same keybinding in the keymaps for Org mode, Gnus summary mode, and
+Message mode, respectively.
+** Trigger Actions
+After calling `gnorb-gnus-incoming-do-todo' on a message, or after
+sending a message associated with an Org heading, you'll be taken to
+the heading and asked to "trigger an action" on it. At the moment
+there are four different possibilities: triggering a TODO state-change
+on the heading, taking a note on the heading (both these options will
+associate the message with the heading), associating the message but
+doing nothing else, and lastly, doing nothing at all.
+
+More actions will be added in the future; it's also possible to
+rearrange or delete existing actions, and add your own: see the
+docstring of `gnorb-org-trigger-actions'.
+** Viewing Tracked Messages in *Summary* Buffers
+:PROPERTIES:
+:END:
+Call `gnorb-org-view' on an Org heading to open an nnir *Summary*
+buffer showing all the messages associated with that heading (this
+requires that you've added an nngnorb server to your Gnus backends). A
+minor mode will be in effect, ensuring that any replies you send to
+messages in this buffer will automatically be associated with the
+original Org heading. You can also invoke
+`gnorb-summary-disassociate-message' ("C-c d") to disassociate the
+message with the Org heading.
+
+As a bonus, it's possible to go into Gnus' *Server* buffer, find the
+line specifying your nngnorb server, and hit "G" (aka
+`gnus-group-make-nnir-group'). At the query prompt, enter an Org-style
+tags-todo Agenda query string (eg "+work-computer", or what have you).
+Gnorb will find all headings matching this query, scan their subtrees
+for gnus links, and then give you a Summary buffer containing all the
+linked messages. This is dog-slow at the moment; it will get faster.
+
+** Hinting in Gnus
+:PROPERTIES:
+:END:
+When you receive new mails that might be relevant to existing Org
+TODOs, Gnorb can alert you to that fact. When
+`gnorb-gnus-hint-relevant-article' is t (the default), Gnorb will
+display a message in the minibuffer when opening potentially relevant
+messages. You can then use `gnorb-gnus-incoming-to-todo' to trigger an
+action on the relevant TODO.
+
+This hinting can happen in the Gnus summary buffer as well. If you use
+the escape indicated by `gnorb-gnus-summary-mark-format-letter" as
+part of your `gnus-summary-line-format', articles that are relevant to
+TODOs will be marked with a special character in the Summary buffer,
+as determined by `gnorb-gnus-summary-mark'. By default, the format
+letter is "g" (meaning it is used as "%ug" in the format line), and
+the mark is "¡".
+** Message Attachments
+:PROPERTIES:
+:END:
+Gnorb simplifies the handling of attachments that you receive in
+emails. When you call `gnorb-gnus-incoming-do-todo' on a message,
+you'll be prompted to re-attach the email's attachments onto the Org
+heading, using the org-attach library.
+
+You can also do this as part of the capture process. Set the
+new :gnus-attachments key to "t" in a capture template that you use on
+mail messages, and you'll be queried to re-attach the message's
+attachments onto the newly-captured heading. Or set
+`gnorb-gnus-capture-always-attach' to "t" to have Gnorb do this for
+all capture templates.
+
+You can also do this using the regular system of MIME commands,
+without invoking the email tracking process. See 
[[id:de1b2579-86c2-4bb1-b77e-3467a3d2b3c7][Suggested
+Keybindings]], below.
+
+The same process works in reverse: when you send a message from an Org
+heading using `gnorb-org-handle-mail', Gnorb will ask if you want to
+attach the files in the heading's org-attach directory to the outgoing
+message.
+** Likely Workflow
+You receive an email from Jimmy, who wants to rent a room in your
+house. "I'll respond to this later," you think.
+
+You capture an Org TODO from the email, call it "Jimmy renting a
+room", and give it a REPLY keyword. Gnorb quietly records the
+correspondence between the email and the TODO, using the Gnus
+registry.
+
+The next day, looking at your Agenda, you see the TODO and decide to
+respond to the email. You call `gnorb-org-handle-mail' on the heading,
+and Gnorb opens Jimmy's email and starts a reply to it.
+
+You tell Jimmy the room's available in March, and send the message.
+Gnorb takes you back to the heading, and asks you to trigger an action
+on it. You choose "todo state", and change the heading keyword to
+WAIT.
+
+Two days later, Jimmy replies to your message, saying that March is
+perfect. When you open his response, Gnorb politely reminds you that
+the message is relevant to an existing TODO. You call
+`gnorb-gnus-incoming-do-todo' on the message, and are again taken to
+the TODO and asked to trigger an action. Again you choose "todo
+state", and change the heading keyword back to REPLY.
+
+You get another email, from Samantha, warning you not to rent the room
+to Jimmy. She even attaches a picture of a room in her house, as it
+looked after Jimmy had stayed there for six months. It's bad. You call
+`gnorb-gnus-incoming-do-todo' on her message, and pick the "Jimmy
+renting a room" heading. This time, you choose "take note" as the
+trigger action, and make a brief note about how bad that room looked.
+Gnorb asks if you'd like to attach the picture to the Org heading. You
+decide you will.
+
+Now it's time to write to Jimmy and say something noncommittal.
+Calling `gnorb-org-handle-mail' on the heading would respond to
+Samantha's email, the most recent of the associated messages, which
+isn't what you want. Instead you call `gnorb-org-view' on the heading,
+which opens up a Gnus *Summary* buffer containing all four messages:
+Jimmy's first, your response, his response to that, and Samantha's
+message. You pick Jimmy's second email, and reply to it normally.
+Gnorb asks if you'd like to send the picture of the room as an
+attachment. You would not. When you send the reply Gnorb tracks that
+as well, and does the "trigger an action" trick again.
+
+In this way Gnorb helps you manage an entire conversation, possibly
+with multiple threads and multiple participants. Mostly all you need
+to do is call `gnorb-gnus-incoming-do-todo' on newly-received
+messages, and `gnorb-org-handle-mail' on the heading when it's time to
+compose a new reply.
+* Restoring Window Layout
+Many Gnorb functions alter the window layout and value of point. In
+most of these cases, you can restore the previous layout using the
+interactive function `gnorb-restore-layout'.
+
+* Recent Mails From BBDB Contacts
+:PROPERTIES:
+:END:
+If you're using a recent git version of BBDB (circa mid-May 2014 or
+later), you can give your BBDB contacts a special field which will
+collect links to recent emails from that contact. The default name of
+the field is "messages", but you can customize that name using the
+`gnorb-bbdb-messages-field' option.
+
+Gnorb will not collect links by default: you need to call
+`gnorb-bbdb-open-link' on a contact once to start the process.
+Thereafter, opening mails from that contact will store a link to the
+message.
+
+Once some links are stored, `gnorb-bbdb-open-link' will open them: Use
+a prefix arg to the function call to select particular messages to
+open. There are several options controlling how all this works; see
+the gnorb-bbdb user options section below for details.
+* BBDB posting styles
+:PROPERTIES:
+:END:
+Gnorb comes with a BBDB posting-style system, inspired by (copied
+from) gnus-posting-styles. You can specify how messages are composed
+to specific contacts, by matching on contact field values (the same
+way gnus-posting-styles matches on group names). See the docstring of
+`gnorb-bbdb-posting-styles' for details.
+
+In order not to be too intrusive, Gnorb doesn't alter the behavior of
+`bbdb-mail', the usual mail-composition function. Instead it provides
+an alternate `gnorb-bbdb-mail', which does exactly the same thing, but
+first processes the new mail according to `gnorb-bbdb-posting-styles'.
+If you want to use this feature regularly, you can remap `bbdb-mail'
+to `gnorb-bbdb-mail' in the `bbdb-mode-map'.
+* BBDB Org tagging
+BBDB contacts can be tagged with the same tags you use in your Org
+files. This allows you to pop up a *BBDB* buffer alongside your Org
+Agenda when searching for certain tags. This can happen automatically
+for all Org tags-todo searches, if you set the option
+`gnorb-org-agenda-popup-bbdb' to t. Or you can do it manually, by
+calling the command of the same name. This command only shows TODOs by
+default: use a prefix argument to show all tagged headings.
+
+Tags are stored in an xfield named org-tags, by default. You can
+customize the name of this field using `gnorb-bbdb-org-tag-field'.
+* Misc BBDB
+** Searching for messages from BBDB contacts
+:PROPERTIES:
+:END:
+Call `gnorb-bbdb-mail-search' to search for all mail messages from the
+record(s) displayed. Currently supports the notmuch, mairix, and
+namazu search backends; set `gnorb-gnus-mail-search-backend' to one of
+those symbol values.
+** Citing BBDB contacts
+:PROPERTIES:
+:END:
+Calling `gnorb-bbdb-cite-contact' will prompt for a BBDB record and
+insert a string of the type "Bob Smith <bob@smith.com>".
+** User Options
+- `gnorb-bbdb-org-tag-field :: The name of the BBDB xfield, as a
+     symbol, that holds Org-related tags. Specified as a string with
+     the ":" separator between tags, same as for Org headings.
+     Defaults to org-tag.
+- `gnorb-bbdb-messages-field' :: The name of the BBDB xfield that
+     holds links to recently-received messages from this contact.
+     Defaults to 'messages.
+- `gnorb-bbdb-collect-N-messages' :: Collect at most this many links
+     to messages from this contact. Defaults to 5.
+- `gnorb-bbdb-define-recent' :: What does "recently-received" mean?
+     Possible values are the symbols seen and received. When set to
+     seen, the most recently-opened messages are collected. When set
+     to received, the most recently-received (by Date header) messages
+     are collected. Defaults to seen.
+- `gnorb-bbdb-message-link-format-multi' :: How is a single message's
+     link formatted in the multi-line BBDB layout format? Defaults to
+     "%:count. %D: %:subject" (see the docstring for details).
+- ` gnorb-bbdb-message-link-format-one' :: How is a single message's
+     link formatted in the one-line BBDB layout format? Defaults to
+     nil (see the docstring for details).
+- `gnorb-bbdb-posting-styles' :: Styles to use for influencing the
+     format of mails composed to the BBDB record(s) under point (see
+     the docstring for details).
+* Misc Org
+** Inserting BBDB links
+:PROPERTIES:
+:END:
+Calling `gnorb-org-contact-link' will prompt for a BBDB record and
+insert an Org link to that record at point.
+** User Options
+- `gnorb-org-after-message-setup-hook' :: Hook run in a message buffer
+     after setting up the message, from `gnorb-org-handle-mail' or
+     `gnorb-org-email-subtree'.
+- `gnorb-org-trigger-actions' :: List of potential actions that can be
+     taken on headings after a message is sent. See docstring for
+     details.
+- `gnorb-org-mail-scan-scope' :: The number of paragraphs to scan for
+     mail-related links. This comes into play when calling
+     `gnorb-org-handle-mail' on a heading with no associated messages,
+     or when `gnorb-org-handle-mail' is called with a prefix arg.
+- `gnorb-org-find-candidates-match' :: When searching all Org files
+     for headings to collect messages from, this option can limit
+     which headings are searched. It is used as the second argument to
+     a call to `org-map-entries', and has the same syntax as that used
+     in an agenda tags view.
+- `gnorb-org-email-subtree-text-parameters' :: A plist of export
+     parameters corresponding to the EXT-PLIST argument to the export
+     functions, for use when exporting to text.
+- `gnorb-org-email-subtree-file-parameters' :: A plist of export
+     parameters corresponding to the EXT-PLIST argument to the export
+     functions, for use when exporting to a file.
+- `gnorb-org-email-subtree-text-options' :: A list of ts and nils
+     corresponding to Org's export options, to be used when exporting
+     to text. The options, in order, are async, subtreep,
+     visible-only, and body-only.
+- `gnorb-org-email-subtree-file-options' :: 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.
+- `gnorb-org-export-extensions' :: Correspondence between export
+     backends and their respective (usual) file extensions.
+- `gnorb-org-capture-collect-link-p' :: When this is set to t, the
+     capture process will always store a link to the Gnus message or
+     BBDB record under point, even when the link isn't part of the
+     capture template. It can then be added to the captured heading
+     with org-insert-link, as usual.
+- `gnorb-org-agenda-popup-bbdb' :: Set to "t" to automatically pop up
+     the BBDB buffer displaying records corresponding to the Org
+     Agenda tags search underway. If this is nil you can always do it
+     manually with the command of the same name.
+- `gnorb-org-bbdb-popup-layout' :: Controls the layout of the
+     Agenda-related BBDB popup, takes the same values as
+     bbdb-pop-up-layout.
+* Misc Gnus
+** Viewing Org headlines relevant to a message
+:PROPERTIES:
+:END:
+Call `gnorb-gnus-view' on a message that is associated with an Org
+heading to jump to that heading.
+** User Options
+- `gnorb-gnus-mail-search-backend' :: Specifies the search backend
+     that you use for searching mails. Currently supports notmuch,
+     mairix, and namazu: set this option to one of those symbols.
+- `gnorb-gnus-capture-always-attach' :: Treat all capture templates as
+     if they had the :gnus-attachments key set to "t". This only has
+     any effect if you're capturing from a Gnus summary or article
+     buffer.
+- `gnorb-trigger-todo-default' :: Set to either 'note or 'todo to tell
+     `gnorb-gnus-incoming-do-todo' what to do by default. You can
+     reach the non-default behavior by calling that function with a
+     prefix argument. Alternately, set to 'prompt to always prompt for
+     the appropriate action.
+- `gnorb-gnus-trigger-refile-targets' :: If you use
+     `gnorb-gnus-incoming-do-todo' on an incoming message, Gnorb will
+     try to locate a TODO heading that's relevant to that message. If
+     it can't, it will prompt you for one, using the refile interface.
+     This option will be used as the value of `org-refile-targets'
+     during that process: see the docstring of `org-refile-targets'
+     for the appropriate syntax.
+- `gnorb-gnus-new-todo-capture-key' :: Set this to a single-character
+     string pointing at an Org capture template to use when creating
+     TODOs from outgoing messages. The template is a regular capture
+     template, with a few exceptions. If Gnus helps you archive
+     outgoing messages (ie you have `gnus-message-archive-group' set
+     to something, and your outgoing messages have a "Fcc" header), a
+     link to that message will be made, and you'll be able to use all
+     the escapes related to gnus messages. If you don't archive
+     outgoing messages, you'll still be able to use the %:subject,
+     %:to, %:toname, %:toaddress, and %:date escapes in the capture
+     template.
+- `gnorb-gnus-hint-relevant-article' :: Set to "t" (the default) to
+     have Gnorb give you a hint in the minibuffer when opening
+     messages that might be relevant to existing Org TODOs.
+- `gnorb-gnus-summary-mark-format-letter' :: The formatting letter to
+     use as part of your `gnus-summary-line-format', to indicate
+     messages which might be relevant to Org TODOs. Defaults to "g",
+     meaning it should be used as "%ug" in the format line.
+- `gnorb-gnus-summary-mark' :: The mark used to indicate relevant
+     messages in the Summary buffer, when
+     `gnorb-gnus-summary-mark-format-letter' is present in the format
+     line. Defaults to "¡".
+* Suggested Keybindings
+:PROPERTIES:
+:ID:       de1b2579-86c2-4bb1-b77e-3467a3d2b3c7
+:END:
+#+BEGIN_SRC emacs-lisp
+  (eval-after-load "gnorb-bbdb"
+    '(progn
+       (define-key bbdb-mode-map (kbd "O") 'gnorb-bbdb-tag-agenda)
+       (define-key bbdb-mode-map (kbd "S") 'gnorb-bbdb-mail-search)
+       (define-key bbdb-mode-map [remap bbdb-mail] 'gnorb-bbdb-mail)
+       (define-key bbdb-mode-map (kbd "l") 'gnorb-bbdb-open-link)
+       (global-set-key (kbd "C-c C") 'gnorb-bbdb-cite-contact)))
+
+  (eval-after-load "gnorb-org"
+    '(progn
+       (org-defkey org-mode-map (kbd "C-c C") 'gnorb-org-contact-link)
+       (org-defkey org-mode-map (kbd "C-c t") 'gnorb-org-handle-mail)
+       (org-defkey org-mode-map (kbd "C-c e") 'gnorb-org-view)
+       (org-defkey org-mode-map (kbd "C-c E") 'gnorb-org-email-subtree)
+       (org-defkey org-mode-map (kbd "C-c V") 'gnorb-org-popup-bbdb)
+       (setq gnorb-org-agenda-popup-bbdb t)
+       (eval-after-load "org-agenda"
+         '(progn (org-defkey org-agenda-mode-map (kbd "H") 
'gnorb-org-handle-mail)
+                 (org-defkey org-agenda-mode-map (kbd "V") 
'gnorb-org-popup-bbdb)))))
+
+  (eval-after-load "gnorb-gnus"
+    '(progn
+       (define-key gnus-summary-mime-map "a" 'gnorb-gnus-article-org-attach)
+       (define-key gnus-summary-mode-map (kbd "C-c t") 
'gnorb-gnus-incoming-do-todo)
+       (push '("attach to org heading" . gnorb-gnus-mime-org-attach)
+             gnus-mime-action-alist)
+       ;; The only way to add mime button command keys is by redefining
+       ;; gnus-mime-button-map, possibly not ideal. Ideal would be a
+       ;; setter function in gnus itself.
+       (push '(gnorb-gnus-mime-org-attach "a" "Attach to Org heading")
+             gnus-mime-button-commands)
+       (setq gnus-mime-button-map
+             (let ((map (make-sparse-keymap)))
+               (define-key map gnus-mouse-2 'gnus-article-push-button)
+               (define-key map gnus-down-mouse-3 'gnus-mime-button-menu)
+               (dolist (c gnus-mime-button-commands)
+                 (define-key map (cadr c) (car c)))
+               map))))
+
+  (eval-after-load "message"
+    '(progn
+       (define-key message-mode-map (kbd "C-c t") 
'gnorb-gnus-outgoing-do-todo)))
+#+END_SRC
+* Wishlist/TODO
+- Provide a command that, when in the Org Agenda, does an email search
+  for messages received in the visible date span, or day under point,
+  etc. Make it work in the calendar, as well?
+- Add trigger actions that create new sibling or child headings on the
+  original Org heading.
+- Allow tagging of Gnus messages, by giving the message's registry
+  entry an 'org-tags key.
+- Provide persistent nngnorb search groups.
+- Allow automatic org-tagging of BBDB contacts: when messages from a
+  contact are associated with an Org heading, make it possible for the
+  contact to inherit that heading's tags automatically.
+- Provide completion when setting Org tags on a BBDB contact.
+- Provide a `gnorb-bbdb-view' command that opens a *Summary* buffer
+  containing all the tracked messages from the contact(s) under point.
+- Provide a `gnorb-view' command that takes a tags-todo search phrase
+  (or a single Org heading ID), finds all relevant messages, Org
+  headings, and BBDB records, and sets up a four-pane view: Org
+  Agenda, *BBDB* buffer, Gnus *Summary* buffer, and an *Article*
+  buffer.
diff --git a/gnorb.texi b/gnorb.texi
index bf1f256..643552f 100644
--- a/gnorb.texi
+++ b/gnorb.texi
@@ -1,5 +1,654 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename ./gnorb.info
+@settitle Gnorb Manual
+@documentencoding UTF-8
+@documentlanguage en
+@syncodeindex pg cp
+@c %**end of header
 
-@c Local Variables: 
-@c mode: texinfo
-@c TeX-master: "."
-@c End: 
+@dircategory Emacs
+@direntry
+* Gnorb: (gnorb).       Glue code for Gnus, Org, and BBDB.
+@end direntry
+
+@finalout
+@titlepage
+@title Gnorb Manual
+@subtitle for version 1, updated 3 October, 2014
+@end titlepage
+
+@ifnottex
+@node Top
+@top Gnorb Manual
+@end ifnottex
+
+@menu
+* Introduction::
+* Installation::
+* Setup::
+* Email Tracking::
+* Restoring Window Layout::
+* Recent Mails From BBDB Contacts::
+* BBDB posting styles::
+* BBDB Org tagging::
+* Misc BBDB::
+* Misc Org::
+* Misc Gnus::
+* Suggested Keybindings::
+* Wishlist/TODO::
+* Index::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Email Tracking
+
+* Email-Related Commands::
+* Trigger Actions::
+* Viewing Tracked Messages in *Summary* Buffers::
+* Hinting in Gnus::
+* Message Attachments::
+
+Misc BBDB
+
+* Searching for messages from BBDB contacts::
+* Citing BBDB contacts::
+* User Options::
+
+Misc Org
+
+* Inserting BBDB links::
+* User Options: User Optionsx. 
+
+Misc Gnus
+
+* Viewing Org headlines relevant to a message::
+* User Options: User Optionsxx. 
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+Gnorb provides glue code between the Gnus, Org, and BBDB packages.
+It's aimed at supporting email-based project management, and generally
+making it easier to keep track of email communication.
+
+Much of the code consists of single-use convenience functions, but
+tracking email conversations with Org requires is more complicated,
+and requires a bit of setup.
+
+Gnorb can be used in a modular fashion, by selectively loading the
+files ``gnorb-org'', ``gnorb-gnus'' or ``gnorb-bbdb'' instead of plain old
+``gnorb''. The package as a whole is rather Org-centric, though, and it
+won't do much of interest without ``gnorb-org''.
+
+This means that Gnorb doesn't have hard requirements to any of the
+three base libraries. For the libraries you are using, however, you'll
+get best results from using the most recent stable version (yes, that
+means BBDB 3). Some of the features in Gnorb only work with
+development versions of these libraries (those cases are noted below).
+
+@node Installation
+@chapter Installation
+
+Gnorb is best installed via the Elpa package manager -- look for it in
+`list-packages'.
+
+You can also clone the source code from
+@uref{https://github.com/girzel/gnorb}, and put the ``gnorb'' directory on your
+load-path. The Github site is also a good place to report bugs and
+other issues.
+
+@node Setup
+@chapter Setup
+
+Loading ``gnorb'' will make the basic functions available. Using Gnorb
+for email tracking takes a bit more setup, however:
+
+@enumerate
+@item
+Email tracking is done via the Gnus registry, so that must be
+activated with `gnus-registry-initialize'.
+@item
+It also requires the org-id package to be loaded, and
+`org-id-track-globally' set to t (that's the default value, so
+simply loading the package should be enough).
+@item
+Add a nngnorb entry to your `gnus-secondary-select-methods'
+variable. It will look like (nngnorb ``Server name''). This does
+nothing but provide a place to hang nnir searches.
+@item
+Then put a call to `gnorb-tracking-initialize' in your init files,
+at some point after the Gnus registry is initialized.
+@item
+If you're not using a local archive method for saving your sent
+messages (ie you're using IMAP), you'll also need to tell Gnorb
+where to find your sent messages. Set the variable
+`gnorb-gnus-sent-groups' to a list of strings; each string should
+indicate a fully-qualified group name, eg ``nnimap+SERVER:GROUP''.
+@end enumerate
+
+Lastly, Gnorb doesn't bind any keys by default; see the @ref{Suggested 
Keybindings,Suggested
+Keybindings} section below for possibilities.
+
+@node Email Tracking
+@chapter Email Tracking
+
+The most interesting thing Gnorb does is using Org headings to track
+email conversations. This can mean anything from reminding yourself to
+write to your mother, to conducting delicate business negotiations
+over email, to running an email-based bug tracker.
+
+Gnorb assists in this process by using the Gnus registry to track
+correspondences between emails and Org headings -- specifically,
+message IDs are associated with Org heading ids. As a conversation
+develops, messages are collected on a heading (and/or its children).
+You can compose new messages directly from the Org heading, and Gnorb
+will automatically associate your sent message with the conversation.
+You can open temporary Gnus *Summary* buffers holding all the messages
+associated with an Org subtree, and reply from there. When you receive
+new messages relevant to a conversation, Gnorb will notice them and
+prompt you to associate them with the appropriate Org heading.
+Attachments on incoming messages can be automatically saved as
+attachments on Org headings, using org-attach.
+
+In general, the goal is to keep track of whole conversations, reduce
+friction when moving between Gnus and Org, and keep you in the Org
+agenda rather than in Gnus.
+@menu
+* Email-Related Commands::
+* Trigger Actions::
+* Viewing Tracked Messages in *Summary* Buffers::
+* Hinting in Gnus::
+* Message Attachments::
+@end menu
+
+@node Email-Related Commands
+@section Email-Related Commands
+
+Email tracking starts in one of three ways:
+
+@enumerate
+@item
+With an Org heading that represents an email TODO. Call
+`gnorb-org-handle-mail' (see below) on the heading to compose a new
+message, and start the tracking process.
+@item
+By calling org-capture on a received message. Any heading captured
+from a message will automatically be associated with that message.
+@item
+By calling `gnorb-gnus-outgoing-do-todo' in a message composition
+buffer -- see below.
+@end enumerate
+
+There are three main email-related commands:
+
+@enumerate
+@item
+`gnorb-org-handle-mail' is called on an Org heading to compose a
+new message. By default, this will begin a reply to the most recent
+message in the conversation. If there are no associated messages to
+reply to (or you call the function with a double prefix arg), Gnorb
+will look for mailto: or bbdb: links in the heading, and compose a
+new message to them.
+
+The sent message will be associated with the Org heading, and
+you'll be brought back to the heading and asked to trigger an
+action on it.
+
+`gnorb-email-subtree' is an alternative entry-point to
+`gnorb-org-handle-mail'. It does the same thing as the latter, but
+first exports the body of the subtree as either text or a file,
+then inserts the text into the message body, or attaches the file
+to the message, depending on what you've chosen.
+@item
+`gnorb-gnus-incoming-do-todo' is called on a message in a Gnus
+*Summary* buffer. You'll be prompted for an Org heading, taken to
+that heading, and asked to trigger an action on it.
+@item
+`gnorb-gnus-outgoing-do-todo' is called in message mode, while
+composing a new message. 
+
+If called without a prefix arg, a new Org heading will be created
+after the message is sent, and the sent message associated with it.
+The new heading will be created as a capture heading, using the
+template specified by the `gnorb-gnus-new-todo-capture-key' option.
+
+If you call this function with a prefix arg, you'll be prompted to
+choose an existing Org heading instead. After the the message is
+sent, you'll be taken to that heading and prompted to trigger an
+action on it.
+
+It's also possible to call this function *after* a message is sent,
+in case you forgot. Gnorb saves information about the most recently
+sent message for this purpose.
+@end enumerate
+
+Because these three commands all express a similar intent, but are
+called in different modes, it can make sense to give each of them the
+same keybinding in the keymaps for Org mode, Gnus summary mode, and
+Message mode, respectively.
+
+@node Trigger Actions
+@section Trigger Actions
+
+After calling `gnorb-gnus-incoming-do-todo' on a message, or after
+sending a message associated with an Org heading, you'll be taken to
+the heading and asked to ``trigger an action'' on it. At the moment
+there are four different possibilities: triggering a TODO state-change
+on the heading, taking a note on the heading (both these options will
+associate the message with the heading), associating the message but
+doing nothing else, and lastly, doing nothing at all.
+
+More actions will be added in the future; it's also possible to add
+your own action: see the docstring of `gnorb-org-trigger-actions'.
+
+@node Viewing Tracked Messages in *Summary* Buffers
+@section Viewing Tracked Messages in *Summary* Buffers
+
+Call `gnorb-org-view' on an Org heading to open an nnir *Summary*
+buffer showing all the messages associated with that heading (this
+requires that you've added an nngnorb server to your Gnus backends). A
+minor mode will be in effect, ensuring that any replies you send to
+messages in this buffer will automatically be associated with the
+original Org heading. You can also invoke
+`gnorb-summary-disassociate-message' (``C-c d'') to disassociate the
+message with the Org heading.
+
+As a bonus, it's possible to go into Gnus' *Server* buffer, find the
+line specifying your nngnorb server, and hit ``G'' (aka
+`gnus-group-make-nnir-group'). At the query prompt, enter an Org-style
+tags-todo Agenda query string (eg ``+work-computer'', or what have you).
+Gnorb will find all headings matching this query, scan their subtrees
+for gnus links, and then give you a Summary buffer containing all the
+linked messages. This is dog-slow at the moment; it will get faster.
+
+@node Hinting in Gnus
+@section Hinting in Gnus
+
+When you receive new mails that might be relevant to existing Org
+TODOs, Gnorb can alert you to that fact. When
+`gnorb-gnus-hint-relevant-article' is t (the default), Gnorb will
+display a message in the minibuffer when opening potentially relevant
+messages. You can then use `gnorb-gnus-incoming-to-todo' to trigger an
+action on the relevant TODO.
+
+This hinting can happen in the Gnus summary buffer as well. If you use
+the escape indicated by `gnorb-gnus-summary-mark-format-letter'' as
+part of your `gnus-summary-line-format', articles that are relevant to
+TODOs will be marked with a special character in the Summary buffer,
+as determined by `gnorb-gnus-summary-mark'. By default, the format
+letter is ``g'' (meaning it is used as ``%ug'' in the format line), and
+the mark is ``¡''.
+
+@node Message Attachments
+@section Message Attachments
+
+Gnorb simplifies the handling of attachments that you receive in
+emails. When you call `gnorb-gnus-incoming-do-todo' on a message,
+you'll be prompted to re-attach the email's attachments onto the Org
+heading, using the org-attach library.
+
+You can also do this as part of the capture process. Set the
+new :gnus-attachments key to ``t'' in a capture template that you use on
+mail messages, and you'll be queried to re-attach the message's
+attachments onto the newly-captured heading. Or set
+`gnorb-gnus-capture-always-attach' to ``t'' to have Gnorb do this for
+all capture templates.
+
+You can also do this using the regular system of MIME commands,
+without invoking the email tracking process. See @ref{Suggested 
Keybindings,Suggested
+Keybindings}, below.
+
+The same process works in reverse: when you send a message from an Org
+heading using `gnorb-org-handle-mail', Gnorb will ask if you want to
+attach the files in the heading's org-attach directory to the outgoing
+message.
+
+@node Restoring Window Layout
+@chapter Restoring Window Layout
+
+Many Gnorb functions alter the window layout and value of point. In
+most of these cases, you can restore the previous layout using the
+interactive function `gnorb-restore-layout'.
+
+@node Recent Mails From BBDB Contacts
+@chapter Recent Mails From BBDB Contacts
+
+If you're using a recent git version of BBDB (circa mid-May 2014 or
+later), you can give your BBDB contacts a special field which will
+collect links to recent emails from that contact. The default name of
+the field is ``messages'', but you can customize that name using the
+`gnorb-bbdb-messages-field' option.
+
+Gnorb will not collect links by default: you need to call
+`gnorb-bbdb-open-link' on a contact once to start the process.
+Thereafter, opening mails from that contact will store a link to the
+message.
+
+Once some links are stored, `gnorb-bbdb-open-link' will open them: Use
+a prefix arg to the function call to select particular messages to
+open. There are several options controlling how all this works; see
+the gnorb-bbdb user options section below for details.
+
+@node BBDB posting styles
+@chapter BBDB posting styles
+
+Gnorb comes with a BBDB posting-style system, inspired by (copied
+from) gnus-posting-styles. You can specify how messages are composed
+to specific contacts, by matching on contact field values (the same
+way gnus-posting-styles matches on group names). See the docstring of
+`gnorb-bbdb-posting-styles' for details.
+
+In order not to be too intrusive, Gnorb doesn't alter the behavior of
+`bbdb-mail', the usual mail-composition function. Instead it provides
+an alternate `gnorb-bbdb-mail', which does exactly the same thing, but
+first processes the new mail according to `gnorb-bbdb-posting-styles'.
+If you want to use this feature regularly, you can remap `bbdb-mail'
+to `gnorb-bbdb-mail' in the `bbdb-mode-map'.
+
+@node BBDB Org tagging
+@chapter BBDB Org tagging
+
+BBDB contacts can be tagged with the same tags you use in your Org
+files. This allows you to pop up a *BBDB* buffer alongside your Org
+Agenda when searching for certain tags. This can happen automatically
+for all Org tags-todo searches, if you set the option
+`gnorb-org-agenda-popup-bbdb' to t. Or you can do it manually, by
+calling the command of the same name. This command only shows TODOs by
+default: use a prefix argument to show all tagged headings.
+
+Tags are stored in an xfield named org-tags, by default. You can
+customize the name of this field using `gnorb-bbdb-org-tag-field'.
+
+@node Misc BBDB
+@chapter Misc BBDB
+
+@menu
+* Searching for messages from BBDB contacts::
+* Citing BBDB contacts::
+* User Options::
+@end menu
+
+@node Searching for messages from BBDB contacts
+@section Searching for messages from BBDB contacts
+
+Call `gnorb-bbdb-mail-search' to search for all mail messages from the
+record(s) displayed. Currently supports the notmuch, mairix, and
+namazu search backends; set `gnorb-gnus-mail-search-backend' to one of
+those symbol values.
+
+@node Citing BBDB contacts
+@section Citing BBDB contacts
+
+Calling `gnorb-bbdb-cite-contact' will prompt for a BBDB record and
+insert a string of the type ``Bob Smith <bob@@smith.com>''.
+
+@node User Options
+@section User Options
+
+@table @samp
+@item `gnorb-bbdb-org-tag-field
+The name of the BBDB xfield, as a
+symbol, that holds Org-related tags. Specified as a string with
+the ``:'' separator between tags, same as for Org headings.
+Defaults to org-tag.
+@item `gnorb-bbdb-messages-field'
+The name of the BBDB xfield that
+holds links to recently-received messages from this contact.
+Defaults to `messages.
+@item `gnorb-bbdb-collect-N-messages'
+Collect at most this many links
+to messages from this contact. Defaults to 5.
+@item `gnorb-bbdb-define-recent'
+What does ``recently-received'' mean?
+Possible values are the symbols seen and received. When set to
+seen, the most recently-opened messages are collected. When set
+to received, the most recently-received (by Date header) messages
+are collected. Defaults to seen.
+@item `gnorb-bbdb-message-link-format-multi'
+How is a single message's
+link formatted in the multi-line BBDB layout format? Defaults to
+``%:count. %D: %:subject'' (see the docstring for details).
+@item ` gnorb-bbdb-message-link-format-one'
+How is a single message's
+link formatted in the one-line BBDB layout format? Defaults to
+nil (see the docstring for details).
+@item `gnorb-bbdb-posting-styles'
+Styles to use for influencing the
+format of mails composed to the BBDB record(s) under point (see
+the docstring for details).
+@end table
+
+@node Misc Org
+@chapter Misc Org
+
+@menu
+* Inserting BBDB links::
+* User Options: User Optionsx. 
+@end menu
+
+@node Inserting BBDB links
+@section Inserting BBDB links
+
+Calling `gnorb-org-contact-link' will prompt for a BBDB record and
+insert an Org link to that record at point.
+
+@node User Optionsx
+@section User Options
+
+@table @samp
+@item `gnorb-org-after-message-setup-hook'
+Hook run in a message buffer
+after setting up the message, from `gnorb-org-handle-mail' or
+`gnorb-org-email-subtree'.
+@item `gnorb-org-trigger-actions'
+List of potential actions that can be
+taken on headings after a message is sent. See docstring for
+details.
+@item `gnorb-org-mail-scan-scope'
+The number of paragraphs to scan for
+mail-related links. This comes into play when calling
+`gnorb-org-handle-mail' on a heading with no associated messages,
+or when `gnorb-org-handle-mail' is called with a prefix arg.
+@item `gnorb-org-find-candidates-match'
+When searching all Org files
+for headings to collect messages from, this option can limit
+which headings are searched. It is used as the second argument to
+a call to `org-map-entries', and has the same syntax as that used
+in an agenda tags view.
+@item `gnorb-org-email-subtree-text-parameters'
+A plist of export
+parameters corresponding to the EXT-PLIST argument to the export
+functions, for use when exporting to text.
+@item `gnorb-org-email-subtree-file-parameters'
+A plist of export
+parameters corresponding to the EXT-PLIST argument to the export
+functions, for use when exporting to a file.
+@item `gnorb-org-email-subtree-text-options'
+A list of ts and nils
+corresponding to Org's export options, to be used when exporting
+to text. The options, in order, are async, subtreep,
+visible-only, and body-only.
+@item `gnorb-org-email-subtree-file-options'
+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.
+@item `gnorb-org-export-extensions'
+Correspondence between export
+backends and their respective (usual) file extensions.
+@item `gnorb-org-capture-collect-link-p'
+When this is set to t, the
+capture process will always store a link to the Gnus message or
+BBDB record under point, even when the link isn't part of the
+capture template. It can then be added to the captured heading
+with org-insert-link, as usual.
+@item `gnorb-org-agenda-popup-bbdb'
+Set to ``t'' to automatically pop up
+the BBDB buffer displaying records corresponding to the Org
+Agenda tags search underway. If this is nil you can always do it
+manually with the command of the same name.
+@item `gnorb-org-bbdb-popup-layout'
+Controls the layout of the
+Agenda-related BBDB popup, takes the same values as
+bbdb-pop-up-layout.
+@end table
+
+@node Misc Gnus
+@chapter Misc Gnus
+
+@menu
+* Viewing Org headlines relevant to a message::
+* User Options: User Optionsxx. 
+@end menu
+
+@node Viewing Org headlines relevant to a message
+@section Viewing Org headlines relevant to a message
+
+Call `gnorb-gnus-view' on a message that is associated with an Org
+heading to jump to that heading.
+
+@node User Optionsxx
+@section User Options
+
+@table @samp
+@item `gnorb-gnus-mail-search-backend'
+Specifies the search backend
+that you use for searching mails. Currently supports notmuch,
+mairix, and namazu: set this option to one of those symbols.
+@item `gnorb-gnus-capture-always-attach'
+Treat all capture templates as
+if they had the :gnus-attachments key set to ``t''. This only has
+any effect if you're capturing from a Gnus summary or article
+buffer.
+@item `gnorb-trigger-todo-default'
+Set to either `note or `todo to tell
+`gnorb-gnus-incoming-do-todo' what to do by default. You can
+reach the non-default behavior by calling that function with a
+prefix argument. Alternately, set to `prompt to always prompt for
+the appropriate action.
+@item `gnorb-gnus-trigger-refile-targets'
+If you use
+`gnorb-gnus-incoming-do-todo' on an incoming message, Gnorb will
+try to locate a TODO heading that's relevant to that message. If
+it can't, it will prompt you for one, using the refile interface.
+This option will be used as the value of `org-refile-targets'
+during that process: see the docstring of `org-refile-targets'
+for the appropriate syntax.
+@item `gnorb-gnus-new-todo-capture-key'
+Set this to a single-character
+string pointing at an Org capture template to use when creating
+TODOs from outgoing messages. The template is a regular capture
+template, with a few exceptions. If Gnus helps you archive
+outgoing messages (ie you have `gnus-message-archive-group' set
+to something, and your outgoing messages have a ``Fcc'' header), a
+link to that message will be made, and you'll be able to use all
+the escapes related to gnus messages. If you don't archive
+outgoing messages, you'll still be able to use the %:subject,
+%:to, %:toname, %:toaddress, and %:date escapes in the capture
+template.
+@item `gnorb-gnus-hint-relevant-article'
+Set to ``t'' (the default) to
+have Gnorb give you a hint in the minibuffer when opening
+messages that might be relevant to existing Org TODOs.
+@item `gnorb-gnus-summary-mark-format-letter'
+The formatting letter to
+use as part of your `gnus-summary-line-format', to indicate
+messages which might be relevant to Org TODOs. Defaults to ``g'',
+meaning it should be used as ``%ug'' in the format line.
+@item `gnorb-gnus-summary-mark'
+The mark used to indicate relevant
+messages in the Summary buffer, when
+`gnorb-gnus-summary-mark-format-letter' is present in the format
+line. Defaults to ``¡''.
+@end table
+
+@node Suggested Keybindings
+@chapter Suggested Keybindings
+
+@lisp
+(eval-after-load "gnorb-bbdb"
+  '(progn
+     (define-key bbdb-mode-map (kbd "O") 'gnorb-bbdb-tag-agenda)
+     (define-key bbdb-mode-map (kbd "S") 'gnorb-bbdb-mail-search)
+     (define-key bbdb-mode-map [remap bbdb-mail] 'gnorb-bbdb-mail)
+     (define-key bbdb-mode-map (kbd "l") 'gnorb-bbdb-open-link)
+     (global-set-key (kbd "C-c C") 'gnorb-bbdb-cite-contact)))
+
+(eval-after-load "gnorb-org"
+  '(progn
+     (org-defkey org-mode-map (kbd "C-c C") 'gnorb-org-contact-link)
+     (org-defkey org-mode-map (kbd "C-c t") 'gnorb-org-handle-mail)
+     (org-defkey org-mode-map (kbd "C-c e") 'gnorb-org-view)
+     (org-defkey org-mode-map (kbd "C-c E") 'gnorb-org-email-subtree)
+     (org-defkey org-mode-map (kbd "C-c V") 'gnorb-org-popup-bbdb)
+     (setq gnorb-org-agenda-popup-bbdb t)
+     (eval-after-load "org-agenda"
+       '(progn (org-defkey org-agenda-mode-map (kbd "H") 
'gnorb-org-handle-mail)
+               (org-defkey org-agenda-mode-map (kbd "V") 
'gnorb-org-popup-bbdb)))))
+
+(eval-after-load "gnorb-gnus"
+  '(progn
+     (define-key gnus-summary-mime-map "a" 'gnorb-gnus-article-org-attach)
+     (define-key gnus-summary-mode-map (kbd "C-c t") 
'gnorb-gnus-incoming-do-todo)
+     (push '("attach to org heading" . gnorb-gnus-mime-org-attach)
+           gnus-mime-action-alist)
+     ;; The only way to add mime button command keys is by redefining
+     ;; gnus-mime-button-map, possibly not ideal. Ideal would be a
+     ;; setter function in gnus itself.
+     (push '(gnorb-gnus-mime-org-attach "a" "Attach to Org heading")
+           gnus-mime-button-commands)
+     (setq gnus-mime-button-map
+           (let ((map (make-sparse-keymap)))
+             (define-key map gnus-mouse-2 'gnus-article-push-button)
+             (define-key map gnus-down-mouse-3 'gnus-mime-button-menu)
+             (dolist (c gnus-mime-button-commands)
+               (define-key map (cadr c) (car c)))
+             map))))
+
+(eval-after-load "message"
+  '(progn
+     (define-key message-mode-map (kbd "C-c t") 'gnorb-gnus-outgoing-do-todo)))
+@end lisp
+
+@node Wishlist/TODO
+@chapter Wishlist/TODO
+
+@itemize
+@item
+Provide a command that, when in the Org Agenda, does an email search
+for messages received in the visible date span, or day under point,
+etc. Make it work in the calendar, as well?
+@item
+Add trigger actions that create new sibling or child headings on the
+original Org heading.
+@item
+Allow tagging of Gnus messages, by giving the message's registry
+entry an `org-tags key.
+@item
+Provide persistent nngnorb search groups.
+@item
+Allow automatic org-tagging of BBDB contacts: when messages from a
+contact are associated with an Org heading, make it possible for the
+contact to inherit that heading's tags automatically.
+@item
+Provide completion when setting Org tags on a BBDB contact.
+@item
+Provide a `gnorb-bbdb-view' command that opens a *Summary* buffer
+containing all the tracked messages from the contact(s) under point.
+@item
+Provide a `gnorb-view' command that takes a tags-todo search phrase
+(or a single Org heading ID), finds all relevant messages, Org
+headings, and BBDB records, and sets up a four-pane view: Org
+Agenda, **Article* SummaryBBDB* buffer, Gnus *buffer, and an *
+buffer.
+@end itemize
+
+@node Index
+@chapter Index
+
+@c Emacs 25.0.50.8 (Org mode 8.3beta)
+@bye
\ No newline at end of file