Org-remark v1.3 Delete and Remove

Org-remark is an Emacs package I have been developing. It lets you highlight and annotate text files, websites, EPUB books and Info documentation with using Org mode.

New Option to Auto Delete Entries in Marginal Notes File

Automatic deletion is a new optional feature with v1.3. This has been added in response to GitHub issue #21. When the feature is enabled, Org-remark will automatically delete the highlight’s headline when you delete text that includes a highlight, provided there is no marginal notes for it. If marginal notes are present for the highlight’s headline, Org-remark only removes the highlight, deleting the properties from the highlight headline – same operation as org-remark-remove. Your marginal notes will be kept intact. In either case, Org-remark does not ask for your confirmation.

This is not new, but it is important to note that you can undo the deletion or removal in the marginal notes buffer – not in the source buffer where you mark text with a highlighter. Technically, highlights are overlays and are therefore not part of the undo tree in the source buffer.

If you prefer automatic deletion, all you need to do is to enable it with the new user option org-remark-notes-auto-delete like so.

(setopt org-remark-notes-auto-delete :auto-delete)

Furthermore, with v1.3, if you pass a universal argument to org-remark-delete (e.g. C-u M-x org-remark-delete) you can manually get Org-remark to do automatic deletion for the highlight at point. You can also pass double universal arguments to org-remark-remove (e.g. C-u C-u M-x org-remark-remove) for the same operation. This should make sense because passing a single universal argument to org-remark-remove is the same as org-remark-delete.

Background

Org-remark is conservative about deleting entries in the marginal notes file¹. This is intentional. Notes that you write are a result of your intellectual efforts. You can write extensive research notes with a sub-headings in the marginal notes. Your tool must not meddle with them; you must have the full control over what happens to them.

This is the reason why Org-remark differentiates remove and delete. Remove does not delete the headline in the marginal notes file, but does only the properties so as to remove the highlight. Delete deletes the headline, but it will ask you for your confirmation if you have written marginal notes under the headline. The distinction may make more sense with a concrete example. If you are writing a research paper, and you want to leave some comments to a paragraph you want to expand later. You highlight a word and write the comments in the marginal notes. You also make the headline a TODO so that it appears in your agenda. Later, you decide to remove the line that includes the highlight. Org-remark does not delete the TODO headline and comments in the marginal notes; it only removes the highlight in your research paper as you have deleted the line it belongs.

This conservative behaviour, however, may lead to cluttering the marginal notes file, as noted in GitHub issue #21. In response to this discussion, version 1.3 introduces a new option to have Org-remark to automatically delete the headlines when you delete text that includes highlights if there is no marginal notes.

The default is as it always has been; if you are happy with the way Org-remark automatically removes highlights and corresponding entries in the marginal notes file, then there is nothing you need to do. Please file a bug report if you observe something different.