[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] master 32329b4: Update documentation
|
From: |
Eric Abrahamsen |
|
Subject: |
[elpa] master 32329b4: Update documentation |
|
Date: |
Tue, 21 Mar 2017 15:57:32 -0400 (EDT) |
branch: master
commit 32329b477341ae634268baee9e0081acabd8b21e
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>
Update documentation
* packages/gnorb/README.org: Mention current installation situation.
* packages/gnorb/gnorb.el: Remove URL package header.
* packages/gnorb/gnorb.org: Try to do a better job of documenting
email tracking, people are still very confused by this. Also mention
the `gnorb-install-defaults' command.
* packages/gnorb/NEWS: Mention new install-defaults command.
* packages/gnorb/gnorb.texi: Export.
* packages/gnorb/gnorb.info: Export.
---
packages/gnorb/NEWS | 3 +
packages/gnorb/README.org | 14 +-
packages/gnorb/gnorb.el | 2 -
packages/gnorb/gnorb.info | 473 +++++++++++++++++++++++-----------------------
packages/gnorb/gnorb.org | 329 ++++++++++++++++----------------
packages/gnorb/gnorb.texi | 408 +++++++++++++++++++--------------------
6 files changed, 619 insertions(+), 610 deletions(-)
diff --git a/packages/gnorb/NEWS b/packages/gnorb/NEWS
index e51edd9..feca7da 100644
--- a/packages/gnorb/NEWS
+++ b/packages/gnorb/NEWS
@@ -1,5 +1,8 @@
GNU Emacs Gnorb NEWS -- history of user-visible changes. -*- org -*-
+* Version 1.2 [2017-03-21 Tue]
+** Add `gnorb-install-defaults'
+New command for installing sane default bindings.
* Version 1.1.3 [2017-03-12 Sun]
** Provide a better interface for trigger action selection
New function `gnorb-select-from-list' providing a nicer interface for
diff --git a/packages/gnorb/README.org b/packages/gnorb/README.org
index 7c45f2f..1ee55a6 100644
--- a/packages/gnorb/README.org
+++ b/packages/gnorb/README.org
@@ -43,16 +43,12 @@ you do, and you have some ideas about how it should be
handled, please
contact the author and suggest them.
** Installation
-It's easiest to install Gnorb from Elpa: run `list-packages' and look
-for it there.
+Gnorb is developed inside the Elpa repository -- install with M-x
+package-install RET gnorb RET. There is a
[[https://github.com/girzel/gnorb/][Github repository]], but the
+code there is stale as of March 2017. Any issues opened there will be
+addressed, though obviously pull requests won't work. Prefer
+submitting bugs via `emacs-report-bug'.
-Or clone the Git repo at https://github.com/girzel/gnorb, and add the
-top-level directory to your load path.
-
-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.
** Roadmap
*** More fully utilize nngnorb
Instead of just being place to put nnir searches, the nngnorb server
diff --git a/packages/gnorb/gnorb.el b/packages/gnorb/gnorb.el
index 832d798..1c61440 100644
--- a/packages/gnorb/gnorb.el
+++ b/packages/gnorb/gnorb.el
@@ -10,8 +10,6 @@
;; Author: Eric Abrahamsen <address@hidden>
;; Keywords: mail org gnus bbdb todo task
-;; URL: https://github.com/girzel/gnorb
-
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
diff --git a/packages/gnorb/gnorb.info b/packages/gnorb/gnorb.info
index 52ca072..09fc886 100644
--- a/packages/gnorb/gnorb.info
+++ b/packages/gnorb/gnorb.info
@@ -1,4 +1,4 @@
-This is gnorb.info, produced by makeinfo version 5.2 from gnorb.texi.
+This is gnorb.info, produced by makeinfo version 6.3 from gnorb.texi.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
@@ -24,35 +24,47 @@ Gnorb Manual
* Misc BBDB::
* Misc Org::
* Misc Gnus::
-* Suggested Keybindings::
+* Default Keybindings::
— The Detailed Node Listing —
+
+
+
Email Tracking
-* Basic Usage::
-* Email-Related Commands::
+* Tracking Setup::
+* Beginning and Continuing the Tracking Process::
* Trigger Actions::
-* Viewing Tracked Messages in *Summary* Buffers::
+* Viewing Things::
* Hinting in Gnus::
* Message Attachments::
* Registry Usage::
* Likely Workflow::
+
+
+
+
+
+
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.
@@ -74,6 +86,10 @@ 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”.
+ If you’ve installed from the package manager, of course, you don’t
+need ‘require’ statements at all. In that case, simply using the
+(autoloaded) functions that are of interest to you will be sufficient.
+
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
@@ -86,13 +102,12 @@ File: gnorb.info, Node: Installation, Next: Setup,
Prev: Introduction, Up: T
2 Installation
**************
-Gnorb is best installed via the Elpa package manager – look for it in
+Gnorb is installable 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.
+ An earlier version of the code is available at
+<https://github.com/girzel/gnorb>, but this is now out of date. Issues
+opened there will still be addressed, however.
File: gnorb.info, Node: Setup, Next: Email Tracking, Prev: Installation,
Up: Top
@@ -101,27 +116,11 @@ File: gnorb.info, Node: Setup, Next: Email Tracking,
Prev: Installation, Up:
*******
Loading “gnorb” will make the basic functions available. Using Gnorb
-for email tracking takes a bit more setup, however:
+for email tracking takes a bit more setup, however – see below.
- 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 *note
-Suggested Keybindings: Suggested Keybindings. section below for
-possibilities.
+ Gnorb doesn’t bind any keys by default, but you can call
+‘gnorb-install-defaults’ to do a basic installation. The rest of this
+manual assumes those *note default keybindings: Default Keybindings.
File: gnorb.info, Node: Email Tracking, Next: Restoring Window Layout,
Prev: Setup, Up: Top
@@ -130,104 +129,116 @@ File: gnorb.info, Node: Email Tracking, Next:
Restoring Window Layout, Prev:
****************
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 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.
+email conversations.
+
+ A “tracked conversation” is essentially a message thread, with
+benefits. An Org heading (and subheadings) collect messages relevant to
+the heading. You can view all the messages at once, reply to the
+most-recently-received message, collect all message attachments on the
+heading (using org-attach), and be reminded that newly-received messages
+might be relevant to the conversation. The state of the Org heading
+tracks the state of your participation in the conversation: the TODO
+keyword might switch between REPLY and WAIT, for instance, or you might
+take notes on how everything’s progressing.
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::
+* Tracking Setup::
+* Beginning and Continuing the Tracking Process::
* Trigger Actions::
-* Viewing Tracked Messages in *Summary* Buffers::
+* Viewing Things::
* Hinting in Gnus::
* Message Attachments::
* Registry Usage::
* Likely Workflow::
-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.
+File: gnorb.info, Node: Tracking Setup, Next: Beginning and Continuing the
Tracking Process, Up: Email Tracking
+
+4.1 Tracking Setup
+==================
+
+Email tracking requires the following steps:
+
+ 1. Tracking is done via the Gnus registry, so that must be activated
+ with ’gnus-registry-initialize’.
+ 2. It also depends on the org-id package, with ‘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.
+ 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”.
+ 6. Set ‘gnorb-gnus-new-todo-capture-key’ to the key of a capture
+ template you want to use for creating TODOs from sent messages.
-File: gnorb.info, Node: Email-Related Commands, Next: Trigger Actions,
Prev: Basic Usage, Up: Email Tracking
+File: gnorb.info, Node: Beginning and Continuing the Tracking Process, Next:
Trigger Actions, Prev: Tracking Setup, Up: Email Tracking
-4.2 Email-Related Commands
-==========================
+4.2 Beginning and Continuing the Tracking Process
+=================================================
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.
+ 2. By calling org-capture on a received message. Capturing from a
+ Gnus Summary buffer automatically initiates tracking.
+ 3. By calling ‘gnorb-gnus-outgoing-do-todo’ while composing a message.
+ This will create a new TODO heading after the message is sent.
+
+ After tracking begins, it is continued by using Gnorb-specific
+commands when sending and receiving email:
- There are three main email-related commands:
+ 1. When you receive an email in Gnus that should be part of a tracked
+ conversation, use ‘gnorb-gnus-incoming-to-todo’ on it to associate
+ it with the relevant Org heading.
+ 2. When it’s time to reply to that email, use ‘gnorb-org-handle-mail’
+ on the Org heading to start a reply to the thread.
- 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 single prefix
- arg), Gnorb will look for mailto: or bbdb: links in the heading,
- and compose a new message to them.
+ The default setup binds all these functions to “C-c t” in their
+respective modes, so just use that keybinding everywhere to keep the
+conversation going.
+
+ Some more detail on the various functions:
+
+ 1. ‘gnorb-org-handle-mail’ (“C-c t” in org-mode) 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
+ single prefix arg), Gnorb will look for mailto: or bbdb: links in
+ the heading, and compose a new message to them.
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-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, 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.
- 3. ‘gnorb-gnus-outgoing-do-todo’ is called in message mode, while
- composing a new message.
+ action on it. See *note Trigger Actions: Trigger Actions. for more
+ information.
+
+ ‘gnorb-email-subtree’ is an alternative 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,
+ respectively.
+ 2. ‘gnorb-gnus-incoming-do-todo’ (“C-c t” in gnus-summary-mode and
+ gnus-article-mode) 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’ (“C-c t” in message-mode) is called
+ in message mode, while composing a new message. Usually this is
+ only necessary when starting a new tracked conversation.
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.
@@ -247,11 +258,6 @@ Email tracking starts in one of three ways:
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.
-
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
@@ -260,37 +266,47 @@ a heading, start a reply, and associate your reply with
the same
heading.
-File: gnorb.info, Node: Trigger Actions, Next: Viewing Tracked Messages in
*Summary* Buffers, Prev: Email-Related Commands, Up: Email Tracking
+File: gnorb.info, Node: Trigger Actions, Next: Viewing Things, Prev:
Beginning and Continuing the Tracking Process, Up: Email Tracking
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
-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, 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.
+After receiving or sending a message in a tracked conversation, you’ll
+be taken to the relevant Org heading and asked to “trigger an action” on
+it. The main purpose of triggering is to associate the message with the
+Org heading, but the action also gives you a chance to do something
+useful like changing the TODO keyword, or leaving a note.
+
+ At the moment there are six different possibilities:
+
+ 1. Change the heading’s TODO state.
+ 2. Take a note on the heading.
+ 3. Associate the message, but do nothing else.
+ 4. Capture a new Org heading as a sibling to the tracked heading
+ 5. Capture a new Org heading as a child to the tracked heading
+ 6. Do nothing – do not associate the message.
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’.
-File: gnorb.info, Node: Viewing Tracked Messages in *Summary* Buffers, Next:
Hinting in Gnus, Prev: Trigger Actions, Up: Email Tracking
+File: gnorb.info, Node: Viewing Things, Next: Hinting in Gnus, Prev:
Trigger Actions, Up: Email Tracking
-4.4 Viewing Tracked Messages in *Summary* Buffers
-=================================================
+4.4 Viewing Things
+==================
-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
+Keeping track of a conversation is one thing, but it’s very useful to be
+able to see an overview of history and current state. For this purpose
+Gnorb provides “view” commands, which by default are bound to “C-c v” in
+all contexts.
+
+ Calling ‘gnorb-org-view’ (“C-c v”) on an Org heading will 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.
@@ -299,6 +315,9 @@ 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.
+ Calling ‘gnorb-gnus-view“ (”C-c v“) on a tracked message will take
+you to the tracked 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
@@ -308,7 +327,7 @@ 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.
-File: gnorb.info, Node: Hinting in Gnus, Next: Message Attachments, Prev:
Viewing Tracked Messages in *Summary* Buffers, Up: Email Tracking
+File: gnorb.info, Node: Hinting in Gnus, Next: Message Attachments, Prev:
Viewing Things, Up: Email Tracking
4.5 Hinting in Gnus
===================
@@ -320,14 +339,14 @@ 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
+ 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.
+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.
File: gnorb.info, Node: Message Attachments, Next: Registry Usage, Prev:
Hinting in Gnus, Up: Email Tracking
@@ -343,13 +362,15 @@ 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.
+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 *note Suggested
-Keybindings: Suggested Keybindings, below.
+without invoking the email tracking process. Using the default
+bindings, pressing “a” on a MIME line will prompt you to move the
+attachment to an Org heading.
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
@@ -382,8 +403,8 @@ 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.
+respond to the email. You hit “C-c t” on the heading, and Gnorb finds
+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
@@ -391,36 +412,34 @@ 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.
+the message is relevant to an existing TODO. You hit “C-c t” 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.
+hit “C-c t” 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.
+Hitting “C-c t” on the heading would respond to Samantha’s email, the
+most recent of the associated messages, which isn’t what you want.
+Instead you hit “C-c v” 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.
+do is hit “C-c t” on newly-received messages, and “C-c t” on the heading
+when it’s time to compose a new reply.
File: gnorb.info, Node: Restoring Window Layout, Next: Recent Mails From
BBDB Contacts, Prev: Email Tracking, Up: Top
@@ -430,7 +449,8 @@ File: gnorb.info, Node: Restoring Window Layout, Next:
Recent Mails From BBDB
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’.
+interactive function ‘gnorb-restore-layout’, by default bound to “C-c
+A”.
File: gnorb.info, Node: Recent Mails From BBDB Contacts, Next: BBDB posting
styles, Prev: Restoring Window Layout, Up: Top
@@ -534,7 +554,7 @@ File: gnorb.info, Node: User Options, Prev: Citing BBDB
contacts, Up: Misc BB
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.
+ 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.
@@ -629,29 +649,19 @@ File: gnorb.info, Node: User Optionsx, Prev: Inserting
BBDB links, Up: Misc O
same values as bbdb-pop-up-layout.
-File: gnorb.info, Node: Misc Gnus, Next: Suggested Keybindings, Prev: Misc
Org, Up: Top
+File: gnorb.info, Node: Misc Gnus, Next: Default Keybindings, Prev: Misc
Org, Up: Top
11 Misc Gnus
************
* Menu:
-* Viewing Org headlines relevant to a message::
* User Options: User Optionsxx.
-File: gnorb.info, Node: Viewing Org headlines relevant to a message, Next:
User Optionsxx, Up: Misc Gnus
-
-11.1 Viewing Org headlines relevant to a message
-================================================
+File: gnorb.info, Node: User Optionsxx, Up: Misc Gnus
-Call ‘gnorb-gnus-view’ on a message that is associated with an Org
-heading to jump to that heading.
-
-
-File: gnorb.info, Node: User Optionsxx, Prev: Viewing Org headlines relevant
to a message, Up: Misc Gnus
-
-11.2 User Options
+11.1 User Options
=================
‘`gnorb-gnus-mail-search-backend'’
@@ -663,10 +673,10 @@ File: gnorb.info, Node: User Optionsxx, Prev: Viewing
Org headlines relevant t
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’
+ 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.
+ ’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
@@ -704,86 +714,79 @@ File: gnorb.info, Node: User Optionsxx, Prev: Viewing
Org headlines relevant t
the format line. Defaults to “&”.
-File: gnorb.info, Node: Suggested Keybindings, Prev: Misc Gnus, Up: Top
+File: gnorb.info, Node: Default Keybindings, Prev: Misc Gnus, Up: Top
-12 Suggested Keybindings
-************************
+12 Default Keybindings
+**********************
+Using the bundled function ‘gnorb-install-defaults’ runs the code below.
+If you don’t like these defaults, you can always do your own setup.
+ (global-set-key (kbd "C-c A") 'gnorb-restore-layout)
(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)))
-
+ (define-key bbdb-mode-map (kbd "C-c S") #'gnorb-bbdb-mail-search)
+ (define-key bbdb-mode-map (kbd "C-c l") #'gnorb-bbdb-open-link)
+ (define-key bbdb-mode-map [remap bbdb-mail] #'gnorb-bbdb-mail)
+ (eval-after-load "gnorb-org"
+ (org-defkey org-mode-map (kbd "C-c C") #'gnorb-org-contact-link))))
(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)
+ (org-defkey org-mode-map (kbd "C-c t") #'gnorb-org-handle-mail)
+ (org-defkey org-mode-map (kbd "C-c v") #'gnorb-org-view)
+ (org-defkey org-mode-map (kbd "C-c E") #'gnorb-org-email-subtree)
(setq gnorb-org-agenda-popup-bbdb t)
(eval-after-load "org-agenda"
- '(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)))))
-
+ '(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-view)))))
(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)
+ (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)
+ (define-key gnus-summary-mode-map (kbd "C-c v") #'gnorb-gnus-view)
+ (setq gnorb-gnus-capture-always-attach t)
(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.
+ gnus-mime-action-alist)
(push '(gnorb-gnus-mime-org-attach "a" "Attach to Org heading")
- gnus-mime-button-commands)
+ 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))))
-
+ (let ((map (make-sparse-keymap)))
+ (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)))
+ (define-key message-mode-map (kbd "C-c t")
#'gnorb-gnus-outgoing-do-todo)))
Tag Table:
Node: Top194
-Node: Introduction1044
-Node: Installation2153
-Node: Setup2567
-Node: Email Tracking3934
-Node: Basic Usage5544
-Node: Email-Related Commands6617
-Node: Trigger Actions10112
-Node: Viewing Tracked Messages in *Summary* Buffers11064
-Node: Hinting in Gnus12551
-Node: Message Attachments13647
-Node: Registry Usage14828
-Node: Likely Workflow15279
-Node: Restoring Window Layout18079
-Node: Recent Mails From BBDB Contacts18443
-Node: BBDB posting styles19439
-Node: BBDB Org tagging20355
-Node: Misc BBDB21101
-Node: Searching for messages from BBDB contacts21314
-Node: Citing BBDB contacts21760
-Node: User Options22081
-Node: Misc Org23620
-Node: Inserting BBDB links23795
-Node: User Optionsx24050
-Node: Misc Gnus26787
-Node: Viewing Org headlines relevant to a message27000
-Node: User Optionsxx27315
-Node: Suggested Keybindings30322
+Node: Introduction1002
+Node: Installation2327
+Node: Setup2705
+Node: Email Tracking3158
+Node: Tracking Setup4362
+Node: Beginning and Continuing the Tracking Process5618
+Node: Trigger Actions9835
+Node: Viewing Things10909
+Node: Hinting in Gnus12679
+Node: Message Attachments13744
+Node: Registry Usage14983
+Node: Likely Workflow15434
+Node: Restoring Window Layout18105
+Node: Recent Mails From BBDB Contacts18502
+Node: BBDB posting styles19498
+Node: BBDB Org tagging20414
+Node: Misc BBDB21160
+Node: Searching for messages from BBDB contacts21373
+Node: Citing BBDB contacts21819
+Node: User Options22140
+Node: Misc Org23679
+Node: Inserting BBDB links23854
+Node: User Optionsx24109
+Node: Misc Gnus26846
+Node: User Optionsxx27009
+Node: Default Keybindings29964
End Tag Table
diff --git a/packages/gnorb/gnorb.org b/packages/gnorb/gnorb.org
index 58b0365..8baf6bf 100644
--- a/packages/gnorb/gnorb.org
+++ b/packages/gnorb/gnorb.org
@@ -1,7 +1,7 @@
#+TEXINFO_CLASS: info
#+TEXINFO_HEADER: @syncodeindex pg cp
#+TITLE: Gnorb Manual
-#+SUBTITLE: for version 1, updated 3 October, 2014
+#+SUBTITLE: for version 1, updated 13 March, 2017
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Gnorb: (gnorb)
#+TEXINFO_DIR_DESC: Glue code for Gnus, Org, and BBDB
@@ -21,123 +21,122 @@ 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".
+If you've installed from the package manager, of course, you don't
+need `require' statements at all. In that case, simply using the
+(autoloaded) functions that are of interest to you will be sufficient.
+
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
+Gnorb is installable 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.
+An earlier version of the code is available at
+https://github.com/girzel/gnorb, but this is now out of date. Issues
+opened there will still be addressed, however.
* Setup
:PROPERTIES:
:ID: 9da59609-bb3c-4970-88f6-bddca18d2ad4
:END:
Loading "gnorb" will make the basic functions available. Using Gnorb
-for email tracking takes a bit more setup, however:
+for email tracking takes a bit more setup, however -- see below.
+
+Gnorb doesn't bind any keys by default, but you can call
+`gnorb-install-defaults' to do a basic installation. The rest of this
+manual assumes those [[id:de1b2579-86c2-4bb1-b77e-3467a3d2b3c7][default
keybindings]].
+* Email Tracking
+The most interesting thing Gnorb does is using Org headings to track
+email conversations.
+
+A "tracked conversation" is essentially a message thread, with
+benefits. An Org heading (and subheadings) collect messages relevant
+to the heading. You can view all the messages at once, reply to the
+most-recently-received message, collect all message attachments on the
+heading (using org-attach), and be reminded that newly-received
+messages might be relevant to the conversation. The state of the Org
+heading tracks the state of your participation in the conversation:
+the TODO keyword might switch between REPLY and WAIT, for instance, or
+you might take notes on how everything's progressing.
+
+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.
+** Tracking Setup
-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).
+Email tracking requires the following steps:
+
+1. Tracking is done via the Gnus registry, so that must be activated
+ with 'gnus-registry-initialize'.
+2. It also depends on the org-id package, with `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.
+4. Then put a call to `gnorb-tracking-initialize' in your init files.
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".
+6. Set `gnorb-gnus-new-todo-capture-key' to the key of a capture
+ template you want to use for creating TODOs from sent messages.
-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 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.
-** 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 [[id:9da59609-bb3c-4970-88f6-bddca18d2ad4][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.
-** Email-Related Commands
+** Beginning and Continuing the Tracking Process
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.
+2. By calling org-capture on a received message. Capturing from a Gnus
+ Summary buffer automatically initiates tracking.
+3. By calling `gnorb-gnus-outgoing-do-todo' while composing a message.
+ This will create a new TODO heading after the message is sent.
+
+After tracking begins, it is continued by using Gnorb-specific
+commands when sending and receiving email:
-There are three main email-related commands:
+1. When you receive an email in Gnus that should be part of a tracked
+ conversation, use `gnorb-gnus-incoming-to-todo' on it to associate
+ it with the relevant Org heading.
+2. When it's time to reply to that email, use `gnorb-org-handle-mail'
+ on the Org heading to start a reply to the thread.
-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 single prefix arg), Gnorb
- will look for mailto: or bbdb: links in the heading, and compose a
- new message to them.
+The default setup binds all these functions to "C-c t" in their
+respective modes, so just use that keybinding everywhere to keep the
+conversation going.
+
+Some more detail on the various functions:
+
+1. `gnorb-org-handle-mail' ("C-c t" in org-mode) 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
+ single prefix arg), Gnorb will look for mailto: or bbdb: links in
+ the heading, and compose a new message to them.
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.
+ action on it. See [[id:6bc4a833-e16a-4538-a675-b8ff21c9345d][Trigger
Actions]] for more information.
- `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, 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.
-3. `gnorb-gnus-outgoing-do-todo' is called in message mode, while
- composing a new message.
+ `gnorb-email-subtree' is an alternative 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,
+ respectively.
+2. `gnorb-gnus-incoming-do-todo' ("C-c t" in gnus-summary-mode and
+ gnus-article-mode) 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' ("C-c t" in message-mode) is called
+ in message mode, while composing a new message. Usually this is
+ only necessary when starting a new tracked conversation.
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.
@@ -157,11 +156,6 @@ There are three main email-related commands:
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.
-
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
@@ -169,28 +163,42 @@ 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.
** 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 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, 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.
+:PROPERTIES:
+:ID: 6bc4a833-e16a-4538-a675-b8ff21c9345d
+:END:
+After receiving or sending a message in a tracked conversation, you'll
+be taken to the relevant Org heading and asked to "trigger an action"
+on it. The main purpose of triggering is to associate the message with
+the Org heading, but the action also gives you a chance to do
+something useful like changing the TODO keyword, or leaving a note.
+
+At the moment there are six different possibilities:
+
+1. Change the heading's TODO state.
+2. Take a note on the heading.
+3. Associate the message, but do nothing else.
+4. Capture a new Org heading as a sibling to the tracked heading
+5. Capture a new Org heading as a child to the tracked heading
+6. Do nothing -- do not associate the message.
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'.
-** Viewing Tracked Messages in *Summary* Buffers
+** Viewing Things
:PROPERTIES:
:END:
-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
+
+Keeping track of a conversation is one thing, but it's very useful to
+be able to see an overview of history and current state. For this
+purpose Gnorb provides "view" commands, which by default are bound to
+"C-c v" in all contexts.
+
+Calling `gnorb-org-view' ("C-c v") on an Org heading will 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.
@@ -199,6 +207,9 @@ 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.
+Calling `gnorb-gnus-view" ("C-c v") on a tracked message will take you
+to the tracked 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
@@ -218,7 +229,7 @@ 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
+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
@@ -236,13 +247,15 @@ 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.
+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.
+without invoking the email tracking process. Using the default
+bindings, pressing "a" on a MIME line will prompt you to move the
+attachment to an Org heading.
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
@@ -264,8 +277,8 @@ 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.
+respond to the email. You hit "C-c t" on the heading, and Gnorb finds
+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
@@ -274,40 +287,39 @@ 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.
+the message is relevant to an existing TODO. You hit "C-c t" 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.
+looked after Jimmy had stayed there for six months. It's bad. You hit
+"C-c t" 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.
+Hitting "C-c t" on the heading would respond to Samantha's email, the
+most recent of the associated messages, which isn't what you want.
+Instead you hit "C-c v" 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.
+to do is hit "C-c t" on newly-received messages, and "C-c t" 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'.
+interactive function `gnorb-restore-layout', by default bound to "C-c
+A".
* Recent Mails From BBDB Contacts
:PROPERTIES:
@@ -441,11 +453,6 @@ insert an Org link to that record at point.
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,
@@ -492,52 +499,46 @@ heading to jump to that heading.
already-tracked messages in the Summary buffer, when
`gnorb-gnus-summary-mark-format-letter' is present in the format
line. Defaults to "&".
-* Suggested Keybindings
+* Default Keybindings
:PROPERTIES:
:ID: de1b2579-86c2-4bb1-b77e-3467a3d2b3c7
:END:
+Using the bundled function `gnorb-install-defaults' runs the code
+below. If you don't like these defaults, you can always do your own setup.
#+BEGIN_SRC emacs-lisp
+ (global-set-key (kbd "C-c A") 'gnorb-restore-layout)
(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)))
-
+ (define-key bbdb-mode-map (kbd "C-c S") #'gnorb-bbdb-mail-search)
+ (define-key bbdb-mode-map (kbd "C-c l") #'gnorb-bbdb-open-link)
+ (define-key bbdb-mode-map [remap bbdb-mail] #'gnorb-bbdb-mail)
+ (eval-after-load "gnorb-org"
+ (org-defkey org-mode-map (kbd "C-c C") #'gnorb-org-contact-link))))
(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)
+ (org-defkey org-mode-map (kbd "C-c t") #'gnorb-org-handle-mail)
+ (org-defkey org-mode-map (kbd "C-c v") #'gnorb-org-view)
+ (org-defkey org-mode-map (kbd "C-c E") #'gnorb-org-email-subtree)
(setq gnorb-org-agenda-popup-bbdb t)
(eval-after-load "org-agenda"
- '(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)))))
-
+ '(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-view)))))
(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)
+ (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)
+ (define-key gnus-summary-mode-map (kbd "C-c v") #'gnorb-gnus-view)
+ (setq gnorb-gnus-capture-always-attach t)
(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)))
+ (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)))
+ (define-key message-mode-map (kbd "C-c t")
#'gnorb-gnus-outgoing-do-todo)))
#+END_SRC
diff --git a/packages/gnorb/gnorb.texi b/packages/gnorb/gnorb.texi
index cdd7576..035a870 100644
--- a/packages/gnorb/gnorb.texi
+++ b/packages/gnorb/gnorb.texi
@@ -15,7 +15,7 @@
@finalout
@titlepage
@title Gnorb Manual
address@hidden for version 1, updated 3 October, 2014
address@hidden for version 1, updated 13 March, 2017
@end titlepage
@ifnottex
@@ -35,36 +35,48 @@
* Misc BBDB::
* Misc Org::
* Misc Gnus::
-* Suggested Keybindings::
+* Default Keybindings::
@detailmenu
--- The Detailed Node Listing ---
+
+
+
Email Tracking
-* Basic Usage::
-* Email-Related Commands::
+* Tracking Setup::
+* Beginning and Continuing the Tracking Process::
* Trigger Actions::
-* Viewing Tracked Messages in *Summary* Buffers::
+* Viewing Things::
* Hinting in Gnus::
* Message Attachments::
* Registry Usage::
* Likely Workflow::
+
+
+
+
+
+
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
@@ -85,6 +97,10 @@ 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''.
+If you've installed from the package manager, of course, you don't
+need `require' statements at all. In that case, simply using the
+(autoloaded) functions that are of interest to you will be sufficient.
+
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
@@ -94,113 +110,86 @@ 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
+Gnorb is installable via the Elpa package manager -- look for it in
`list-packages'.
-You can also clone the source code from
address@hidden://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.
+An earlier version of the code is available at
address@hidden://github.com/girzel/gnorb}, but this is now out of date. Issues
+opened there will still be addressed, however.
@node Setup
@chapter Setup
Loading ``gnorb'' will make the basic functions available. Using Gnorb
-for email tracking takes a bit more setup, however:
-
address@hidden
address@hidden
-Email tracking is done via the Gnus registry, so that must be
-activated with `gnus-registry-initialize'.
address@hidden
-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).
address@hidden
-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.
address@hidden
-Then put a call to `gnorb-tracking-initialize' in your init files,
-at some point after the Gnus registry is initialized.
address@hidden
-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''.
address@hidden enumerate
+for email tracking takes a bit more setup, however -- see below.
-Lastly, Gnorb doesn't bind any keys by default; see the @ref{Suggested
Keybindings,Suggested
-Keybindings} section below for possibilities.
+Gnorb doesn't bind any keys by default, but you can call
+`gnorb-install-defaults' to do a basic installation. The rest of this
+manual assumes those @ref{Default Keybindings,default keybindings}.
@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 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.
+email conversations.
+
+A ``tracked conversation'' is essentially a message thread, with
+benefits. An Org heading (and subheadings) collect messages relevant
+to the heading. You can view all the messages at once, reply to the
+most-recently-received message, collect all message attachments on the
+heading (using org-attach), and be reminded that newly-received
+messages might be relevant to the conversation. The state of the Org
+heading tracks the state of your participation in the conversation:
+the TODO keyword might switch between REPLY and WAIT, for instance, or
+you might take notes on how everything's progressing.
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::
+* Tracking Setup::
+* Beginning and Continuing the Tracking Process::
* Trigger Actions::
-* Viewing Tracked Messages in *Summary* Buffers::
+* Viewing Things::
* Hinting in Gnus::
* Message Attachments::
* Registry Usage::
* Likely Workflow::
@end menu
address@hidden Basic Usage
address@hidden Basic Usage
address@hidden Tracking Setup
address@hidden Tracking Setup
-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:
+Email tracking requires the following steps:
@enumerate
@item
-Add ``%ug'' somewhere appropriate in your `gnus-summary-line-format'
-variable.
+Tracking is done via the Gnus registry, so that must be activated
+with 'gnus-registry-initialize'.
@item
-If you don't use a local archive method, add your sent message
-groups to `gnorb-gnus-sent-groups' (see the docstring).
+It also depends on the org-id package, with `org-id-track-globally'
+set to t (that's the default value, so simply loading the package
+should be enough).
@item
-Use Org capture from Gnus summary buffers to create reminders for
-emails you need to reply to.
+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
-Reply to those emails by pressing ``C-c t'' on the TODO heading in
-either the Agenda, or in regular Org files.
+Then put a call to `gnorb-tracking-initialize' in your init 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).
+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''.
address@hidden
+Set `gnorb-gnus-new-todo-capture-key' to the key of a capture
+template you want to use for creating TODOs from sent messages.
@end enumerate
-That should be enough to get started.
-
address@hidden Email-Related Commands
address@hidden Email-Related Commands
address@hidden Beginning and Continuing the Tracking Process
address@hidden Beginning and Continuing the Tracking Process
Email tracking starts in one of three ways:
@@ -210,43 +199,62 @@ 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.
+By calling org-capture on a received message. Capturing from a Gnus
+Summary buffer automatically initiates tracking.
@item
-By calling `gnorb-gnus-outgoing-do-todo' in a message composition
-buffer -- see below.
+By calling `gnorb-gnus-outgoing-do-todo' while composing a message.
+This will create a new TODO heading after the message is sent.
@end enumerate
-There are three main email-related commands:
+After tracking begins, it is continued by using Gnorb-specific
+commands when sending and receiving email:
@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 single prefix arg), Gnorb
-will look for mailto: or bbdb: links in the heading, and compose a
-new message to them.
+When you receive an email in Gnus that should be part of a tracked
+conversation, use `gnorb-gnus-incoming-to-todo' on it to associate
+it with the relevant Org heading.
address@hidden
+When it's time to reply to that email, use `gnorb-org-handle-mail'
+on the Org heading to start a reply to the thread.
address@hidden enumerate
+
+The default setup binds all these functions to ``C-c t'' in their
+respective modes, so just use that keybinding everywhere to keep the
+conversation going.
+
+Some more detail on the various functions:
+
address@hidden
address@hidden
+`gnorb-org-handle-mail' (``C-c t'' in org-mode) 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
+single prefix arg), Gnorb will look for mailto: or bbdb: links in
+the heading, and compose a new message to them.
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.
+action on it. See @ref{Trigger Actions,Trigger Actions} for more information.
-`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, respectively.
+`gnorb-email-subtree' is an alternative 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,
+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
-that heading, and asked to trigger an action on it.
+`gnorb-gnus-incoming-do-todo' (``C-c t'' in gnus-summary-mode and
+gnus-article-mode) 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.
+`gnorb-gnus-outgoing-do-todo' (``C-c t'' in message-mode) is called
+in message mode, while composing a new message. Usually this is
+only necessary when starting a new tracked conversation.
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.
@@ -267,11 +275,6 @@ 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.
-
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
@@ -282,29 +285,47 @@ 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 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, 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.
+After receiving or sending a message in a tracked conversation, you'll
+be taken to the relevant Org heading and asked to ``trigger an action''
+on it. The main purpose of triggering is to associate the message with
+the Org heading, but the action also gives you a chance to do
+something useful like changing the TODO keyword, or leaving a note.
+
+At the moment there are six different possibilities:
+
address@hidden
address@hidden
+Change the heading's TODO state.
address@hidden
+Take a note on the heading.
address@hidden
+Associate the message, but do nothing else.
address@hidden
+Capture a new Org heading as a sibling to the tracked heading
address@hidden
+Capture a new Org heading as a child to the tracked heading
address@hidden
+Do nothing -- do not associate the message.
address@hidden enumerate
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'.
address@hidden Viewing Tracked Messages in *Summary* Buffers
address@hidden Viewing Tracked Messages in *Summary* Buffers
address@hidden Viewing Things
address@hidden Viewing Things
-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
+Keeping track of a conversation is one thing, but it's very useful to
+be able to see an overview of history and current state. For this
+purpose Gnorb provides ``view'' commands, which by default are bound to
+``C-c v'' in all contexts.
+
+Calling `gnorb-org-view' (``C-c v'') on an Org heading will 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.
@@ -313,6 +334,9 @@ 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.
+Calling `gnorb-gnus-view`` (''C-c v``) on a tracked message will take you
+to the tracked 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
@@ -332,7 +356,7 @@ 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
+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
@@ -351,13 +375,15 @@ 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.
+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.
+without invoking the email tracking process. Using the default
+bindings, pressing ``a'' on a MIME line will prompt you to move the
+attachment to an Org heading.
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
@@ -385,8 +411,8 @@ 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.
+respond to the email. You hit ``C-c t'' on the heading, and Gnorb finds
+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
@@ -395,43 +421,42 @@ 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.
+the message is relevant to an existing TODO. You hit ``C-c t'' 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.
+looked after Jimmy had stayed there for six months. It's bad. You hit
+``C-c t'' 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.
+Hitting ``C-c t'' on the heading would respond to Samantha's email, the
+most recent of the associated messages, which isn't what you want.
+Instead you hit ``C-c v'' 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.
+to do is hit ``C-c t'' on newly-received messages, and ``C-c t'' on the
+heading when it's time to compose a new reply.
@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'.
+interactive function `gnorb-restore-layout', by default bound to ``C-c
+A''.
@node Recent Mails From BBDB Contacts
@chapter Recent Mails From BBDB Contacts
@@ -517,7 +542,7 @@ 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.
+Defaults to 'messages.
@item `gnorb-bbdb-collect-N-messages'
Collect at most this many links
to messages from this contact. Defaults to 5.
@@ -620,16 +645,9 @@ bbdb-pop-up-layout.
@chapter Misc Gnus
@menu
-* Viewing Org headlines relevant to a message::
* User Options: User Optionsxx.
@end menu
address@hidden Viewing Org headlines relevant to a message
address@hidden 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
@@ -644,10 +662,10 @@ 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
+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
+prefix argument. Alternately, set to 'prompt to always prompt for
the appropriate action.
@item `gnorb-gnus-trigger-refile-targets'
If you use
@@ -690,57 +708,47 @@ already-tracked messages in the Summary buffer, when
line. Defaults to ``&''.
@end table
address@hidden Suggested Keybindings
address@hidden Suggested Keybindings
address@hidden Default Keybindings
address@hidden Default Keybindings
+Using the bundled function `gnorb-install-defaults' runs the code
+below. If you don't like these defaults, you can always do your own setup.
@lisp
+(global-set-key (kbd "C-c A") 'gnorb-restore-layout)
(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)))
-
+ (define-key bbdb-mode-map (kbd "C-c S") #'gnorb-bbdb-mail-search)
+ (define-key bbdb-mode-map (kbd "C-c l") #'gnorb-bbdb-open-link)
+ (define-key bbdb-mode-map [remap bbdb-mail] #'gnorb-bbdb-mail)
+ (eval-after-load "gnorb-org"
+ (org-defkey org-mode-map (kbd "C-c C") #'gnorb-org-contact-link))))
(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)
+ (org-defkey org-mode-map (kbd "C-c t") #'gnorb-org-handle-mail)
+ (org-defkey org-mode-map (kbd "C-c v") #'gnorb-org-view)
+ (org-defkey org-mode-map (kbd "C-c E") #'gnorb-org-email-subtree)
(setq gnorb-org-agenda-popup-bbdb t)
(eval-after-load "org-agenda"
- '(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)))))
-
+ '(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-view)))))
(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)
+ (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)
+ (define-key gnus-summary-mode-map (kbd "C-c v") #'gnorb-gnus-view)
+ (setq gnorb-gnus-capture-always-attach t)
(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.
+ gnus-mime-action-alist)
(push '(gnorb-gnus-mime-org-attach "a" "Attach to Org heading")
- gnus-mime-button-commands)
+ 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))))
-
+ (let ((map (make-sparse-keymap)))
+ (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)))
+ (define-key message-mode-map (kbd "C-c t")
#'gnorb-gnus-outgoing-do-todo)))
@end lisp
address@hidden
address@hidden Local Variables:
address@hidden mode: texinfo
address@hidden TeX-master: t
address@hidden End:
address@hidden
\ No newline at end of file
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [elpa] master 32329b4: Update documentation,
Eric Abrahamsen <=