1 \input texinfo @c -*- texinfo -*-
3 @setfilename ./gnorb.info
5 @documentencoding UTF-8
12 * Gnorb: (gnorb). Glue code for Gnus, Org, and BBDB.
18 @subtitle for version 1, updated 3 October, 2014
31 * Restoring Window Layout::
32 * Recent Mails From BBDB Contacts::
33 * BBDB posting styles::
38 * Suggested Keybindings::
41 --- The Detailed Node Listing ---
45 * Email-Related Commands::
47 * Viewing Tracked Messages in *Summary* Buffers::
49 * Message Attachments::
54 * Searching for messages from BBDB contacts::
55 * Citing BBDB contacts::
60 * Inserting BBDB links::
61 * User Options: User Optionsx.
65 * Viewing Org headlines relevant to a message::
66 * User Options: User Optionsxx.
73 Gnorb provides glue code between the Gnus, Org, and BBDB packages.
74 It's aimed at supporting email-based project management, and generally
75 making it easier to keep track of email communication.
77 Much of the code consists of single-use convenience functions, but
78 tracking email conversations with Org requires is more complicated,
79 and requires a bit of setup.
81 Gnorb can be used in a modular fashion, by selectively loading the
82 files ``gnorb-org'', ``gnorb-gnus'' or ``gnorb-bbdb'' instead of plain old
83 ``gnorb''. The package as a whole is rather Org-centric, though, and it
84 won't do much of interest without ``gnorb-org''.
86 This means that Gnorb doesn't have hard requirements to any of the
87 three base libraries. For the libraries you are using, however, you'll
88 get best results from using the most recent stable version (yes, that
89 means BBDB 3). Some of the features in Gnorb only work with
90 development versions of these libraries (those cases are noted below).
95 Gnorb is best installed via the Elpa package manager -- look for it in
98 You can also clone the source code from
99 @uref{https://github.com/girzel/gnorb}, and put the ``gnorb'' directory on your
100 load-path. The Github site is also a good place to report bugs and
106 Loading ``gnorb'' will make the basic functions available. Using Gnorb
107 for email tracking takes a bit more setup, however:
111 Email tracking is done via the Gnus registry, so that must be
112 activated with `gnus-registry-initialize'.
114 It also requires the org-id package to be loaded, and
115 `org-id-track-globally' set to t (that's the default value, so
116 simply loading the package should be enough).
118 Add a nngnorb entry to your `gnus-secondary-select-methods'
119 variable. It will look like (nngnorb ``Server name''). This does
120 nothing but provide a place to hang nnir searches.
122 Then put a call to `gnorb-tracking-initialize' in your init files,
123 at some point after the Gnus registry is initialized.
125 If you're not using a local archive method for saving your sent
126 messages (ie you're using IMAP), you'll also need to tell Gnorb
127 where to find your sent messages. Set the variable
128 `gnorb-gnus-sent-groups' to a list of strings; each string should
129 indicate a fully-qualified group name, eg ``nnimap+SERVER:GROUP''.
132 Lastly, Gnorb doesn't bind any keys by default; see the @ref{Suggested Keybindings,Suggested
133 Keybindings} section below for possibilities.
136 @chapter Email Tracking
138 The most interesting thing Gnorb does is using Org headings to track
139 email conversations. This can mean anything from reminding yourself to
140 write to your mother, to conducting delicate business negotiations
141 over email, to running an email-based bug tracker.
143 Gnorb assists in this process by using the Gnus registry to track
144 correspondences between emails and Org headings -- specifically,
145 message IDs are associated with Org heading ids. As a conversation
146 develops, messages are collected on a heading (and/or its children).
147 You can compose new messages directly from the Org heading, and Gnorb
148 will automatically associate your sent message with the conversation.
149 You can open temporary Gnus *Summary* buffers holding all the messages
150 associated with an Org subtree, and reply from there. When you receive
151 new messages relevant to a conversation, Gnorb will notice them and
152 prompt you to associate them with the appropriate Org heading.
153 Attachments on incoming messages can be automatically saved as
154 attachments on Org headings, using org-attach.
156 In general, the goal is to keep track of whole conversations, reduce
157 friction when moving between Gnus and Org, and keep you in the Org
158 agenda rather than in Gnus.
160 * Email-Related Commands::
162 * Viewing Tracked Messages in *Summary* Buffers::
164 * Message Attachments::
168 @node Email-Related Commands
169 @section Email-Related Commands
171 Email tracking starts in one of three ways:
175 With an Org heading that represents an email TODO. Call
176 `gnorb-org-handle-mail' (see below) on the heading to compose a new
177 message, and start the tracking process.
179 By calling org-capture on a received message. Any heading captured
180 from a message will automatically be associated with that message.
182 By calling `gnorb-gnus-outgoing-do-todo' in a message composition
186 There are three main email-related commands:
190 `gnorb-org-handle-mail' is called on an Org heading to compose a
191 new message. By default, this will begin a reply to the most recent
192 message in the conversation. If there are no associated messages to
193 reply to (or you call the function with a double prefix arg), Gnorb
194 will look for mailto: or bbdb: links in the heading, and compose a
197 The sent message will be associated with the Org heading, and
198 you'll be brought back to the heading and asked to trigger an
201 `gnorb-email-subtree' is an alternative entry-point to
202 `gnorb-org-handle-mail'. It does the same thing as the latter, but
203 first exports the body of the subtree as either text or a file,
204 then inserts the text into the message body, or attaches the file
205 to the message, depending on what you've chosen.
207 `gnorb-gnus-incoming-do-todo' is called on a message in a Gnus
208 *Summary* buffer. You'll be prompted for an Org heading, taken to
209 that heading, and asked to trigger an action on it.
211 `gnorb-gnus-outgoing-do-todo' is called in message mode, while
212 composing a new message.
214 If called without a prefix arg, a new Org heading will be created
215 after the message is sent, and the sent message associated with it.
216 The new heading will be created as a capture heading, using the
217 template specified by the `gnorb-gnus-new-todo-capture-key' option.
219 If you call this function with a single prefix arg, you'll be
220 prompted to choose an existing Org heading instead. After the the
221 message is sent, you'll be taken to that heading and prompted to
222 trigger an action on it.
224 If you've called this function, and then realize you've associated
225 the message with the wrong TODO, call it again with a double prefix
226 to clear all associations.
228 It's also possible to call this function *after* a message is sent,
229 in case you forgot. Gnorb saves information about the most recently
230 sent message for this purpose.
233 Because these three commands all express a similar intent, but are
234 called in different modes, it can make sense to give each of them the
235 same keybinding in the keymaps for Org mode, Gnus summary mode, and
236 Message mode, respectively.
238 @node Trigger Actions
239 @section Trigger Actions
241 After calling `gnorb-gnus-incoming-do-todo' on a message, or after
242 sending a message associated with an Org heading, you'll be taken to
243 the heading and asked to ``trigger an action'' on it. At the moment
244 there are four different possibilities: triggering a TODO state-change
245 on the heading, taking a note on the heading (both these options will
246 associate the message with the heading), associating the message but
247 doing nothing else, and lastly, doing nothing at all.
249 More actions will be added in the future; it's also possible to
250 rearrange or delete existing actions, and add your own: see the
251 docstring of `gnorb-org-trigger-actions'.
253 @node Viewing Tracked Messages in *Summary* Buffers
254 @section Viewing Tracked Messages in *Summary* Buffers
256 Call `gnorb-org-view' on an Org heading to open an nnir *Summary*
257 buffer showing all the messages associated with that heading (this
258 requires that you've added an nngnorb server to your Gnus backends). A
259 minor mode will be in effect, ensuring that any replies you send to
260 messages in this buffer will automatically be associated with the
261 original Org heading. You can also invoke
262 `gnorb-summary-disassociate-message' (``C-c d'') to disassociate the
263 message with the Org heading.
265 As a bonus, it's possible to go into Gnus' *Server* buffer, find the
266 line specifying your nngnorb server, and hit ``G'' (aka
267 `gnus-group-make-nnir-group'). At the query prompt, enter an Org-style
268 tags-todo Agenda query string (eg ``+work-computer'', or what have you).
269 Gnorb will find all headings matching this query, scan their subtrees
270 for gnus links, and then give you a Summary buffer containing all the
271 linked messages. This is dog-slow at the moment; it will get faster.
273 @node Hinting in Gnus
274 @section Hinting in Gnus
276 When you receive new mails that might be relevant to existing Org
277 TODOs, Gnorb can alert you to that fact. When
278 `gnorb-gnus-hint-relevant-article' is t (the default), Gnorb will
279 display a message in the minibuffer when opening potentially relevant
280 messages. You can then use `gnorb-gnus-incoming-to-todo' to trigger an
281 action on the relevant TODO.
283 This hinting can happen in the Gnus summary buffer as well. If you use
284 the escape indicated by `gnorb-gnus-summary-mark-format-letter'' as
285 part of your `gnus-summary-line-format', articles that are relevant to
286 TODOs will be marked with a special character in the Summary buffer,
287 as determined by `gnorb-gnus-summary-mark'. By default, the format
288 letter is ``g'' (meaning it is used as ``%ug'' in the format line), and
291 @node Message Attachments
292 @section Message Attachments
294 Gnorb simplifies the handling of attachments that you receive in
295 emails. When you call `gnorb-gnus-incoming-do-todo' on a message,
296 you'll be prompted to re-attach the email's attachments onto the Org
297 heading, using the org-attach library.
299 You can also do this as part of the capture process. Set the
300 new :gnus-attachments key to ``t'' in a capture template that you use on
301 mail messages, and you'll be queried to re-attach the message's
302 attachments onto the newly-captured heading. Or set
303 `gnorb-gnus-capture-always-attach' to ``t'' to have Gnorb do this for
304 all capture templates.
306 You can also do this using the regular system of MIME commands,
307 without invoking the email tracking process. See @ref{Suggested Keybindings,Suggested
310 The same process works in reverse: when you send a message from an Org
311 heading using `gnorb-org-handle-mail', Gnorb will ask if you want to
312 attach the files in the heading's org-attach directory to the outgoing
315 @node Likely Workflow
316 @section Likely Workflow
318 You receive an email from Jimmy, who wants to rent a room in your
319 house. ``I'll respond to this later,'' you think.
321 You capture an Org TODO from the email, call it ``Jimmy renting a
322 room'', and give it a REPLY keyword. Gnorb quietly records the
323 correspondence between the email and the TODO, using the Gnus
326 The next day, looking at your Agenda, you see the TODO and decide to
327 respond to the email. You call `gnorb-org-handle-mail' on the heading,
328 and Gnorb opens Jimmy's email and starts a reply to it.
330 You tell Jimmy the room's available in March, and send the message.
331 Gnorb takes you back to the heading, and asks you to trigger an action
332 on it. You choose ``todo state'', and change the heading keyword to
335 Two days later, Jimmy replies to your message, saying that March is
336 perfect. When you open his response, Gnorb politely reminds you that
337 the message is relevant to an existing TODO. You call
338 `gnorb-gnus-incoming-do-todo' on the message, and are again taken to
339 the TODO and asked to trigger an action. Again you choose ``todo
340 state'', and change the heading keyword back to REPLY.
342 You get another email, from Samantha, warning you not to rent the room
343 to Jimmy. She even attaches a picture of a room in her house, as it
344 looked after Jimmy had stayed there for six months. It's bad. You call
345 `gnorb-gnus-incoming-do-todo' on her message, and pick the ``Jimmy
346 renting a room'' heading. This time, you choose ``take note'' as the
347 trigger action, and make a brief note about how bad that room looked.
348 Gnorb asks if you'd like to attach the picture to the Org heading. You
351 Now it's time to write to Jimmy and say something noncommittal.
352 Calling `gnorb-org-handle-mail' on the heading would respond to
353 Samantha's email, the most recent of the associated messages, which
354 isn't what you want. Instead you call `gnorb-org-view' on the heading,
355 which opens up a Gnus *Summary* buffer containing all four messages:
356 Jimmy's first, your response, his response to that, and Samantha's
357 message. You pick Jimmy's second email, and reply to it normally.
358 Gnorb asks if you'd like to send the picture of the room as an
359 attachment. You would not. When you send the reply Gnorb tracks that
360 as well, and does the ``trigger an action'' trick again.
362 In this way Gnorb helps you manage an entire conversation, possibly
363 with multiple threads and multiple participants. Mostly all you need
364 to do is call `gnorb-gnus-incoming-do-todo' on newly-received
365 messages, and `gnorb-org-handle-mail' on the heading when it's time to
368 @node Restoring Window Layout
369 @chapter Restoring Window Layout
371 Many Gnorb functions alter the window layout and value of point. In
372 most of these cases, you can restore the previous layout using the
373 interactive function `gnorb-restore-layout'.
375 @node Recent Mails From BBDB Contacts
376 @chapter Recent Mails From BBDB Contacts
378 If you're using a recent git version of BBDB (circa mid-May 2014 or
379 later), you can give your BBDB contacts a special field which will
380 collect links to recent emails from that contact. The default name of
381 the field is ``messages'', but you can customize that name using the
382 `gnorb-bbdb-messages-field' option.
384 Gnorb will not collect links by default: you need to call
385 `gnorb-bbdb-open-link' on a contact once to start the process.
386 Thereafter, opening mails from that contact will store a link to the
389 Once some links are stored, `gnorb-bbdb-open-link' will open them: Use
390 a prefix arg to the function call to select particular messages to
391 open. There are several options controlling how all this works; see
392 the gnorb-bbdb user options section below for details.
394 @node BBDB posting styles
395 @chapter BBDB posting styles
397 Gnorb comes with a BBDB posting-style system, inspired by (copied
398 from) gnus-posting-styles. You can specify how messages are composed
399 to specific contacts, by matching on contact field values (the same
400 way gnus-posting-styles matches on group names). See the docstring of
401 `gnorb-bbdb-posting-styles' for details.
403 In order not to be too intrusive, Gnorb doesn't alter the behavior of
404 `bbdb-mail', the usual mail-composition function. Instead it provides
405 an alternate `gnorb-bbdb-mail', which does exactly the same thing, but
406 first processes the new mail according to `gnorb-bbdb-posting-styles'.
407 If you want to use this feature regularly, you can remap `bbdb-mail'
408 to `gnorb-bbdb-mail' in the `bbdb-mode-map'.
410 @node BBDB Org tagging
411 @chapter BBDB Org tagging
413 BBDB contacts can be tagged with the same tags you use in your Org
414 files. This allows you to pop up a *BBDB* buffer alongside your Org
415 Agenda when searching for certain tags. This can happen automatically
416 for all Org tags-todo searches, if you set the option
417 `gnorb-org-agenda-popup-bbdb' to t. Or you can do it manually, by
418 calling the command of the same name. This command only shows TODOs by
419 default: use a prefix argument to show all tagged headings.
421 Tags are stored in an xfield named org-tags, by default. You can
422 customize the name of this field using `gnorb-bbdb-org-tag-field'.
428 * Searching for messages from BBDB contacts::
429 * Citing BBDB contacts::
433 @node Searching for messages from BBDB contacts
434 @section Searching for messages from BBDB contacts
436 Call `gnorb-bbdb-mail-search' to search for all mail messages from the
437 record(s) displayed. Currently supports the notmuch, mairix, and
438 namazu search backends; set `gnorb-gnus-mail-search-backend' to one of
441 @node Citing BBDB contacts
442 @section Citing BBDB contacts
444 Calling `gnorb-bbdb-cite-contact' will prompt for a BBDB record and
445 insert a string of the type ``Bob Smith <bob@@smith.com>''.
448 @section User Options
451 @item `gnorb-bbdb-org-tag-field
452 The name of the BBDB xfield, as a
453 symbol, that holds Org-related tags. Specified as a string with
454 the ``:'' separator between tags, same as for Org headings.
456 @item `gnorb-bbdb-messages-field'
457 The name of the BBDB xfield that
458 holds links to recently-received messages from this contact.
459 Defaults to `messages.
460 @item `gnorb-bbdb-collect-N-messages'
461 Collect at most this many links
462 to messages from this contact. Defaults to 5.
463 @item `gnorb-bbdb-define-recent'
464 What does ``recently-received'' mean?
465 Possible values are the symbols seen and received. When set to
466 seen, the most recently-opened messages are collected. When set
467 to received, the most recently-received (by Date header) messages
468 are collected. Defaults to seen.
469 @item `gnorb-bbdb-message-link-format-multi'
470 How is a single message's
471 link formatted in the multi-line BBDB layout format? Defaults to
472 ``%:count. %D: %:subject'' (see the docstring for details).
473 @item ` gnorb-bbdb-message-link-format-one'
474 How is a single message's
475 link formatted in the one-line BBDB layout format? Defaults to
476 nil (see the docstring for details).
477 @item `gnorb-bbdb-posting-styles'
478 Styles to use for influencing the
479 format of mails composed to the BBDB record(s) under point (see
480 the docstring for details).
487 * Inserting BBDB links::
488 * User Options: User Optionsx.
491 @node Inserting BBDB links
492 @section Inserting BBDB links
494 Calling `gnorb-org-contact-link' will prompt for a BBDB record and
495 insert an Org link to that record at point.
498 @section User Options
501 @item `gnorb-org-after-message-setup-hook'
502 Hook run in a message buffer
503 after setting up the message, from `gnorb-org-handle-mail' or
504 `gnorb-org-email-subtree'.
505 @item `gnorb-org-trigger-actions'
506 List of potential actions that can be
507 taken on headings after a message is sent. See docstring for
509 @item `gnorb-org-mail-scan-scope'
510 The number of paragraphs to scan for
511 mail-related links. This comes into play when calling
512 `gnorb-org-handle-mail' on a heading with no associated messages,
513 or when `gnorb-org-handle-mail' is called with a prefix arg.
514 @item `gnorb-org-find-candidates-match'
515 When searching all Org files
516 for headings to collect messages from, this option can limit
517 which headings are searched. It is used as the second argument to
518 a call to `org-map-entries', and has the same syntax as that used
519 in an agenda tags view.
520 @item `gnorb-org-email-subtree-text-parameters'
522 parameters corresponding to the EXT-PLIST argument to the export
523 functions, for use when exporting to text.
524 @item `gnorb-org-email-subtree-file-parameters'
526 parameters corresponding to the EXT-PLIST argument to the export
527 functions, for use when exporting to a file.
528 @item `gnorb-org-email-subtree-text-options'
529 A list of ts and nils
530 corresponding to Org's export options, to be used when exporting
531 to text. The options, in order, are async, subtreep,
532 visible-only, and body-only.
533 @item `gnorb-org-email-subtree-file-options'
534 A list of ts and nils
535 corresponding to Org's export options, to be used when exporting
536 to a file. The options, in order, are async, subtreep,
537 visible-only, and body-only.
538 @item `gnorb-org-export-extensions'
539 Correspondence between export
540 backends and their respective (usual) file extensions.
541 @item `gnorb-org-capture-collect-link-p'
542 When this is set to t, the
543 capture process will always store a link to the Gnus message or
544 BBDB record under point, even when the link isn't part of the
545 capture template. It can then be added to the captured heading
546 with org-insert-link, as usual.
547 @item `gnorb-org-agenda-popup-bbdb'
548 Set to ``t'' to automatically pop up
549 the BBDB buffer displaying records corresponding to the Org
550 Agenda tags search underway. If this is nil you can always do it
551 manually with the command of the same name.
552 @item `gnorb-org-bbdb-popup-layout'
553 Controls the layout of the
554 Agenda-related BBDB popup, takes the same values as
562 * Viewing Org headlines relevant to a message::
563 * User Options: User Optionsxx.
566 @node Viewing Org headlines relevant to a message
567 @section Viewing Org headlines relevant to a message
569 Call `gnorb-gnus-view' on a message that is associated with an Org
570 heading to jump to that heading.
573 @section User Options
576 @item `gnorb-gnus-mail-search-backend'
577 Specifies the search backend
578 that you use for searching mails. Currently supports notmuch,
579 mairix, and namazu: set this option to one of those symbols.
580 @item `gnorb-gnus-capture-always-attach'
581 Treat all capture templates as
582 if they had the :gnus-attachments key set to ``t''. This only has
583 any effect if you're capturing from a Gnus summary or article
585 @item `gnorb-trigger-todo-default'
586 Set to either `note or `todo to tell
587 `gnorb-gnus-incoming-do-todo' what to do by default. You can
588 reach the non-default behavior by calling that function with a
589 prefix argument. Alternately, set to `prompt to always prompt for
590 the appropriate action.
591 @item `gnorb-gnus-trigger-refile-targets'
593 `gnorb-gnus-incoming-do-todo' on an incoming message, Gnorb will
594 try to locate a TODO heading that's relevant to that message. If
595 it can't, it will prompt you for one, using the refile interface.
596 This option will be used as the value of `org-refile-targets'
597 during that process: see the docstring of `org-refile-targets'
598 for the appropriate syntax.
599 @item `gnorb-gnus-new-todo-capture-key'
600 Set this to a single-character
601 string pointing at an Org capture template to use when creating
602 TODOs from outgoing messages. The template is a regular capture
603 template, with a few exceptions. If Gnus helps you archive
604 outgoing messages (ie you have `gnus-message-archive-group' set
605 to something, and your outgoing messages have a ``Fcc'' header), a
606 link to that message will be made, and you'll be able to use all
607 the escapes related to gnus messages. If you don't archive
608 outgoing messages, you'll still be able to use the %:subject,
609 %:to, %:toname, %:toaddress, and %:date escapes in the capture
611 @item `gnorb-gnus-hint-relevant-article'
612 Set to ``t'' (the default) to
613 have Gnorb give you a hint in the minibuffer when opening
614 messages that might be relevant to existing Org TODOs.
615 @item `gnorb-gnus-summary-mark-format-letter'
616 The formatting letter to
617 use as part of your `gnus-summary-line-format', to indicate
618 messages which might be relevant to Org TODOs. Defaults to ``g'',
619 meaning it should be used as ``%ug'' in the format line.
620 @item `gnorb-gnus-summary-mark'
621 The mark used to indicate relevant
622 messages in the Summary buffer, when
623 `gnorb-gnus-summary-mark-format-letter' is present in the format
624 line. Defaults to ``¡''.
627 @node Suggested Keybindings
628 @chapter Suggested Keybindings
631 (eval-after-load "gnorb-bbdb"
633 (define-key bbdb-mode-map (kbd "O") 'gnorb-bbdb-tag-agenda)
634 (define-key bbdb-mode-map (kbd "S") 'gnorb-bbdb-mail-search)
635 (define-key bbdb-mode-map [remap bbdb-mail] 'gnorb-bbdb-mail)
636 (define-key bbdb-mode-map (kbd "l") 'gnorb-bbdb-open-link)
637 (global-set-key (kbd "C-c C") 'gnorb-bbdb-cite-contact)))
639 (eval-after-load "gnorb-org"
641 (org-defkey org-mode-map (kbd "C-c C") 'gnorb-org-contact-link)
642 (org-defkey org-mode-map (kbd "C-c t") 'gnorb-org-handle-mail)
643 (org-defkey org-mode-map (kbd "C-c e") 'gnorb-org-view)
644 (org-defkey org-mode-map (kbd "C-c E") 'gnorb-org-email-subtree)
645 (org-defkey org-mode-map (kbd "C-c V") 'gnorb-org-popup-bbdb)
646 (setq gnorb-org-agenda-popup-bbdb t)
647 (eval-after-load "org-agenda"
648 '(progn (org-defkey org-agenda-mode-map (kbd "H") 'gnorb-org-handle-mail)
649 (org-defkey org-agenda-mode-map (kbd "V") 'gnorb-org-popup-bbdb)))))
651 (eval-after-load "gnorb-gnus"
653 (define-key gnus-summary-mime-map "a" 'gnorb-gnus-article-org-attach)
654 (define-key gnus-summary-mode-map (kbd "C-c t") 'gnorb-gnus-incoming-do-todo)
655 (push '("attach to org heading" . gnorb-gnus-mime-org-attach)
656 gnus-mime-action-alist)
657 ;; The only way to add mime button command keys is by redefining
658 ;; gnus-mime-button-map, possibly not ideal. Ideal would be a
659 ;; setter function in gnus itself.
660 (push '(gnorb-gnus-mime-org-attach "a" "Attach to Org heading")
661 gnus-mime-button-commands)
662 (setq gnus-mime-button-map
663 (let ((map (make-sparse-keymap)))
664 (define-key map gnus-mouse-2 'gnus-article-push-button)
665 (define-key map gnus-down-mouse-3 'gnus-mime-button-menu)
666 (dolist (c gnus-mime-button-commands)
667 (define-key map (cadr c) (car c)))
670 (eval-after-load "message"
672 (define-key message-mode-map (kbd "C-c t") 'gnorb-gnus-outgoing-do-todo)))
675 @c Emacs 25.0.50.8 (Org mode 8.3beta)