\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename gnorb.info
@settitle Gnorb Manual
@documentencoding UTF-8
@documentlanguage en
@syncodeindex pg cp
@c %**end of header

@dircategory Emacs
@direntry
* Gnorb: (gnorb).       Glue code for Gnus, Org, and BBDB.
@end direntry

@finalout
@titlepage
@title Gnorb Manual
@subtitle for version 1, updated 13 March, 2017
@end titlepage

@ifnottex
@node Top
@top Gnorb Manual
@end ifnottex

@menu
* Introduction::
* Installation::
* Setup::
* Email Tracking::
* Restoring Window Layout::
* Recent Mails From BBDB Contacts::
* Tagging Messages and Contacts::
* BBDB posting styles::
* Misc BBDB::
* Misc Org::
* Misc Gnus::
* Default Keybindings::

@detailmenu
--- The Detailed Node Listing ---

Email Tracking

* Likely Workflow::
* Tracking Setup::
* Beginning and Continuing the Tracking Process::
* Trigger Actions::
* Viewing Things::
* Hinting in Gnus::
* Message Attachments::
* Registry Usage::

Misc BBDB

* Searching for messages from BBDB contacts::
* Citing BBDB contacts::
* User Options::

Misc Org

* Inserting BBDB links::
* User Options: User Options 1.

Misc Gnus

* Searching With the Registry::
* User Options: User Options 2.

@end detailmenu
@end menu

@node Introduction
@chapter Introduction

Gnorb provides glue code between the Gnus, Org, and BBDB packages.
It's aimed at supporting email-based project management, and generally
making it easier to keep track of email communication.

Much of the code consists of single-use convenience functions, but
tracking email conversations with Org requires is more complicated,
and requires a bit of setup.

Gnorb can be used in a modular fashion, by selectively loading the
files ``gnorb-org'', ``gnorb-gnus'' or ``gnorb-bbdb'' instead of plain old
``gnorb''. The package as a whole is rather Org-centric, though, and it
won't do much of interest without ``gnorb-org''.

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).

@node Installation
@chapter Installation

Gnorb is installable via the Elpa package manager -- look for it in
`list-packages'.

An earlier version of the code is available at
@uref{https://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 -- 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 @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.

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
* Likely Workflow::
* Tracking Setup::
* Beginning and Continuing the Tracking Process::
* Trigger Actions::
* Viewing Things::
* Hinting in Gnus::
* Message Attachments::
* Registry Usage::
@end menu

@node Likely Workflow
@section Likely Workflow

First of all, here's a hypothetical workflow to show you how tracking
works.

Say you receive an email from Jimmy, who wants to rent a room in your
house. ``I'll respond to this later,'' you think.

You capture an Org TODO from the email, writing a headline ``Jimmy
renting a room'', and give it a REPLY keyword. Gnorb quietly records
the correspondence between the email and the TODO, using the Gnus
registry.

The next day, looking at your Agenda, you see the TODO and decide to
respond to the email. You 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
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 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 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.
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 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 Tracking Setup
@section Tracking Setup

Email tracking requires the following steps:

@enumerate
@item
Tracking is done via the Gnus registry, so that must be activated
with 'gnus-registry-initialize'.
@item
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
Add a nngnorb entry to your `gnus-secondary-select-methods'
variable. It will look like (nngnorb ``Server name''). This does
nothing but provide a place to hang nnir searches.
@item
Then put a call to `gnorb-tracking-initialize' in your init files.
@item
If you're not using a local archive method for saving your sent
messages (ie you're using IMAP), you'll also need to tell Gnorb
where to find your sent messages. Set the variable
`gnorb-gnus-sent-groups' to a list of strings; each string should
indicate a fully-qualified group name, eg ``nnimap+SERVER:GROUP''.
@item
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

@node Beginning and Continuing the Tracking Process
@section Beginning and Continuing the Tracking Process

Email tracking starts in one of three ways:

@enumerate
@item
With an Org heading that represents an email TODO. Call
`gnorb-org-handle-mail' (see below) on the heading to compose a new
message, and start the tracking process.
@item
By calling org-capture on a received message. Capturing from a Gnus
Summary buffer automatically initiates tracking.
@item
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

After tracking begins, it is continued by using Gnorb-specific
commands when sending and receiving email:

@enumerate
@item
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.
@item
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.
@end 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:

@enumerate
@item
`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. See @ref{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.
@item
`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' (``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.
The new heading will be created as a capture heading, using the
template specified by the `gnorb-gnus-new-todo-capture-key' option.

If you call this function with a single prefix arg, you'll be
prompted to choose an existing Org heading instead. After the
message is sent, you'll be taken to that heading and prompted to
trigger an action on it.

If you've called this function, and then realize you've associated
the message with the wrong TODO, call it again with a double prefix
to clear all associations.

It's also possible to call this function *after* a message is sent,
in case you forgot. Gnorb saves information about the most recently
sent message for this purpose.
@end enumerate

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 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:

@enumerate
@item
Change the heading's TODO state.
@item
Take a note on the heading.
@item
Associate the message, but do nothing else.
@item
Capture a new Org heading as a sibling to the tracked heading
@item
Capture a new Org heading as a child to the tracked heading
@item
Do nothing -- do not associate the message.
@end 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'.

@node Viewing Things
@section Viewing Things

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.

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.

Calling `gnorb-gnus-view' (``C-c v'') on a tracked message will take you
to the tracked Org heading.

From a Gnus *Summary* buffer, you can insert all tracked messages in
the current group into the buffer with
`gnorb-gnus-insert-tracked-messages', bound to ``/ G'' in the default
keybindings. By default this will only insert messages associated with
headings that are not in a DONE state; call with a prefix arg to
insert all messages.

As a bonus, it's possible to go into Gnus' *Server* buffer, find the
line specifying your nngnorb server, and hit ``G'' (aka
`gnus-group-make-nnir-group'). At the query prompt, enter an Org-style
tags-todo Agenda query string (eg ``+work-computer'', or what have you).
Gnorb will find all headings matching this query, scan their subtrees
for gnus links, and then give you a Summary buffer containing all the
linked messages. This is dog-slow at the moment; it will get faster.

@node Hinting in Gnus
@section Hinting in Gnus

When you receive new mails that might be relevant to existing Org
TODOs, Gnorb can alert you to that fact. When
`gnorb-gnus-hint-relevant-article' is t (the default), Gnorb will
display a message in the minibuffer when opening potentially relevant
messages. You can then use `gnorb-gnus-incoming-to-todo' to trigger an
action on the relevant TODO.

This hinting can happen in the Gnus summary buffer as well. If you use
the escape indicated by `gnorb-gnus-summary-mark-format-letter' as
part of your `gnus-summary-line-format', articles that 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

Gnorb simplifies the handling of attachments that you receive in
emails. When you call `gnorb-gnus-incoming-do-todo' on a message,
you'll be prompted to re-attach the email's attachments onto the Org
heading, using the org-attach library.

You can also do this as part of the capture process. Set the
new :gnus-attachments key to ``t'' in a capture template that you use on
mail messages, and you'll be queried to re-attach the message's
attachments onto the newly-captured heading.

Or set `gnorb-gnus-capture-always-attach' to ``t'' to have Gnorb do this
for all capture templates.

You can also do this using the regular system of MIME commands,
without invoking the email tracking process. 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
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 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', by default bound to ``C-c
A''.

@node Recent Mails From BBDB Contacts
@chapter Recent Mails From BBDB Contacts

If you're using a recent git version of BBDB (circa mid-May 2014 or
later), you can give your BBDB contacts a special field which will
collect links to recent emails from that contact. The default name of
the field is ``messages'', but you can customize that name using the
`gnorb-bbdb-messages-field' option.

Gnorb will not collect links by default: you need to call
`gnorb-bbdb-open-link' on a contact once to start the process.
Thereafter, opening mails from that contact will store a link to the
message.

Once some links are stored, `gnorb-bbdb-open-link' will open them: Use
a prefix arg to the function call to select particular messages to
open. There are several options controlling how all this works; see
the gnorb-bbdb user options section below for details.

@node Tagging Messages and Contacts
@chapter Tagging Messages and Contacts

It's possible to use your defined Org tags to tag BBDB contacts and
Gnus messages.

For BBDB contacts, tags are stored in an xfield named org-tags, by
default (you can customize the name of this field using the
`gnorb-bbdb-org-tag-field' option). Once contacts are tagged, you can
search for tags normally in the *BBDB* buffer. You can also pop up a
*BBDB* buffer alongside an Org Agenda tags search, with contacts
matching the search terms. You can have this happen automatically, by
setting `gnorb-org-agenda-popup-bbdb' to a non-nil value, or do it
manually by calling `gnorb-org-popup-bbdb'.

Gnus messages can be tagged from a *Summary* buffer using the command
`gnorb-gnus-tag-message' (bound to ``C-c C-t'' when using the default
keybindings). You can also search for tagged messages in a group using
`gnorb-gnus-insert-tagged-messages' (bound to ``/ g'' when using the
default keybindings). The search string can be given as a more complex
tags expression a la Org Agenda searches, ie ``cat|bird-dog''.

If the option `gnorb-gnus-auto-tag-messages' is non-nil, any time you
trigger an Org heading from a Gnus message, the message will ``inherit''
the tags of the Org heading.

You can view Org tags on Gnus messages by adding the ``%uG'' spec code
to your `gnus-group-line-format' value. That spec code can be
customized using the `gnorb-gnus-summary-tags-format-letter' option.

@node BBDB posting styles
@chapter BBDB posting styles

Gnorb comes with a BBDB posting-style system, inspired by (copied
from) gnus-posting-styles. You can specify how messages are composed
to specific contacts, by matching on contact field values (the same
way gnus-posting-styles matches on group names). See the docstring of
`gnorb-bbdb-posting-styles' for details.

In order not to be too intrusive, Gnorb doesn't alter the behavior of
`bbdb-mail', the usual mail-composition function. Instead it provides
an alternate `gnorb-bbdb-mail', which does exactly the same thing, but
first processes the new mail according to `gnorb-bbdb-posting-styles'.
If you want to use this feature regularly, you can remap `bbdb-mail'
to `gnorb-bbdb-mail' in the `bbdb-mode-map'.

@node Misc BBDB
@chapter Misc BBDB

@menu
* Searching for messages from BBDB contacts::
* Citing BBDB contacts::
* User Options::
@end menu

@node Searching for messages from BBDB contacts
@section Searching for messages from BBDB contacts

Call `gnorb-bbdb-mail-search' to search for all mail messages from the
record(s) displayed. Currently supports the notmuch, mairix, and
namazu search backends; set `gnorb-gnus-mail-search-backend' to one of
those symbol values.

@node Citing BBDB contacts
@section Citing BBDB contacts

Calling `gnorb-bbdb-cite-contact' will prompt for a BBDB record and
insert a string of the type ``Bob Smith <bob@@smith.com>''.

@node User Options
@section User Options

@table @asis
@item `gnorb-bbdb-org-tag-field
The name of the BBDB xfield, as a
symbol, that holds Org-related tags. Specified as a string with
the ``:'' separator between tags, same as for Org headings.
Defaults to org-tag.
@item `gnorb-bbdb-messages-field'
The name of the BBDB xfield that
holds links to recently-received messages from this contact.
Defaults to 'messages.
@item `gnorb-bbdb-collect-N-messages'
Collect at most this many links
to messages from this contact. Defaults to 5.
@item `gnorb-bbdb-define-recent'
What does ``recently-received'' mean?
Possible values are the symbols seen and received. When set to
seen, the most recently-opened messages are collected. When set
to received, the most recently-received (by Date header) messages
are collected. Defaults to seen.
@item `gnorb-bbdb-message-link-format-multi'
How is a single message's
link formatted in the multi-line BBDB layout format? Defaults to
``%:count. %D: %:subject'' (see the docstring for details).
@item ` gnorb-bbdb-message-link-format-one'
How is a single message's
link formatted in the one-line BBDB layout format? Defaults to
nil (see the docstring for details).
@item `gnorb-bbdb-posting-styles'
Styles to use for influencing the
format of mails composed to the BBDB record(s) under point (see
the docstring for details).
@end table

@node Misc Org
@chapter Misc Org

@menu
* Inserting BBDB links::
* User Options: User Options 1.
@end menu

@node Inserting BBDB links
@section Inserting BBDB links

Calling `gnorb-org-contact-link' will prompt for a BBDB record and
insert an Org link to that record at point.

@node User Options 1
@section User Options

@table @asis
@item `gnorb-org-after-message-setup-hook'
Hook run in a message buffer
after setting up the message, from `gnorb-org-handle-mail' or
`gnorb-org-email-subtree'.
@item `gnorb-org-trigger-actions'
List of potential actions that can be
taken on headings after a message is sent. See docstring for
details.
@item `gnorb-org-mail-scan-scope'
The number of paragraphs to scan for
mail-related links. This comes into play when calling
`gnorb-org-handle-mail' on a heading with no associated messages,
or when `gnorb-org-handle-mail' is called with a prefix arg.
@item `gnorb-org-find-candidates-match'
When searching all Org files
for headings to collect messages from, this option can limit
which headings are searched. It is used as the second argument to
a call to `org-map-entries', and has the same syntax as that used
in an agenda tags view.
@item `gnorb-org-email-subtree-text-parameters'
A plist of export
parameters corresponding to the EXT-PLIST argument to the export
functions, for use when exporting to text.
@item `gnorb-org-email-subtree-file-parameters'
A plist of export
parameters corresponding to the EXT-PLIST argument to the export
functions, for use when exporting to a file.
@item `gnorb-org-email-subtree-text-options'
A list of ts and nils
corresponding to Org's export options, to be used when exporting
to text. The options, in order, are async, subtreep,
visible-only, and body-only.
@item `gnorb-org-email-subtree-file-options'
A list of ts and nils
corresponding to Org's export options, to be used when exporting
to a file. The options, in order, are async, subtreep,
visible-only, and body-only.
@item `gnorb-org-export-extensions'
Correspondence between export
backends and their respective (usual) file extensions.
@item `gnorb-org-capture-collect-link-p'
When this is set to t, the
capture process will always store a link to the Gnus message or
BBDB record under point, even when the link isn't part of the
capture template. It can then be added to the captured heading
with org-insert-link, as usual.
@item `gnorb-org-log-add-link'
When non-nil, any time a todo trigger
action results in adding a note, a link to the triggering message
will be added to the log note text.
@item `gnorb-org-agenda-popup-bbdb'
Set to ``t'' to automatically pop up
the BBDB buffer displaying records corresponding to the Org
Agenda tags search underway. If this is nil you can always do it
manually with the command of the same name.
@item `gnorb-org-bbdb-popup-layout'
Controls the layout of the
Agenda-related BBDB popup, takes the same values as
bbdb-pop-up-layout.
@end table

@node Misc Gnus
@chapter Misc Gnus

@menu
* Searching With the Registry::
* User Options: User Options 2.
@end menu

@node Searching With the Registry
@section Searching With the Registry

Gnorb can use the Gnus registry as a sort of limited search index: the
registry tracks information about sender, recipient, subject, and a
few other things, and while this isn't as powerful as a full-text
search index, it's often sufficient. It's also very fast, as it
doesn't rely on external program, and doesn't require the user to mark
a particular set of groups beforehand.

@table @asis
@item `gnorb-gnus-search-registry'
Prompt the user for a search string,
and match it against messages tracked in the registry. Search
strings are given as a series of ``key:value'' terms, with double
quotes around multi-word values. See docstring for available
keys.
@item `gnorb-helm-search-registry'
Helm users can use this function to
conduct a more visual search of the registry. Only
sender/recipient and subject lines are matched against.
@end table

These functions are not bound by default; you might consider:

@lisp
(with-eval-after-load "gnus-group"
  (define-key gnus-group-group-map (kbd "/") #'gnorb-gnus-search-registry)
  (define-key gnus-group-group-map (kbd "?") #'gnorb-helm-search-registry))
@end lisp

@node User Options 2
@section User Options

@table @asis
@item `gnorb-gnus-mail-search-backend'
Specifies the search backend
that you use for searching mails. Currently supports notmuch,
mairix, and namazu: set this option to one of those symbols.
@item `gnorb-gnus-capture-always-attach'
Treat all capture templates as
if they had the :gnus-attachments key set to ``t''. This only has
any effect if you're capturing from a Gnus summary or article
buffer.
@item `gnorb-gnus-tick-all-tracked-messages'
When non-nil, always add
the tick mark to messages when they are first associated with an
Org heading. The mark can be safely deleted afterwards.
@item `gnorb-trigger-todo-default'
Set to either 'note or 'todo to tell
`gnorb-gnus-incoming-do-todo' what to do by default. You can
reach the non-default behavior by calling that function with a
prefix argument. Alternately, set to 'prompt to always prompt for
the appropriate action.
@item `gnorb-gnus-trigger-refile-targets'
If you use
`gnorb-gnus-incoming-do-todo' on an incoming message, Gnorb will
try to locate a TODO heading that's relevant to that message. If
it can't, it will prompt you for one, using the refile interface.
This option will be used as the value of `org-refile-targets'
during that process: see the docstring of `org-refile-targets'
for the appropriate syntax.
@item `gnorb-gnus-refile-use-outline-path'
Similar to the previous
option, this option will be used as the value of
`org-refile-use-outline-path' when selecting a heading: see the
its docstring for the meaning of its potential values.
@item `gnorb-gnus-new-todo-capture-key'
Set this to a single-character
string pointing at an Org capture template to use when creating
TODOs from outgoing messages. The template is a regular capture
template, with a few exceptions. If Gnus helps you archive
outgoing messages (ie you have `gnus-message-archive-group' set
to something, and your outgoing messages have a ``Fcc'' header), a
link to that message will be made, and you'll be able to use all
the escapes related to gnus messages. If you don't archive
outgoing messages, you'll still be able to use the %:subject,
%:to, %:toname, %:toaddress, and %:date escapes in the capture
template.
@item `gnorb-gnus-hint-relevant-article'
Set to ``t'' (the default) to
have Gnorb give you a hint in the minibuffer when opening
messages that might be relevant to existing Org TODOs.
@item `gnorb-gnus-summary-mark-format-letter'
The formatting letter to
use as part of your `gnus-summary-line-format', to indicate
messages which might be relevant to Org TODOs. Defaults to ``g'',
meaning it should be used as ``%ug'' in the format line.
@item `gnorb-gnus-summary-mark'
The mark used to indicate 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 Default Keybindings
@chapter 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 "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 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-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-mode-map (kbd "C-c v") #'gnorb-gnus-view)
     (define-key gnus-summary-mode-map (kbd "C-c C-t") #'gnorb-gnus-tag-message)
     (define-key gnus-summary-limit-map (kbd "g") #'gnorb-gnus-insert-tagged-messages)
     (define-key gnus-summary-limit-map (kbd "G") #'gnorb-gnus-insert-tracked-messages)
     (setq gnorb-gnus-capture-always-attach t)
     (push '("attach to org heading" . gnorb-gnus-mime-org-attach)
           gnus-mime-action-alist)
     (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)))
             (dolist (c gnus-mime-button-commands)
               (define-key map (cadr c) (car c)))
             map))))
(eval-after-load "message"
  '(progn
     (define-key message-mode-map (kbd "C-c t") #'gnorb-gnus-outgoing-do-todo)))
@end lisp

@bye