Skip to content

Keep handy notes of Gnus articles with helm and org

License

Notifications You must be signed in to change notification settings

deusmax/gnus-notes

 
 

Repository files navigation

gnus-notes README

1 Introduction

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.

2 Prerequisites

The following packages are required, for gnus-notes:

  • bbdb and bbdb-mua
  • gnus
  • org-gnus or the newer ol-gnus.
  • helm-lib
  • s

3 Installation

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 sequence

Advanced users can look at the definition of the above function, to fine-tune their needs.

3.1 The use-package method

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

4 Usage

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.

4.1 Viewing notes

Below is a shot of helm-gnus-notes showing (fake) emails from the gnus-mock package (a Mock Gnus installation for testing).

./img/readme-Mocky-01.png

The helm search is performed on the whole lines. Matching and refining the search is part of helm:

./img/readme-Mocky-02.png

Gnus-notes displays one email (or gnus article) each line, with the following information:

  1. Sender or recipient, according to gnus-ignored-from-addresses.
  2. Subject line
  3. Date, default in Org date format, but customizable.
  4. Gnus group name.

For other gnus article, such as RSS feeds instead of emails, the above info are displayed similarly:

./img/readme-nrss.png

Helm provides many useful features. Pressing M-<up>, displays additional information, such as To, Cc fields if available, in multi-line format:

./img/readme-Mocky-03.png

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.

4.2 Editing notes

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.

4.3 Actions

By default the following actions are available:

KeyActionRemarks
[F1]Open articlewill open the article in gnus
[F2]Reply (to) articleWide-reply-and-yank (S W)
[F3]Show threadgnus-summary-refer-thread (A T)
[F4]Edit display lineUser edit
[F5]Edit GroupUser edit article group
[F6]Copy org-link to kill ringCreate an org-link
[F7]Insert org-linkInsert org-link at point in buffer
[F8]Insert quick noteInsert 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 entriesDisplay BBDB buffer.
[F11]Clear allStart 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).

4.3.1 Persistent Actions

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:

./img/readme-persistent.png

5 Org integration

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 the gnus: type links under the current org subtree.
  • in summary or article-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.

5.1 Org-mode

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:

img/readme-org-current-heading.png

The options have the following meaning:

  • h: View in helm using notes. Only the articles in notes will be displayed.
  • t: Apply a Wide-reply-and-yank (S W) to top item.
  • v: Search Gnus using the nnir gnus engine. This is configured by default for the nnimap engine. 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:

  1. An org timestamp
  2. An org-gnus link to the message just sent
  3. 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.

5.2 Reading in Gnus

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.

6 Implementation details

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:

  1. the article notes are saved in the sequence read by the user (you).
  2. 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.

6.1 Saving

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.

6.2 Interaction with Gnus

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.

6.3 Limitation due to Gnus dependance

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.

7 License

This work is distributed under the terms of the Gnu General Public License Version 3 or later. See LICENSE.

8 Emacs

About

Keep handy notes of Gnus articles with helm and org

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Emacs Lisp 100.0%