org-remark

org-remark copied to clipboard

#+title: README – Org-remark #+options: toc:t creator:nil author:nil broken-links:t

#+html: #+html:

• ❦❦❦ IMPORTANT NOTICE ❦❦❦ :noexport:

[This notice written on 18 January 2022]

Happy 2022!

I have changed the name of the project and package to "Org-remark" from Org-marginalia.

If you are using Org-marginalia now, there are breaking changes. This package includes the feature that automatically converts the old Org-marginalia data into the new Org-remark data. Add ~org-remark-convert-legacy~ feature like this:

#+begin_src elisp (require 'org-remark-convert-legacy) #+end_src

This feature is designed to work automatically and transparently to you, meaning you should not have to do anything, as long as you did not customize ~org-marginala-notes-file-path~. If you did, you also need to customize ~org-remark-notes-file-path~. You can also manually do data conversion if you wish. For more detail, refer to the docstring of function ~org-remark-convert-legacy-data~.

• Introduction

Org-remark lets you highlight and annotate any text file with using Org mode.

A user manual is available [[https://nobiot.github.io/org-remark/][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][Installation]] below or the user manual: [[https://nobiot.github.io/org-remark/#Installation][online]] or Info node `(org-remark) Installation'

Getting Started in the user manual will get you started in 5 minutes: [[https://nobiot.github.io/org-remark/#getting-started][online]] or or Info node `(org-remark) Getting Started'.

For customization, refer to the customization group org-remark' or user manual: [[https://nobiot.github.io/org-remark/#Customizing][online]] or Info node (org-remark) Customizing'.

An [[https://youtu.be/c8DHrAsFiLc][introductory video]] (8 minutes) is available on YouTube.

• Screenshots and Videos :noexport:

[[./resources/images/2022-01-22-Title.png]] Figure 1. Left: Org-mode with text enlarged; Right: marginal notes with an inline image. [[https://youtu.be/c8DHrAsFiLc][Introductory video]] (8 minutes) is available on YouTube

[[./resources/images/2022-01-22-Context-menu.png]] Figure 2. Mouse context menu with built-in ~context-menu-mode~ available with Emacs version 28 onward

[[./resources/images/2022-01-22-code.png]] Figure 3. Main notes can be any text files. Left: marginal notes file; Right: an ~org-remark.el~ file with a highlight.

• Installation :PROPERTIES: :CUSTOM_ID: installation :END:

This package is available on:

• [[https://elpa.gnu.org/packages/org-remark.html][GNU-ELPA]] (releases only; equivalent to MELPA-Stable)
• [[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] (unreleased development 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:

#+BEGIN_SRC elisp (add-to-list 'package-archives '("gnu-devel" . "https://elpa.gnu.org/devel/") :append) #+END_SRC

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

#+begin_src emacs-lisp (require 'org-remark-global-tracking) (org-remark-global-tracking-mode +1) #+end_src

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:

#+begin_src emacs-lisp ;; 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)) #+end_src

• 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 [[http://fsf.org][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" ([[https://orgmode.org/contribute.html#copyright][Org Mode website]]).

Thank you.

• License

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

• Marginal Notes :noexport: :PROPERTIES: :org-remark-file: ~/src/org-remark/org-remark.el :END:

This section is created by Org-remark for the source file. It serves as an example to illustrate what Org-remark can do.

** defmacro org-remark-create

This macro was inspired by [[https://github.com/jkitchin/ov-highlight][Ov-highlight]]. It's by John Kitchin (author of Org-ref). Great UX for markers with hydra. Saves the marker info and comments directly within the Org file as Base64 encoded string. It uses overlays with using ~ov~ package.