Keep notes on Gnus articles and emails - not all of them, just the ones that matter, viewed with the convenience of helm. Keep more extensive notes and tasks about your gnus-notes with Org-mode.
The gnus-notes works with your Gnus, it can not replace it. Neither can it damage or hurt your Gnus. Your Gnus is safe. It just works in the background, unimpending, efficiently and quietly, keeping track of the articles read with gnus. When an article is read, it adds a quick note. It removes notes of deleted articles or the ones expunged by gnus.
Providing a good level of Gnus-Org integration. It will complement your Gnus experience.
This simplicity allows the user to add and remove articles to gnus-notes, stress free. Gnus-notes can be used without having to start gnus.
Viewing gnus-notes with the powerful helm interface brings great search
capabilities and all the other helm goodness.
Gnus-notes has been built around helm.
Gnus is not limited to email, that is why gnus uses the term “articles”. Gnus-notes follows the Gnus general philosophy, it also uses the term “articles”. Most testing has been done on email (and IMAP in particular) and RSS.
This work is a fork of unhammer’s gnus-recent. Some ideas for integration with
other emacs features are from ericabrahamsens’s gnorb package.
This is still work in progress. But safe to use.
The following packages are required, for gnus-notes:
bbdbandbbdb-muagnusorg-gnusor the newerol-gnus.helm-libs
This is not an Emacs package, so installation is still a manual process. Place the files in a directory and add it the load path. Load the library or using require:
(require 'gnus-notes-helm)
(gnus-notes-init)Now your gnus-notes is waiting to start tracking your Gnus. After viewing a few emails or other gnus articles, to start using gnus-notes, invoke the helm command ‘gnus-notes-helm’. This command is the main entry to gnus-notes. For quick access, add an option to your favorite hydra or assign to a global key:
(global-set-key (kbd "C-c m") #'gnus-notes-helm)For org integration the user has to define a key sequence. This should be set in
the user configuration file or run manually. The convenience function
gnus-notes-org-define-key can be used:
(gnus-notes-org-define-key) ; default "C-c t"
;; or
(gnus-notes-org-define-key "C-c X") ; use another key sequenceAdvanced users can look at the definition of the above function, to fine-tune their needs.
For those who prefer using use-package, user Thaodan recommends and uses
following configuration setup:
(use-package gnus-notes-org
:after org
:bind (
;; define keybindings here instead of using gnus-notes-org-define-key
;; to profit from use-packages lazy loading
:map org-mode-map
("C-c t" . gnus-notes-org-handle-mail)
:map org-agenda-keymap
("C-c t" . gnus-notes-org-handle-mail)
:map gnus-summary-mode-map
("C-c t" . gnus-notes-org-capture-mail)
:map gnus-article-mode-map
("C-c t" . gnus-notes-org-capture-mail)))
(use-package gnus-notes
:after gnus
:after gnus-notes-org
:config
(gnus-notes-init))
(use-package gnus-notes-helm
:after gnus-notes
:bind (("C-c g m" . gnus-notes-helm)))After loading the gnus-notes library, start your gnus and read a few
articles (emails). To view the list of the emails and articles just read, type
the command gnus-notes-helm.
For quick access asign to a global key, such as:
(global-set-key (kbd "C-c m") #'gnus-notes-helm)Or add it as an option to your favorite hydra.
Gnus is very efficient in displaying new emails, but sometimes it is hard to
remember the Group the rest of the thread was filed. Just C-c m, to fire up
the gnus-note helm interface and quickly narrow to the thread using subject
words or the sender’s name. The filling Group will be shown.
Below is a shot of helm-gnus-notes showing (fake) emails from the gnus-mock
package (a Mock Gnus installation for testing).
The helm search is performed on the whole lines. Matching and refining the search is part of helm:
Gnus-notes displays one email (or gnus article) each line, with the following information:
- Sender or recipient, according to
gnus-ignored-from-addresses. - Subject line
- Date, default in Org date format, but customizable.
- Gnus group name.
For other gnus article, such as RSS feeds instead of emails, the above info are
displayed similarly:
Helm provides many useful features. Pressing M-<up>, displays additional
information, such as To, Cc fields if available, in multi-line format:
Helm has many features. It is worth checking the helm manual (C-h m). It is
beyond this README to provide detailed info on Helm.
This is a new functionality in gnus-notes. Now the user can edit the display
string or the article group. This is handy when the user doesn’t like something
about the display string, such as:
- the name may be long and would like to shorten it.
- wants a more concise or descriptive line.
- too much whitespace.
- etc.
As for the article group, gnus-notes tries hard to track it and keep it up-to date. When the article is handled outside of gnus-notes, such as when reading email using a web-interface, this tracking is not possible. The group value may have changed and could be wrong. Manually editing the group value will help provide links (org-style gnus-links) to the article, that are correct and work as expected. Selecting the group name using completion is not implemented yet and is pending.
By default the following actions are available:
| Key | Action | Remarks |
|---|---|---|
[F1] | Open article | will open the article in gnus |
[F2] | Reply (to) article | Wide-reply-and-yank (S W) |
[F3] | Show thread | gnus-summary-refer-thread (A T) |
[F4] | Edit display line | User edit |
[F5] | Edit Group | User edit article group |
[F6] | Copy org-link to kill ring | Create an org-link |
[F7] | Insert org-link | Insert org-link at point in buffer |
[F8] | Insert quick note | Insert quick note at point in buffer |
[F9] | Remove marked article(s) | Remove current article or multiple marked articles (C-<space>) from the gnus-notes. |
| Gnus is not affected, this only affects the list. | ||
[F10] | Display BBDB entries | Display BBDB buffer. |
[F11] | Clear all | Start over. Clear ALL the articles on the list. Careful! |
Applying any of the actions, will close the helm buffer. You can get back by
restarting helm-gnus-notes or resuming with helm-resume (C-x c b).
The message at the top of the helm window is a hint to persistent actions. Persistent actions are special actions that do not close the helm buffer.
C-j: quick helm config and actions (keeping session)
Gnus-notes provides a hydra, to select from a number of available persistent actions, a mix of helm configuration items and actions on the articles:
The C-c t key sequence activates the gnus-notes integration functionalities.
It is associated with different actions depending on the mode:
- in
org-mode, it lists all thegnus:type links under the current org subtree. - in
summaryorarticle-mode, i.e. while reading in gnus, lets you directly create a quick note using the org-capture system. It preselects the capture template. By default, it is set to creating a REPLY to-do heading. The user can customize this of course, this is Emacs, after all.
This sections assumes the default key sequence is used. If the user has defined another, it should be used.
In a org-mode file, typing C-c t will scan the whole subtree under the current
heading for org links using the gnus: prefix. These are org-gnus links, as
defined in package org-gnus or ol-gnus (newer).
The user is presented with a choice menu (another hydra!) on what to do:
The options have the following meaning:
h: View in helm using notes. Only the articles in notes will be displayed.t: Apply aWide-reply-and-yank(S W) to top item.v: Search Gnus using thennirgnus engine. This is configured by default for thennimapengine. For other gnus back ends, some setup is required. See the Gnus manual for Searching details.
Here, if/when selecting the action to reply to an article display in the h
option, or directly in the t option, the user will be offered to save a quick
note under to the current heading. This note is created using the org-add-note
(C-c C-z) command. It will have the following information:
- An org timestamp
- An org-gnus link to the message just sent
- The user supplied text notes.
Where the note is placed depends on the variables org-log-into-drawer. By
default notes are stored in the LOGBOOK drawer. The user may want to customize
org-mode, to place the note outside the drawer.
While reading, the mostly email, articles in gnus the user can use the familiar
C-c t key sequence to directly capture an org-note using the preselected
gnus-notes-org-capture-key (default ”e” for email) org-capture template. A
suggested capture template is provided by gnus-notes, which the user may
customize. See gnus-notes-org-capture-template.
This is a handy way for creating a “REPLY” task for responding to an email. Once the reply has been sent, the task can be marked “REPLIED” or “DONE”, or if expecting an answer, marked “WAIT” along with a scheduled time until sending a reminder.
Most development and testing has been done using gnus IMAP, keeping the emails on the IMAP server.
Gnus-notes works in the background, while the user is using gnus. It takes a note
of each article you read. The note contains some basic information about the
article. The first time an article is read, this note is stored in a list
(gnus-notes--articles-list).
The above process has two consequences:
- the article notes are saved in the sequence read by the user (you).
- only read article notes are on the list. Articles deleted or ignored are not on the list.
This provides a natural first filtering of the articles, that helps to keep the size small. Gnus-notes does not try (or want) to keep track of everything.
Gnus-notes creates its own directory for its saving needs. This is defined in
gnus-notes-top-dir, default =”~/.emacs.d/gnus-notes”= . The Gnus-notes list
is saved in gnus-notes-file, default =”~/.emacs.d/gnus-notes/articles.el”=.
To guard against data-loss, a breadcrumbs directory (for the crumbs left behind!)
is defined in gnus-notes-breadcrumbs-dir, default
=”/.emacs.d/gnus-notes/crumbs"=. These "crumbs" will be cleaned up when
gnus-notes starts or is saved (~gnus-notes-save).
These path locations can be changed using the customize interface.
Gnus-notes tries to track gnus operations, to provide an accurate status. Direct gnus operations will update article details in gnus-notes:
- Moving (
B M) an article to another group, will update the group location - Deleting (
B <del>) article(s) will remove it/them from gnus-notes - Expunging (
G x) will also remove article(s) from gnus-notes
On the other hand, operations to gnus-notes have no effect on gnus, see Actions. So, when an article is removed/deleted from gnus-notes, only the note is deleted from the list. The actual article(s) is still available in gnus and can be read back to gnus-notes.
As mentioned above, gnus-notes tracks Gnus. It does not know of any actions performed outside of Gnus. This means that any actions such as moving, deleting performed using a web-interface to your imap email or other imap client, will not be reflected in gnus-notes. So, for example, gnus-notes may display the wrong group for an email that was moved using another client.
This work is distributed under the terms of the Gnu General Public License Version 3 or later. See LICENSE.