GNU ELPA - org-remark

org-remark

Description
Highlight & annotate text, Info, EPUB, EWW
Latest
org-remark-1.2.2.tar (.sig), 2024-Mar-31, 300 KiB
Maintainer
Noboru Ota <me@nobiot.com>
Atom feed
org-remark.xml
Website
https://github.com/nobiot/org-remark
Browse ELPA's repository
CGit or Gitweb
Badge
Manual
org-remark

To install this package from Emacs, use package-install or list-packages.

Full description

GNU Emacs GPLv3 GNU ELPA GNU-devel ELPA

1. Introduction

Org-remark lets you highlight and annotate text files, websites, EPUB books and Info documentation with using Org mode.

A user manual is available online or Emacs in-system as an Info node `(org-remark)': (C-h i and find the Org-remark node).

For installation and minimum configuration, refer to Installation below or the user manual: online or Info node `(org-remark) Installation'

Getting Started in the user manual will get you started in 5 minutes: online or or Info node `(org-remark) Getting Started'.

For customization, refer to the customization group `org-remark' or user manual: online or Info node `(org-remark) Customizing'. A separate online article has been written to guide you on how to customize an icon (also part of the user manual. Evaluate (info "(or-gremark) How to Set Org-remark to Use SVG Icons").

An introductory video (8 minutes) and V1.1.0 release introduction (12 minutes) are available on YouTube.

2. Features

  • Highlight and annotate any text file. The highlights and notes are kept in an Org file as the plain text database. This lets you easily manage your marginal notes and use the built-in Org facilities on them – e.g. create a sparse tree based on the category of the notes
  • Create your your own highlighter pens with different colors, type (e.g. underline, squiggle, etc. optionally with Org's category for search and filter on your highlights and notes)
  • Have the same highlighting and annotating functionality for
    • Websites when you use EWW to browse them
    • EPUB books with nov.el
    • Info documentation

3. Installation

This package is available on:

  • GNU-ELPA (releases only; equivalent to MELPA-Stable)
  • GNU-devel ELPA (unreleased main branch; equivalent to MELPA)

GNU ELPA should be already set up in your Emacs by default. If you wish to add GNU-devel ELPA, simply add its URL to package-archives like this:

(add-to-list 'package-archives
	     '("gnu-devel" . "https://elpa.gnu.org/devel/") :append)

After installation, we suggest you put the setup below in your configuration.

(org-remark-global-tracking-mode +1)

;; Optional if you would like to highlight websites via eww-mode
(with-eval-after-load 'eww
  (org-remark-eww-mode +1))

;; Optional if you would like to highlight EPUB books via nov.el
(with-eval-after-load 'nov
  (org-remark-nov-mode +1))

;; Optional if you would like to highlight Info documentation via Info-mode
(with-eval-after-load 'info
  (org-remark-info-mode +1))

Unless you explicitly load org during Emacs initialization, I suggest to defer loading org-remark (thus there is no (require 'org-remark) in the example above). This is because it will also pull in org, which can slow down initialization. You can control the timing of loading org-remark by autoloading some commands in a similar way with the example keybindings below.

Below are example keybindings you might like to consider:

;; Key-bind `org-remark-mark' to global-map so that you can call it
;; globally before the library is loaded.

(define-key global-map (kbd "C-c n m") #'org-remark-mark)

;; The rest of keybidings are done only on loading `org-remark'
(with-eval-after-load 'org-remark
  (define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open)
  (define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-view-next)
  (define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-view-prev)
  (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove)
  (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete))

Alternatively, you can use use-package to set up Org-remark. The example provided below should be equivalent to the setup described above.

(use-package org-remark
  :bind (;; :bind keyword also implicitly defers org-remark itself.
	 ;; Keybindings before :map is set for global-map.
	 ("C-c n m" . org-remark-mark)
	 ("C-c n l" . org-remark-mark-line)
	 :map org-remark-mode-map
	 ("C-c n o" . org-remark-open)
	 ("C-c n ]" . org-remark-view-next)
	 ("C-c n [" . org-remark-view-prev)
	 ("C-c n r" . org-remark-remove)
	 ("C-c n d" . org-remark-delete))
  ;; Alternative way to enable `org-remark-global-tracking-mode' in
  ;; `after-init-hook'.
  ;; :hook (after-init . org-remark-global-tracking-mode)
  :init
  ;; It is recommended that `org-remark-global-tracking-mode' be
  ;; enabled when Emacs initializes. Alternatively, you can put it to
  ;; `after-init-hook' as in the comment above
  (org-remark-global-tracking-mode +1)
  :config
  (use-package org-remark-info :after info :config (org-remark-info-mode +1))
  (use-package org-remark-eww  :after eww  :config (org-remark-eww-mode +1))
  (use-package org-remark-nov  :after nov  :config (org-remark-nov-mode +1)))

4. Contributing and Feedback

Create issues, discussion, and/or pull requests in the GitHub repository. All welcome.

Org-remark is available on GNU ELPA and thus copyrighted by the Free Software Foundation (FSF). This means that anyone who is making a substantive code contribution will need to "assign the copyright for your contributions to the FSF so that they can be included in GNU Emacs" (Org Mode website).

Thank you.

5. Contributors

New features

  • EPUB books (nov.el) support would not have been possible without collaboration with @sati-bodhi
  • echo-text update from the marginal notes to the source buffer by marty hiatt (@mooseyboots)
  • Support for websites with eww-mode by Vedang Manerikar (@vedang)

Bug fixes

@alan-w-255, Nan Jun Jie (@nanjj), @sgati-bodhi

Documentation (including README, NEWS, CHANGELOG)

@randomwangran, marty hiatt (@mooseyboots), @jsntn

Thank-you to all the comments, issues, and questions on GitHub!

6. License

This work is licensed under a GPLv3 license. For a full copy of the license, refer to LICENSE.

Old versions

org-remark-1.2.1.tar.lz2023-Aug-2053.3 KiB
org-remark-1.1.0.tar.lz2023-May-2045.7 KiB
org-remark-1.0.5.tar.lz2022-May-1439.7 KiB
org-remark-1.0.4.tar.lz2022-Mar-1239.7 KiB
org-remark-1.0.3.tar.lz2022-Feb-2839.4 KiB
org-remark-1.0.2.tar.lz2022-Feb-1439.3 KiB
org-remark-1.0.1.tar.lz2022-Feb-1239.3 KiB

News

Current development version (release candidate 1.3.0)

     Features:

   - Ability to highlight a whole line and show a mark on the margin (#71)

   - Option to delete the whole notes entry when highlight is removed if
     there is no notes body text (#21)

   - `org-remark-open` to open the associated marginal notes file if
     cursor outside a highlight (#72)

     Fixes:

   - fix: compiler warning ‘org-remark-highlight-save’ is an obsolete...

Version 1.2.2 - 2024-03-25

  - fix: program error #78 mapconcat's 3rd arg is not optional in Emacs 28

Version 1.2.1 - 2023-08-20

  - fix: org-remark-icon-mode is a void symbol

Version 1.2.0 - 2023-08-20

  - feat(info): Org-remark supports Info

          + Advice has been implemented. It is added and removed by
            `org-remark-info-mode`.

          + No suitable hook is avaialble to trigger a function after the Info node
            is rendered. This is necessary as Info renders a new node in the same
            buffer (in the same way as Nov.el does).

  - feat: icons for additional information for highlights

          + Notes exists for the highlight (*)

          + The highlight position auto-adjusted (d)

          + Uses the new `org-remark-highlights-after-load-functions'

          + Icons are customizable. You can also disable icons by setting
            the respective customizing variable to nil

          + The default face of auto-adjusted icon is customizable with
            face `org-remark-highlighter-warning'

          + `org-remark-toggle' also toggles the icon display

  - feat: nov.el support for epub books

         + The link is added to the notes org file correctly pointing
           back to epub's highlight location with using :nov link type
           added by nov.el.l

  - feat: Adjust positions after load

         + This is useful especially for epubs via nov.el. Nov.el
           renders tables on differently depending on the size of the
           window. This causes the positions of subsequent text elements
           to move depending on the window size when the page is
           rendered, dislocating the positions of highlights. This
           feature attemps to auto-correct the location on the fly. The
           feature works generically, so Org-remark attemps to correct
           minior edits to websites (for EWW).

         + The fact that a given highlight has been automatically moved
           is indicated by an icon

  - feat: org-remark-highlights-after-load-functions
          Abnormal hook

  Fixes:

  - fix: org 9.6.7 breaks org-remark-highlights-get (#70)

  - fix: Make load process robust

         + When error occurs during the load process, instead of
           emitting an error, Org-remark now halts the load process and
           returns without an error. This has been proven useful
           especially for epub support with nov.el. Nov.el renders by
           reusing the same buffer instead of generating a new one. When
           error occurs during the load process (e.g. user accidentally
           deletes some property data in the notes org buffer), the
           error would cause nov.el to not properly render the epub
           book. This could override the epub archive file wiht a plain
           text file of a single file from the book, errasing the entire
           book. With this change, Org-remark does not cause the error
           when loading highlights from the notes org file to preven
           this distructive process from happening.

         + `org-remark-highlights-get' existence checks beg and end

           beg and end must exist. If either is nil, `number-to-string`
           errors and load stops prematurely. This can happen when the
           user manually manages the notes file and accidentally deletes
           the beg/end props.

   - fix: default highlighter color for dark theme

          No functional change. Changed the default color of the
          highlighter to be more visible in the dark theme.
...
...