[elpa] externals/org-remark 76e5a4f915 136/173: docs: WIP

[ELPA Syncer]

branch: externals/org-remark
commit 76e5a4f9151e2a737f66129e2202a28cc73bc4b2
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@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 <me@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=