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

#+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://img.shields.io/static/v1?logo=gnuemacs&logoColor=fafafa&label=Made%20for&message=GNU%20Emacs&color=7F5AB6&style=flat"/></a>
#+html: <a href="https://github.com/nobiot/org-remark/blob/main/LICENSE"><img alt="GPLv3" src="https://img.shields.io/badge/License-GPLv3-blue.svg"></a>
#+html: <a href="http://elpa.gnu.org/packages/org-remark.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/org-remark.svg"/></a>
#+html: <a href="http://elpa.gnu.org/devel/org-remark.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/org-remark.svg"/></a>

* 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 [[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'. A [[https://github.com/nobiot/org-remark/tree/main/docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md][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 [[https://youtu.be/c8DHrAsFiLc][introductory video]] (8 minutes) and [[https://youtu.be/BTFuS21N00k][V1.1.0 release introduction]] (12 minutes) are available on YouTube.

* 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 [[https://depp.brause.cc/nov.el/][nov.el]]

   + Info documentation

   + [[https://github.com/chenyanming/wallabag.el][wallabag.el]] (it has been [[https://github.com/nobiot/org-remark/issues/92#issuecomment-2601307855][reported]])

Refer to  [[https://github.com/nobiot/org-remark/blob/main/NEWS][NEWS]] file for a list of new features and fixes.

* 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) and [[https://youtu.be/BTFuS21N00k][v1.1.0 release introduction]] (12 minutes) are 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/2023-08-20-epub-prince-icon.png]]
*Figure 3*. EPUB book ("Prince" by Niccolò Machiavelli via https://www.gutenberg.org/) with icon indicating there are annotations to the highlight: new features with v1.2.0 (2023-08-20). Left: marginal notes file with annotations; Right: an EPUB book file with a highlight and simple ASCII icon.

[[./resources/images/v1.3.0/2023-08-19-line-highlights-with-icons.png]]
*Figure 4*. Line-highlights with using icons (as of v1.3.0). Refer to the user manual or [[https://nobiot.com/blog/2023-09-11_org-remark-v1.3-line-highlight/][this article]] for more detail.

* 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 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:

#+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
  (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))
#+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)
    (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete))
#+end_src

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

#+begin_src emacs-lisp
  (use-package org-remark-global-tracking
    ;; It is recommended that `org-remark-global-tracking-mode' be
    ;; enabled when Emacs initializes. You can set it in
    ;; `after-init-hook'.
    :hook after-init
    :config
    ;; Selectively keep or comment out the following if you want to use
    ;; extensions for Info-mode, EWW, and NOV.el (EPUB) respectively.
    (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)))

  (use-package org-remark
    :bind (;; :bind keyword also implicitly defers org-remark itself.
           ;; Keybindings before :map is set for global-map. Adjust the keybinds
           ;; as you see fit.
           ("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)))
#+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.

* Contributors

*New features*

- User option `org-remark-report-no-highlights`by Kristoffer Balintona (@krisbalintona)
- 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*

Joseph Turner (@josephmturner) @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!

* License

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