[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/gnorb e089d66 129/449: Documenting recent additions in
From: |
Stefan Monnier |
Subject: |
[elpa] externals/gnorb e089d66 129/449: Documenting recent additions in the README |
Date: |
Fri, 27 Nov 2020 23:15:24 -0500 (EST) |
branch: externals/gnorb
commit e089d66ee955b893c6e482518d3fdd60535da229
Author: Eric Abrahamsen <eric@ericabrahamsen.net>
Commit: Eric Abrahamsen <eric@ericabrahamsen.net>
Documenting recent additions in the README
README.org: Lots of new sections on new functionality
---
README.org | 181 +++++++++++++++++++++++++++++++++++++++++++++++++------------
1 file changed, 145 insertions(+), 36 deletions(-)
diff --git a/README.org b/README.org
index f266fec..ea4a3a7 100644
--- a/README.org
+++ b/README.org
@@ -21,23 +21,23 @@ Code in this package is aimed at the development (git)
versions of
Gnus, Org, and BBDB (that means BBDB 3: upgrade, already!). I'll try
to make it work with the most recent stable releases of those
packages, but I'm not promising anything.
-** Using Gnorb for Tracking Email TODOs
+
Most of the functions listed later in this README are fairly discrete:
they do one thing only, and (I hope) don't require anything special in
-terms of file formats or workflow. The one exception to this is using
-Gnorb to keep track of email-related TODOs. Because we try to track
-them round-trip -- incoming and outgoing under one TODO representing a
-conversation -- it works best if things match up at both ends.
-Specifically:
+terms of file formats or workflow. A few exceptions to that are listed
+below.
+** Using Gnorb for Tracking Email TODOs
+Because we try to track email messages and related TODOs round-trip --
+incoming and outgoing under one TODO representing a conversation -- it
+works best if things match up at both ends. Specifically:
*** Capture templates for emails
Most people will be using plain capture templates to create TODOs from
messages. You'll almost always want to save a link to the message, so
you can get back to it later. Once the TODO is made, you can call
`gnorb-org-handle-mail' on it, to look for message and mail links and
automatically start a reply to the original message. The option
-`gnorb-org-mail-scan-scope' determines how much of the TODO heading
-and its subtree are scanned for links (set to a number to scan that
-number of paragraphs, or 0 for just the heading).
+`gnorb-org-mail-scan-strategies' determines how the TODO heading and
+its subtree are scanned for links -- see the docstring of that option.
Your capture template should therefore put the link where
`gnorb-org-handle-mail' can find it. Say your capture template looks
@@ -50,8 +50,9 @@ like this:
#+END_SRC
-Then you'll want to set `gnorb-org-mail-scan-scope' to 1 (at least),
-so that the link in the first paragraph is found.
+In this case, you'll want a scan strategy that looks at the first
+paragraph of body text.
+
*** Tracking conversations
It can be useful to use a single TODO heading to keep track of the
salient points of an entire email back-and-forth conversation -- a
@@ -94,8 +95,81 @@ that it is part of an ongoing conversation. The only thing it
(currently) won't do is automatically store a link to the message you
just replied to, so if you want to put that into the conversation,
you'll have to do it manually.
+*** 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 act on
+them: usually triggering a state change on the relevant TODO.
+
+This hinting can happen in the Gnus summary buffer as well. If you use
+the escape indicated by `gnorb-gnus-summary-mark-format-letter" as
+part of your `gnus-summary-line-format', articles that are relevant to
+TODOs will be marked with a special character in the Summary buffer,
+as determined by `gnorb-gnus-summary-mark'. By default, the format
+letter is "g" (meaning it is used as "%ug" in the format line), and
+the mark is "¡".
+** Showing gnus messages from links in Org buffers
+Sometimes you've got an Org subtree containing a bunch of Gnus links,
+and you'd like to see all those message in a single Gnus summary
+buffer. Gnorb can do this, but you'll have to add a new backend to
+your list of Gnus servers. If that makes your skin crawl a little, it
+probably should. But no fear! The server essentially does nothing but
+provide a place for nnir to hang searches.
+
+Add an entry like this to your `gnus-secondary-select-methods':
+
+(nngnorb "Purely Decorative Server Name")
+
+And restart Gnus. Now, on any given Org subtree, you can call
+`gnorb-org-view', and you'll be presented with an nnir *Summary*
+buffer containing all the messages linked to within the subtree.
+
+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.
+** 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.
+** 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 rebind "m" in
+`bbdb-mode-map' to `gnorb-bbdb-mail'.
+** Using attach with org capture
+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.
** Gnorb-BBDB
-*** Functions
+*** Interactive Functions
**** gnorb-bbdb-tag-agenda
Give BBDB records an org-tag field (customizable), then call this
function on the current records(s) to open an Org agenda tags search
@@ -108,17 +182,49 @@ supports the notmuch, mairix, and namazu search backends;
set
**** gnorb-bbdb-cite-contact
Prompt for a BBDB record and insert a string of the type "Bob Smith
<bob@smith.com>".
+**** gnorb-bbdb-mail
+Exactly like `bbdb-mail', except it runs the records through
+`gnorb-bbdb-posting-styles' first, and alters the composed message
+accordingly.
+**** gnorb-bbdb-open-link
+Open a message linked to from within a BBDB record's
+`gnorb-bbdb-messages-field'. Use prefix args to select the exact
+message. If a record is not yet collecting links, use this function to
+start the collection process.
*** User Options
**** gnorb-bbdb-org-tag-field
The name of the BBDB xfield that holds Org-related tags. Specified as
a string with the ":" separator between tags, 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.
+**** gnorb-bbdb-collect-N-messages
+Collect at most this many links to messages from this contact.
+Defaults to 5.
+**** gnorb-bbdb-define-recent
+What does "recently-received" mean? Possible values are '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.
+**** 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).
+**** 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).
+**** 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).
*** Suggested Keybindings
#+BEGIN_SRC emacs-lisp
(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 (kbd "m") '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)))
#+END_SRC
** Gnorb-Org
@@ -150,7 +256,8 @@ command replies to that message in a DWIM style.
**** gnorb-org-email-subtree
Call on a Org subtree to export the subtree as either text or a file.
Then compose a message with the text in the message body, or the file
-attached to the message.
+attached to the message. See the `gnorb-org-email-subtree-*' user
+options for influencing this process.
There's a little overlap with org-mime, but this function allows for
exporting the subtree as a file, and does not compose a MIME-multipart
@@ -182,7 +289,16 @@ the current tags search.
In a regular file, it will look at the heading under point for bbdb:
links, and pop up a BBDB buffer showing those records.
+**** gnorb-org-view
+If you've got a 'nngnorb backend installed in your gnus select
+methods, you can use this function on a subtree to scan it for gnus
+links and open all linked messages in a nnir summary buffer.
*** User Options
+**** gnorb-org-mail-scan-strategies
+This option provides various strategies for how the
+`gnorb-org-handle-mail' and `gnorb-org-email-subtree' functions act on
+links within the subtree at point. Three different options are
+provided, for flexibility -- see the docstring for details.
**** 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
@@ -195,45 +311,25 @@ you can always do it manually with the command of the
same name.
**** gnorb-org-bbdb-popup-layout
Controls the layout of the Agenda-related BBDB popup, takes the same
values as bbdb-pop-up-layout.
-**** gnorb-org-mail-scan-scope
-When calling `gnorb-org-handle-mail' on a TODO heading, this option
-controls how much of the heading and its text are scanned for relevant
-links. Set to 0 to only look within the heading text, or to a positive
-integer to scan that many paragraphs of body text. The symbols 'text
-and 'subtree will scan all the body text or all the body text and all
-subheadings, respectively.
-
-Note that if `gnorb-org-mail-scan-state-changes' is non-nil, the
-state-change drawer will be scanned for links first. If links are
-found there, only they will be used.
-**** gnorb-org-mail-scan-state-changes
-If this option is non-nil, `gnorb-org-handle-mail' will first look for
-links in the state-change drawer (ie the "LOGBOOK" or whatever you
-have it set to), and if any are found there they will be used instead
-of the links found elsewhere in the heading. Valid values are 'first
-(only the most recent state-change note will be examined), and 'all.
*** Suggested Keybindings
#+BEGIN_SRC emacs-lisp
(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 H") '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)
(setq gnorb-org-agenda-popup-bbdb t)
(eval-after-load "org-agenda"
- '(org-defkey org-agenda-mode-map (kbd "H") 'gnorb-org-handle-mail)
- '(org-defkey org-agenda-mode-map (kbd "V") 'gnorb-org-popup-bbdb))))
+ '(progn (org-defkey org-agenda-mode-map (kbd "H")
'gnorb-org-handle-mail)
+ (org-defkey org-agenda-mode-map (kbd "V")
'gnorb-org-popup-bbdb)))))
#+END_SRC
** Gnorb-Gnus
*** Functions
**** gnorb-gnus-article-org-attach
When called on an email with attached files, prompt for an Org heading
and attach the files to that heading using org-attach.
-**** Using attach with org capture
-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.
**** gnorb-gnus-incoming-do-todo
Call on an incoming message that should trigger a state change or a
note on an existing TODO. You'll be asked to locate the appropriate
@@ -285,6 +381,19 @@ 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.
+**** 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.
+**** 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.
+**** gnorb-gnus-summary-mark
+The mark used to indicate relevant messages in the Summary buffer,
+when `gnorb-gnus-summary-mark-format-letter' is present in the format
+line. Defaults to "¡".
*** Suggested Keybindings
#+BEGIN_SRC emacs-lisp
(eval-after-load "gnorb-gnus"
- [elpa] externals/gnorb 5182998 228/449: Necessary headers in main file, (continued)
- [elpa] externals/gnorb 5182998 228/449: Necessary headers in main file, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb ec32255 231/449: Use org-reveal when restoring/triggering, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb 4da19b0 232/449: Get rid of gnorb-org-mail-todos, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb 01f0a31 235/449: Move all *.el files out of lisp/ to top directory, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb eab79ec 241/449: Allow attachment transfers in nngnorb summary buffers, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb 20de4ee 104/449: Caching of msg-id to org-id correlations, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb edab89d 110/449: Be more careful about cleaning up attachments, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb 6375f83 112/449: And append doesn't modify destructively..., Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb f7b93f2 115/449: Whitespace/indentation cleanup, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb e86d24a 119/449: Robustification of nngnorb nnir message viewing, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb e089d66 129/449: Documenting recent additions in the README,
Stefan Monnier <=
- [elpa] externals/gnorb d254f39 140/449: Merge and simplify handle-mail and email-subtree, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb de3a512 244/449: Releasing version 1, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb 4b8a6da 255/449: New function for removing message/heading association, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb aaf8556 261/449: Be a good citizen about the cl package, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb de3182e 263/449: Shift location of org-reveal during trigger process, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb 6246244 106/449: Hinting for potentially-relevant incoming messages, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb a79cf72 126/449: Unwrap "if" from around function, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb 0255247 133/449: Only notice records on message receipt, not sending, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb b70d845 168/449: Handle nil group values in registry entries, Stefan Monnier, 2020/11/27
- [elpa] externals/gnorb 880afd6 158/449: Register sent messages so we can view them later, Stefan Monnier, 2020/11/27