* Misc Org::
* Misc Gnus::
* Suggested Keybindings::
-* Wishlist/TODO::
-* Index::
— The Detailed Node Listing —
Email Tracking
+* Basic Usage::
* Email-Related Commands::
* Trigger Actions::
* Viewing Tracked Messages in *Summary* Buffers::
* Hinting in Gnus::
* Message Attachments::
+* Registry Usage::
+* Likely Workflow::
Misc BBDB
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.
+can open Gnus *Summary* buffers holding all the messages associated with
+an Org subtree, and reply from there – these groups can be made
+persistent, if you like. 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:
+* Basic Usage::
* Email-Related Commands::
* Trigger Actions::
* Viewing Tracked Messages in *Summary* Buffers::
* Hinting in Gnus::
* Message Attachments::
+* Registry Usage::
+* Likely Workflow::
\1f
-File: gnorb.info, Node: Email-Related Commands, Next: Trigger Actions, Up: Email Tracking
+File: gnorb.info, Node: Basic Usage, Next: Email-Related Commands, Up: Email Tracking
+
+4.1 Basic Usage
+===============
+
+The following sections might be a bit confusing to read if you haven’t
+actually tried using Gnorb. If you don’t want to dive in all the way
+just yet, you can just dabble your toes. First set up email tracking as
+specified in *note Setup: Setup, then do the following:
+
+ 1. Add “%ug” somewhere appropriate in your ‘gnus-summary-line-format’
+ variable.
+ 2. If you don’t use a local archive method, add your sent message
+ groups to ‘gnorb-gnus-sent-groups’ (see the docstring).
+ 3. Use Org capture from Gnus summary buffers to create reminders for
+ emails you need to reply to.
+ 4. Reply to those emails by pressing “C-c t” on the TODO heading in
+ either the Agenda, or in regular Org files.
+ 5. If you ever get confused about what’s associated with an Org
+ heading, press “C-c v” on the heading (works in either the Agenda,
+ or regular Org files).
+
+ That should be enough to get started.
-4.1 Email-Related Commands
+\1f
+File: gnorb.info, Node: Email-Related Commands, Next: Trigger Actions, Prev: Basic Usage, Up: Email Tracking
+
+4.2 Email-Related Commands
==========================
Email tracking starts in one of three ways:
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
+ messages to reply to (or you call the function with a single 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
+ Calling the function with a double prefix arg will ignore all
+ associated messages and links, and compose a blank message.
+
+ Once sent, the 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-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.
+ to the message, respectively.
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.
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.
+ If you call this function with a single 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.
+
+ If you’ve called this function, and then realize you’ve associated
+ the message with the wrong TODO, call it again with a double prefix
+ to clear all associations.
It’s also possible to call this function *after* a message is sent,
in case you forgot. Gnorb saves information about the most
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.
+Message mode.
+
+ An additional convenience command is available for use in Gnus
+summary buffers: ‘gnorb-gnus-quick-reply’. If you don’t want to go
+through the whole round trip of triggering an action and then starting a
+new reply, call this command on an incoming message to associate it with
+a heading, start a reply, and associate your reply with the same
+heading.
\1f
File: gnorb.info, Node: Trigger Actions, Next: Viewing Tracked Messages in *Summary* Buffers, Prev: Email-Related Commands, Up: Email Tracking
-4.2 Trigger Actions
+4.3 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
+six 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.
+else, capturing a new Org heading as a sibling to the tracked heading,
+capturing a new Org heading as a child, 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’.
+ More actions may 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’.
\1f
File: gnorb.info, Node: Viewing Tracked Messages in *Summary* Buffers, Next: Hinting in Gnus, Prev: Trigger Actions, Up: Email Tracking
-4.3 Viewing Tracked Messages in *Summary* Buffers
+4.4 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.
+Call ‘gnorb-org-view’ on an Org heading to open an nnir summary buffer
+showing all the messages associated with that heading and child headings
+(this requires you to have added an nngnorb server to your Gnus
+backends). A minor mode is 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.
+
+ If you call ‘gnorb-org-view’ with a prefix argument, the search group
+will be made persistent across Gnus sessions. You can re-run the search
+and update the group contents by hitting “M-g” on the group in the Gnus
+*Group* buffer.
As a bonus, it’s possible to go into Gnus’ *Server* buffer, find the
line specifying your nngnorb server, and hit “G” (aka
\1f
File: gnorb.info, Node: Hinting in Gnus, Next: Message Attachments, Prev: Viewing Tracked Messages in *Summary* Buffers, Up: Email Tracking
-4.4 Hinting in Gnus
+4.5 Hinting in Gnus
===================
When you receive new mails that might be relevant to existing Org TODOs,
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
-“¡”.
+ 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 may be 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 “&” for messages that are already tracked, and “¡” for
+messages that may be relevant.
\1f
-File: gnorb.info, Node: Message Attachments, Prev: Hinting in Gnus, Up: Email Tracking
+File: gnorb.info, Node: Message Attachments, Next: Registry Usage, Prev: Hinting in Gnus, Up: Email Tracking
-4.5 Message Attachments
+4.6 Message Attachments
=======================
Gnorb simplifies the handling of attachments that you receive in emails.
attach the files in the heading’s org-attach directory to the outgoing
message.
+\1f
+File: gnorb.info, Node: Registry Usage, Next: Likely Workflow, Prev: Message Attachments, Up: Email Tracking
+
+4.7 Registry Usage
+==================
+
+You can see how many associations you’ve got stored in the registry by
+calling ‘gnorb-report-tracking-usage’. This will pop up a buffer
+showing how much of the registry you’re using, and offering keybindings
+for ‘gnorb-flush-dead-associations’, to help Gnorb clean up after
+itself.
+
+\1f
+File: gnorb.info, Node: Likely Workflow, Prev: Registry Usage, Up: Email Tracking
+
+4.8 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.
+
\1f
File: gnorb.info, Node: Restoring Window Layout, Next: Recent Mails From BBDB Contacts, Prev: Email Tracking, Up: Top
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 “¡”.
+ The mark used to indicate potentially relevant messages in the
+ Summary buffer, when ‘gnorb-gnus-summary-mark-format-letter’ is
+ present in the format line. Defaults to “¡”.
+‘`gnorb-gnus-summary-tracked-mark'’
+ The mark used to indicate already-tracked messages in the Summary
+ buffer, when ‘gnorb-gnus-summary-mark-format-letter’ is present in
+ the format line. Defaults to “&”.
\1f
-File: gnorb.info, Node: Suggested Keybindings, Next: Wishlist/TODO, Prev: Misc Gnus, Up: Top
+File: gnorb.info, Node: Suggested Keybindings, Prev: Misc Gnus, Up: Top
12 Suggested Keybindings
************************
(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)))))
+ '(progn (org-defkey org-agenda-mode-map (kbd "C-c t") 'gnorb-org-handle-mail)
+ (org-defkey org-agenda-mode-map (kbd "C-c v") 'gnorb-org-popup-bbdb)
+ (org-defkey org-agenda-mode-map (kbd "V") 'gnorb-org-view)))))
(eval-after-load "gnorb-gnus"
'(progn
'(progn
(define-key message-mode-map (kbd "C-c t") 'gnorb-gnus-outgoing-do-todo)))
-\1f
-File: gnorb.info, Node: Wishlist/TODO, Next: Index, Prev: Suggested Keybindings, Up: Top
-
-13 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, **Article* SummaryBBDB* buffer, Gnus *buffer, and an *
- buffer.
-
-\1f
-File: gnorb.info, Node: Index, Prev: Wishlist/TODO, Up: Top
-
-14 Index
-********
-
\1f
Tag Table:
Node: Top\7f194
-Node: Introduction\7f1017
-Node: Installation\7f2126
-Node: Setup\7f2540
-Node: Email Tracking\7f3907
-Node: Email-Related Commands\7f5418
-Node: Trigger Actions\7f8239
-Node: Viewing Tracked Messages in *Summary* Buffers\7f9053
-Node: Hinting in Gnus\7f10287
-Node: Message Attachments\7f11295
-Node: Restoring Window Layout\7f12453
-Node: Recent Mails From BBDB Contacts\7f12817
-Node: BBDB posting styles\7f13813
-Node: BBDB Org tagging\7f14729
-Node: Misc BBDB\7f15475
-Node: Searching for messages from BBDB contacts\7f15688
-Node: Citing BBDB contacts\7f16134
-Node: User Options\7f16455
-Node: Misc Org\7f17994
-Node: Inserting BBDB links\7f18169
-Node: User Optionsx\7f18424
-Node: Misc Gnus\7f21161
-Node: Viewing Org headlines relevant to a message\7f21374
-Node: User Optionsxx\7f21689
-Node: Suggested Keybindings\7f24453
-Node: Wishlist/TODO\7f26824
-Node: Index\7f28139
+Node: Introduction\7f1044
+Node: Installation\7f2153
+Node: Setup\7f2567
+Node: Email Tracking\7f3934
+Node: Basic Usage\7f5544
+Node: Email-Related Commands\7f6617
+Node: Trigger Actions\7f10112
+Node: Viewing Tracked Messages in *Summary* Buffers\7f11064
+Node: Hinting in Gnus\7f12551
+Node: Message Attachments\7f13647
+Node: Registry Usage\7f14828
+Node: Likely Workflow\7f15279
+Node: Restoring Window Layout\7f18079
+Node: Recent Mails From BBDB Contacts\7f18443
+Node: BBDB posting styles\7f19439
+Node: BBDB Org tagging\7f20355
+Node: Misc BBDB\7f21101
+Node: Searching for messages from BBDB contacts\7f21314
+Node: Citing BBDB contacts\7f21760
+Node: User Options\7f22081
+Node: Misc Org\7f23620
+Node: Inserting BBDB links\7f23795
+Node: User Optionsx\7f24050
+Node: Misc Gnus\7f26787
+Node: Viewing Org headlines relevant to a message\7f27000
+Node: User Optionsxx\7f27315
+Node: Suggested Keybindings\7f30322
\1f
End Tag Table