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
Table of Contents
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-textupdate from the marginal notes to the source buffer by marty hiatt (@mooseyboots)- Support for websites with
eww-modeby 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.lz | 2023-Aug-20 | 53.3 KiB |
| org-remark-1.1.0.tar.lz | 2023-May-20 | 45.7 KiB |
| org-remark-1.0.5.tar.lz | 2022-May-14 | 39.7 KiB |
| org-remark-1.0.4.tar.lz | 2022-Mar-12 | 39.7 KiB |
| org-remark-1.0.3.tar.lz | 2022-Feb-28 | 39.4 KiB |
| org-remark-1.0.2.tar.lz | 2022-Feb-14 | 39.3 KiB |
| org-remark-1.0.1.tar.lz | 2022-Feb-12 | 39.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.
...
...