#+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: <img alt="GPLv3" src="https://img.shields.io/badge/License-GPLv3-blue.svg">

* ❦❦❦ 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]] (Info node will be available when Org-remark is added to ELPA/MELPA) 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/devel/org-remark.html][GNU-devel ELPA]] (unreleased development branch; equivalent to MELPA)

It will soon be available on GNU ELPA (releases only; equivalent to MELPA-Stable) in one of the next updates.

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 planned to be submitted to 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.
