branch: externals/org-remark
commit 76e5a4f9151e2a737f66129e2202a28cc73bc4b2
Author: Noboru Ota <m...@nobiot.com>
Commit: Noboru Ota <m...@nobiot.com>
docs: WIP
---
docs/org-remark-manual.org | 152 +++++++++++++++++++++++++++++----------------
1 file changed, 100 insertions(+), 52 deletions(-)
diff --git a/docs/org-remark-manual.org b/docs/org-remark-manual.org
index 3dcbdf3f2a..e876fe8932 100644
--- a/docs/org-remark-manual.org
+++ b/docs/org-remark-manual.org
@@ -1,7 +1,7 @@
#+title: Org-remark User Manual
#+author: Noboru Ota <m...@nobiot.com>
#+macro: version 1.0.x
-#+macro: modified 16 January 2022
+#+macro: modified 17 January 2022
#+language: en
#+export_file_name: org-remark.texi
@@ -46,26 +46,16 @@ modify this GNU manual.”
* Installation
:PROPERTIES:
-:TOC: :depth 0
+:CUSTOM_ID: installation
:END:
This package is not available on ELPA or MELPA yet. Manual installation is
required.
Ensure to have Org Mode 9.4 or later (tested on 9.4.2). This package uses
~org-collect-keywords~, which does not exist in an earlier version.
-Store both of the =.el= files in the repo in your load-path and put this in
your
+Store all the =.el= files in the repo in your load-path and put this in your
init file:
-#+BEGIN_SRC emacs-lisp
- (add-to-list 'load-path "~/local-repos/org-remark/")
- (require 'org-remark-global-tracking)
- (require 'org-remark)
-#+END_SRC
-
-By loading =org-remark=, it will also pull in Org mode. You might like to
defer loading of Org as it might take long time. As of version 0.0.6, you can
do so with loading only =org-remark-global-tracking=, which does not load =org=
automatically.
-
-For example, I use this in my init file.
-
#+begin_src emacs-lisp
;; Set `load-path' , load `org-remark-global-tracking', and turn it on for
;; automatic loading of highlights for the files tracked
@@ -74,6 +64,8 @@ For example, I use this in my init file.
(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. By autoloading some commands in similar ways as the example
keybindings below, you can control the timing of loading =org-remark=.
+
Below are example keybindings you might like to consider:
#+begin_src emacs-lisp
@@ -90,7 +82,6 @@ Below are example keybindings you might like to consider:
(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
* Getting Started
@@ -99,15 +90,69 @@ Below are example keybindings you might like to consider:
#+findex: org-remark-mark
#+findex: org-remark-open
#+findex: org-remark-view
+
+Once you have installed and set it up (refer to section
[[#installation][Installation]]), Org-remark is simple to use. Simply select
one[fn:1] and call =M-x org-remark-mark= to highlight a part of text. You will
see the selected text gets highlighted. That's it.
+
+To add or display the marginal notes for the highlight you have just marked,
place your cursor on the highlight and call =M-x org-remark-open= or =M-x
org-remark-view=. This will display a new buffer to the left of the current
buffer you are editing. The =open= command takes the cursor to the marginal
notes buffer to edit notes; whereas the =view= command keeps the cursor in the
current buffer only to display the marginal notes. Both commands narrow the
marginal notes file to the entry f [...]
+
+[fn:1] Set a mark and activate a region in Emacs terminology.
+
+** Navigating from One Highlight to Another
+
+#+findex: org-remark-view-next
+#+findex: org-remark-view-prev
+#+findex: org-remark-remove
+
+After you have added a couple of highlights in the text, you can jump around
to the next or previous highlights easily. Use =org-remark-view-next= and
=org-remark-view-prev= to brows the marginal notes as you move from one
highlight to another. They display the marginal notes on the side-window. Or
use =org-remark-next= and =org-remark-prev= if you simply move to though
highlights wihtout displaying marginal notes for them.
+
+To make it easy to navigate, you can use the same "prefix key" to Org-remark
commands, like this:
+
+- =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=
+
+The =C-c n= are the prefix key common to all of them. If you set the
keybindings like this, you can use =C-c n ]= once to view the next highlight,
and simply keep using a single key =]= or =[= to browse the next/previuos
highlights. After you have reached the one you like to act on, press =o= to
open it, or =r= to remove it.
+
+** Create Your Own Custom Highlighter Pens
+
+#+findex: org-remark-create
+#+findex: org-remark-mark-yellow
+#+findex: org-remark-mark-red-line
+
+Org-remark has a default highlighter pen function, and comes with a set of two
additional pens by default:
+
+- =org-remark-mark= :: default highlighter pen
+- =org-remark-mark-yellow= :: yellow highlight with "important" category in
the marginal notes entry
+- =org-remark-mark-red-line= :: wavy red underline with "review" category in
the marginal notes entry and "Review this" in tooltips
+
+Org-remark does not stop there; it lets you create your own custom pen
functions with =org-remark-create=. Use the yellow and red line pens as
examples, and create your own. Refer to [[#create-custom-pens][Create Your Own
Custom Pens]] for how to do it.
+
+This is it. It's all to get you started. For more detail, refer to the rest of
this user manual, especially the [[#usage][Usage]] and
[[#customizing][Customizing]] sections. There is more detail to the commands
introduced in this section and more ways in which you can customize Org-remark.
+
+* Usage
+:PROPERTIES:
+:CUSTOM_ID: usage
+:END:
+
+
#+cindex: Marginal notes file
#+cindex: Org-remark properties for highlights
-To highlight a part of text, simply select one[fn:1] and call =M-x
-org-remark-mark=. You will see the selected text gets highlighted. At the same
time Org-remark will automatically create a *marginal notes file*.
[[#customizing][By default]], it will be named =marginalia.org= and created in
the same directory as the file you are editing.
+** Highlighting and Annotating
+
+You can leave the marginal notes file as it is without writing any notes. In
this case, the entries in marginal notes file simply save the locations of your
highlighted text. After you quit Emacs, re-start it, and visit the same main
file, Org-remark uses this information to highlight the text again. You can
also directly edit the marginal notes file as a normal Org file.
+
-To display the marginal notes for the highlight you have marked, place your
cursor on the highlight and use =M-x org-remark-open= or =M-x org-remark-view=.
[[#customizing][By default]], it will display a new buffer to the left of the
current buffer you are editing. The =open= command takes the cursor to the
marginal notes buffer to edit notes; whereas the =view= command keeps the
cursor in the current buffer only to display the marginal notes. Both commands
narrow the marginal notes file [...]
+At the same time Org-remark will automatically create a *marginal notes file*.
+
+
+
+
+[[#customizing][By default]], it will be named =marginalia.org= and created in
the same directory as the file you are editing.
+
+[[#customizing][By default]]
-You do not need to add any notes. In this case, the entry in marginal notes
simply saves the location of the highlighted text. After you quit Emacs,
re-start it, and visit the same main file, Org-remark uses this information to
highlight the text. You can also directly edit the marginal notes file as a
normal Org file.
The important thing to note is that Org-remark uses following properties in
the property drawer of the headline to remember the highlights:
@@ -118,7 +163,7 @@ The important thing to note is that Org-remark uses
following properties in the
Essentially, the marginal notes file is a database in the plain text with
using Org mode. As a plain text database, you can easily edit these properties
manually if necessary.
-[fn:1] Set a mark and activate a region in Emacs terminology.
+
** Automatically Load Highlights after Re-starting Emacs
@@ -134,41 +179,8 @@ When activated, =org-remark-global-tracking-mode= will
also start remembering an
Without this global minor mode, you would need to remember to activate
=org-remark-mode= for each file where you add highlihgts and annotation. This
is often unpractical.
-** Create Your Own Custom Highlighter Pen
-
-#+vindex: org-remark-create-default-pen-set
-#+findex: org-remark-mark
-#+findex: org-remark-mark-yellow
-#+findex: org-remark-mark-red-line
-#+findex: org-remark-create
-
-Org-remark has a default highlighter pen function, and comes with a set of two
additional pens [[#customizing][by default]]:
-
-- =org-remark-mark= : default highlighter pen
-- =org-remark-mark-yellow=
-- =org-remark-mark-red-line=
-
-Org-remark lets you create your own custom pen functions with
=org-remark-create=. See how "red-line" and "yellow" pens are created. They are
meant to be a starter pack and examples.
-#+begin_src elisp
- (org-remark-create "red-line"
- '(:underline (:color "dark red" :style wave))
- '(CATEGORY "review" help-echo "Review this"))
- (org-remark-create "yellow"
- '(:underline "gold" :background "lemon chiffon")
- '(CATEGORY "important"))
-#+end_src
-#+ATTR_TEXINFO: :tag CAUTION
-#+begin_quote
-Don't use category (symbol) as a property -- it's a special one of text
properties. If you use it, the value also need to be a symbol; otherwise, you
will get an error. You can use CATEGORY (symbol and all uppercase), which will
result in CATEGORY in the property drawer in marginal notes Org files.
-#+end_quote
-
-
-* Usage
-:PROPERTIES:
-:TOC: :depth 0
-:END:
** Commands
- =org-remark-global-tracking-mode= ::
@@ -275,6 +287,42 @@ I will try to incorporate these into the package when I
have more time to focus
:CUSTOM_ID: customizing
:END:
+** Create Your Own Custom Highlighter Pen
+:PROPERTIES:
+:CUSTOM_ID: create-custom-pens
+:END:
+
+
+#+vindex: org-remark-create-default-pen-set
+#+findex: org-remark-mark
+#+findex: org-remark-mark-yellow
+#+findex: org-remark-mark-red-line
+#+findex: org-remark-create
+
+Org-remark has a default highlighter pen function, and comes with a set of two
additional pens [[#customizing][by default]]:
+
+- =org-remark-mark= : default highlighter pen
+- =org-remark-mark-yellow=
+- =org-remark-mark-red-line=
+
+Org-remark lets you create your own custom pen functions with
=org-remark-create=. See how "red-line" and "yellow" pens are created. They are
meant to be a starter pack and examples.
+
+#+begin_src elisp
+ (org-remark-create "red-line"
+ '(:underline (:color "dark red" :style wave))
+ '(CATEGORY "review" help-echo "Review this"))
+ (org-remark-create "yellow"
+ '(:underline "gold" :background "lemon chiffon")
+ '(CATEGORY "important"))
+#+end_src
+
+#+ATTR_TEXINFO: :tag CAUTION
+#+begin_quote
+Don't use category (symbol) as a property -- it's a special one of text
properties. If you use it, the value also need to be a symbol; otherwise, you
will get an error. You can use CATEGORY (symbol and all uppercase), which will
result in CATEGORY in the property drawer in marginal notes Org files.
+#+end_quote
+
+
+
- You can customize settings in the =org-remark= group.
- Highlight's face can be changed via =org-remark-highlighter=
- Remark file is defined by =org-remark-notes-file-path=
