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
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.
+You 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::
@end menu
+@node Basic Usage
+@section 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 @ref{Setup,Setup}, then do the following:
+
+@enumerate
+@item
+Add ``%ug'' somewhere appropriate in your `gnus-summary-line-format'
+variable.
+@item
+If you don't use a local archive method, add your sent message
+groups to `gnorb-gnus-sent-groups' (see the docstring).
+@item
+Use Org capture from Gnus summary buffers to create reminders for
+emails you need to reply to.
+@item
+Reply to those emails by pressing ``C-c t'' on the TODO heading in
+either the Agenda, or in regular Org files.
+@item
+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).
+@end enumerate
+
+That should be enough to get started.
+
@node Email-Related Commands
@section Email-Related Commands
`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
+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.
@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
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.
@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
+there are 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.
+doing nothing 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
+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'.
@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
+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
`gnus-group-make-nnir-group'). At the query prompt, enter an Org-style
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 ``¡''.
+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.
@node Message Attachments
@section Message Attachments
attach the files in the heading's org-attach directory to the outgoing
message.
+@node Registry Usage
+@section 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.
+
@node Likely Workflow
@section Likely Workflow
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
+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 ``¡''.
+@item `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 ``&''.
@end table
@node 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
(define-key message-mode-map (kbd "C-c t") 'gnorb-gnus-outgoing-do-todo)))
@end lisp
-@c Emacs 25.0.50.8 (Org mode 8.3beta)
-@bye
\ No newline at end of file
+@bye
+@c Local Variables:
+@c mode: texinfo
+@c TeX-master: t
+@c End: