[elpa] externals/org-remark 4042e9434f 137/173: doc: User Manual first draft

[ELPA Syncer]

branch: externals/org-remark
commit 4042e9434f82bc06b0588fb18d5649240a8527a9
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>

    doc: User Manual first draft
---
 docs/org-remark-manual.org    | 250 +++++++++++++++---------------------------
 org-remark-global-tracking.el |   4 +-
 org-remark.el                 |   4 +-
 3 files changed, 93 insertions(+), 165 deletions(-)

diff --git a/docs/org-remark-manual.org b/docs/org-remark-manual.org
index e876fe8932..9b6182bf3d 100644
--- a/docs/org-remark-manual.org
+++ b/docs/org-remark-manual.org
@@ -21,7 +21,7 @@ This manual is for Org-remark version {{{version}}}.
 
 Last updated: {{{modified}}}.
 
-Org-remark lets you highlight and annote any text file with using Org mode.
+Org-remark lets you highlight and annotate any text file with using Org mode.
 
 #+texinfo: @insertcopying
 
@@ -90,10 +90,11 @@ Below are example keybindings you might like to consider:
 #+findex: org-remark-mark
 #+findex: org-remark-open
 #+findex: org-remark-view
+#+cindex: marginal notes file
 
-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.
+Once you have installed and set it up (refer to section 
[[#installation][Installation]]), Org-remark is simple to use. Select a part of 
text[fn:1] and call =M-x org-remark-mark= to highlight it. 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 [...]
+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 [...]
 
 [fn:1] Set a mark and activate a region in Emacs terminology.
 
@@ -103,7 +104,7 @@ To add or display the marginal notes for the highlight you 
have just marked, pla
 #+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.
+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 without displaying marginal notes for them.
 
 To make it easy to navigate, you can use the same "prefix key" to Org-remark 
commands, like this:
 
@@ -112,7 +113,7 @@ To make it easy to navigate, you can use the same "prefix 
key" to Org-remark com
 - =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.
+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/previous 
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
 
@@ -124,7 +125,7 @@ Org-remark has a default highlighter pen function, and 
comes with a set of two a
 
 - =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-mark-red-line=  :: wavy red underline with "review" category in 
the marginal notes entry and "Review this" in tool-tips
 
 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. 
 
@@ -135,202 +136,129 @@ This is it. It's all to get you started. For more 
detail, refer to the rest of t
 :CUSTOM_ID: usage
 :END:
 
+** Create Your Own Custom Highlighter Pen
+:PROPERTIES:
+:CUSTOM_ID: create-custom-pens
+:END:
 
-#+cindex: Marginal notes file
+#+cindex: user-defined custom highlighter pen functions
 #+cindex: Org-remark properties for highlights
+#+findex: org-remark-mark
+#+findex: org-remark-mark-yellow
+#+findex: org-remark-mark-red-line
+#+findex: org-remark-create
 
-** 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.
-
-
-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]]
+=org-remark-create= is a macro that lets create your own custom pen functions. 
Org-remark comes with two additional pens that are created by default. Use them 
as examples to learn how to create your own.
 
+#+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
 
-The important thing to note is that Org-remark uses following properties in 
the property drawer of the headline to remember the highlights:
+- Macro: org-remark-create label &optional face properties ::
+  Create and register new highlighter pen functions. The newly created pen 
function will be registered to variable =org-remark-available-pens=.  It is 
used by =org-remark-change= as a selection list.
 
-- :org-remark-beg:
-- :org-remark-end:
-- :org-remark-id:
-- :org-remark-label:
+  LABEL is the name of the highlighter and mandatory.  The function
+will be named =org-remark-mark-LABEL=.
 
-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.
+  The highlighter pen function will apply FACE to the selected region. FACE 
can be an anonymous face.  When FACE is nil, this macro uses the default face 
=org-remark-highlighter=.
 
+  PROPERTIES is a plist of pairs of a symbol and value. Each highlighted text 
region will have a corresponding Org headline in the notes file, and it can 
have additional properties in the property drawer from the highlighter pen.  To 
do this, prefix property names with "org-remark-" or use "CATEGORY".
 
+#+ATTR_TEXINFO: :tag NOTE
+#+begin_quote
+Don't use =category= (all lowercase, symbol) as a property -- it's a special 
one for text properties. If you use it, the value also need to be a symbol; 
otherwise, you will get an error. You can use =CATEGORY= (all uppercase, 
symbol), which will result in adding =CATEGORY= with the value in the property 
drawer in marginal notes Org files.
+#+end_quote
 
-** Automatically Load Highlights after Re-starting Emacs
+** Tracking to Automatically Load Highlights after Re-starting Emacs
 
 #+findex: org-remark-global-tracking-mode
 #+findex: org-remark-mode
 #+vindex: org-remark-tracking-file
 
-It is recommended that =org-remark-global-tracking-mode= be turned on as part 
of your Emacs initalization. This should be done before you start adding 
hightlights in any file. 
+It is recommended that =org-remark-global-tracking-mode= be turned on as part 
of your Emacs initialization. This should be done before you start adding 
highlights in any file. 
 
 Once you have added highlights to some files, quit Emacs, and re-start it, 
active =org-remark-global-tracking-mode= will automatically turn on 
=org-remark-mode= and load the highlights from your previous sessions for the 
files being globally tracked.
 
 When activated, =org-remark-global-tracking-mode= will also start remembering 
and tracking the files to which you add highlights and annotations. When you 
quit Emacs, it will save the tracked files in a file in your Emacs config 
directory (=user-emacs-directory=). [[#customizing][By default]], this file is 
named =.org-remark-tracking=.
 
-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. 
-
-
-
-** Commands
-
-- =org-remark-global-tracking-mode= ::
-A global minor mode to save and track files that have marginal notes.
-When active, visiting a file being tracked automatically turns on 
=org-remark-mode=, which loads highlights previously saved in the remark file.
-
-The files being tracked are saved in =org-remark-tracking-file=, which you can 
customize. The default file is named =.org-remark-tracking= in your Emacs 
configuration directory (=user-emacs-directory=).
-
-- =org-remark-mode= ::
-Org-remark is a local minor mode. Toggle it on/off with using 
=org-remark-mode=. On activating, it loads your saved highlights from the 
remark file (defined by =org-remark-notes-file-path=), and enables automatic 
saving of highlights. The automatic saving is achieved via function 
=org-remark-save= added to =after-save-hook=.
-
-- =org-remark-mark= ::
-Select a region of text, and call =org-remark-mark= to highlight the region. 
It will generate a new ID, and start tracking the location -- so you can edit 
text around the highlighted text. Do not cut, copy and paste as the highlight 
will disappear (you can immediately =undo= to recover the text region along the 
highlights). To create a new marginal note entry in the remark file, save the 
buffer.
-
-- =org-remark-save= ::
-By default, Org-remark automatically creates or updates corresponding entries 
in the remark file with location and text of highlights on saving the buffer. 
Nevertheless, you can manually call =org-remark-save= to do so (automatic 
process also call this command).
-
-If user option =org-remark-use-org-id= is non-nil, Org-remark will
-create a link back to the source note with using an Org-ID link instead of a
-normal file link.
-
-When a new remark file is created and =org-remark-use-org-id= is
-non-nil, Org-remark will add an ID property to the file level. This is mainly 
to support Org-roam's backlink feature for remark files.
-
-- =org-remark-open= ::
-Move your cursor on the highlighted text, and call =org-remark-open= to open 
the relevant margin notes in a separate window. Your cursor will move to the 
remark buffer narrowed to the relevant margin notes entry. You can edit the 
remark buffer as a normal Org buffer. Once you have done editing, you may 
simply save and close the it (kill it or close the window) as per your normal 
workflow. Technically, the remark buffer is a cloned indirect buffer of the 
remark file. 
+Without this global minor mode, you would need to remember to activate 
=org-remark-mode= for each file where you add highlights and annotation. This 
is often unpractical. 
 
-- =org-remark-load= ::
-This command visits the remark file and loads the saved highlights onto the 
current buffer. If there is no margin notes for it, it will output a message in 
the echo. Highlights tracked locally by Org-remark cannot persist when you kill 
the buffer, or quit Emacs. When you re-launch Emacs, ensure to turn on 
=org-remark-mode= to load the highlights. Loading is automatically done when 
you activate the minor mode.
+** Marginal Notes File
 
-- =org-remark-remove= ::
-This command removes the highlight at point. It will remove the highlight, and 
remove the properties from the remark, but will keep the headline and notes in 
tact.
-
-You can pass a universal argument (=C-u= by default). If this is the case, the 
command additionally deletes the entire heading subtree, along with the notes 
you have written, for the highlight.
-
-- =org-remark-next= ::
-Move to the next highlight if any. If there is none below the cursor, and 
there is a highlight above, loop back to the top one.
-If the point has moved to the next highlight, this function enables transient 
map with `set-transient-map'. You don't have to press the keybinding prefix 
again to move further to the next. That is, you can do a key sequence like this:
-
-   =C-c n ] ] ] ]=
-
-If you have the same prefix for `org-remark-prev', you can combine it in
-the sequence like so:
+#+cindex: marginal notes file
+#+cindex: Org-remark properties for highlights
 
-  =C-c n ] ] [ [=
-  This lets your cursor back to where you started (next next prev prev)
+When you mark a part of text with a highlighter pen function, 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.
 
-- =org-remark-prev= ::
-Move to the previous highlight if any. If there is none above the cursor, and 
there is a highlight below, loop back to the bottom one. This function enables 
transient map. See =org-remark-next= for detail.
+The important thing to note is that Org-remark uses following properties in 
the property drawer of the headline to remember the highlights:
 
-- =org-remark-toggle= ::
-Toggle showing/hiding of highlighters in current buffer. It only affects the 
display of the highlighters. When hidden, highlights' locations are still kept 
tracked; thus, upon buffer-save the correct locations are still recorded in the 
remark file.
+- :org-remark-beg:
+- :org-remark-end:
+- :org-remark-id:
+- :org-remark-label:
 
-** Keybindings Examples
+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.
 
-`Org-remark` only provides its mode map, and does not bind any keys to it. As 
an example, you could do something like this below.
+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.
 
-#+begin_src emacs-lisp
-(define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open)
-(define-key org-remark-mode-map (kbd "C-c m") #'org-remark-mark)
-(define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-next)
-(define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-prev)
-#+end_src
+In addition to the properties above that Org-remark reserves for itself, you 
can add your own custom properties and =CATEGORY= property. Use "org-remark-" 
as the prefix to the property names (or "CATEGORY", which is the only 
exception), and Org-remark put them to the property drawer of highlight's 
headline entry in the marginal notes buffer. Define the custom properties in 
your own custom pen functions (refer to [[create-custom-pens][Create Your Own 
Custom Pens]]). 
 
-** Composing Personal Workflow
+** \*marginal-notes\* Buffer
 
-Currently only "elementary" functions are defined in the package; for example, 
 =mark= , =save=, and =open= are all separate functions. You can string these 
together to compose a more fluid operation to suite your own workflow. A very 
useful set of such chained commands have been suggesetd by holtzermann17 in 
[[https://org-roam.discourse.group/t/prototype-org-remark-write-margin-notes-with-org-mode/1080/10][Org-roam's
 Discourse discussion]] (adjusted to reflect the change of the prefix f [...]
+#+cindex: *marginal notes* buffer
 
-I will try to incorporate these into the package when I have more time to 
focus on it -- I find them useful, but there are some plans I have had, and 
want to think of how I can incoprate these suggestions better with my ideas. 
+When you display the marginal notes with =org-remark-view= or 
=org-remark-open= for a given highlight, Org-remark creates a cloned indirect 
buffer visiting the marginal notes file. [[#customizing][By default]], it is a 
dedicated side-window opened to the left part of the current frame, and it is 
named \*marginal notes\*. You can change the behavior of =display-buffer= 
function and the name of the buffer.
 
-#+begin_src emacs-lisp
-  (defun org-remark-make-annotation ()
-    (interactive)
-    (let ((mark-end (region-end)))
-      (org-remark-mark (region-beginning) (region-end))
-      (org-remark-save)
-      (org-remark-open (1- mark-end))
-      (end-of-buffer)))
-
-  (define-key org-remark-mode-map (kbd "C-c M")
-    #'org-remark-make-annotation)
-
-  (defun org-remark-browse-forward ()
-    (interactive)
-    (let ((buf (current-buffer)))
-      (org-remark-next) (org-remark-open (point))
-      (pop-to-buffer buf nil t)))
-
-  (define-key org-remark-mode-map (kbd "C-c n }")
-    #'org-remark-browse-forward)
-
-  (defun org-remark-browse-backward ()
-    (interactive)
-    (let ((buf (current-buffer)))
-      (org-remark-prev) (org-remark-open (point))
-      (pop-to-buffer buf nil t)))
-
-  (define-key org-remark-mode-map (kbd "C-c n {")
-    #'org-remark-browse-backward)
-#+end_src
+Org-remark displays the marginal notes buffer narrowed to the highlight the 
cursor is on. 
 
 * Customizing
 :PROPERTIES:
 :CUSTOM_ID: customizing
 :END:
 
-** Create Your Own Custom Highlighter Pen
-:PROPERTIES:
-:CUSTOM_ID: create-custom-pens
-:END:
-
-
+#+vindex: org-remark-highlighter
 #+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
+#+vindex: org-remark-notes-display-buffer-action
+#+vindex: org-remark-notes-buffer-name
+#+vindex: org-remark-use-org-id
+#+vindex: org-remark-tracking-file
 
+Org-remark's user options are available in the =org-remark= group.
 
+- Face: org-remark-highlighter ::
+  Default face for =org-remark-mark=
 
-- 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=
-- Your files with marginal notes are saved and tracked in
-  =org-remark-tracking-file= (when tracking is turned on via the global
-  minor mode =org-remark-global-tracking-mode=)
-- You can use Org-ID to create links from marginal notes back to their main
-  notes when =org-remark-use-org-id= is on (default is on). This option also 
enables Org-remark to add an ID property when a new remark file is being 
created. This is to support seamless workflow with 
[[https://orgroam.com][Org-roam]].
+- Customizable variable: org-remark-create-default-pen-set ::
+  When non-nil, Org-remark creates default pen set. Set to nil if you prefer 
for it not to.
+  
+- Customizable variable: org-remark-notes-file-path ::
+  Define the file path to store the location of highlights and write 
annotations.
+The default is one file per directory.  Ensure that it is an Org
+file.
+
+- Customizable variable: org-remark-notes-display-buffer-action ::
+  Define how Org-remark opens the notes buffer.
+The default is to use a dedicated side-window on the left.  It is
+an action list for =display-buffer=.  Refer to its documentation
+for more detail and expected elements of the list.
+
+- Customizable variable: org-remark-notes-buffer-name ::
+  Define the buffer name of the marginal notes.
+=org-remark-open= creates an indirect clone buffer with this
+name.
+
+- Customizable variable: org-remark-use-org-id ::
+  Define if Org-remark use Org-ID to link back to the main note.
+
+- Customizable variable: org-remark-tracking-file ::
+  Define file path to save the files `org-remark' tracks.
+When `org-remark-global-tracking-mode' is active, opening a file
+saved in =org-remark-tracking-file= automatically loads highlights.
 
 * Known Limitations
 
@@ -338,7 +266,7 @@ Don't use category (symbol) as a property -- it's a special 
one of text properti
   
 - Undo highlight does not undo it :: Overlays are not part of the undo list; 
you cannot undo highlighting. Use =org-remark-remove= command instead.
   
-- Moving source files and remark file :: Move your files and remark file to 
another directory does not update the source path recorded in the remark file. 
It will be confusing. Try not to do this.
+- Moving source files and remark file :: Move your files and remark file to 
another directory does not update the source path recorded in the remark file. 
It will be confusing. Try not to do it.
 
 * Credits
 
diff --git a/org-remark-global-tracking.el b/org-remark-global-tracking.el
index 726ffa7c30..3974260cd0 100644
--- a/org-remark-global-tracking.el
+++ b/org-remark-global-tracking.el
@@ -5,7 +5,7 @@
 ;; Author: Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-remark
 ;; Created: 15 August 2021
-;; Last modified: 16 January 2022
+;; Last modified: 17 January 2022
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, writing, note-taking, marginal notes
 
@@ -34,7 +34,7 @@
 (defcustom org-remark-tracking-file
   (abbreviate-file-name
    (expand-file-name ".org-remark-tracking" user-emacs-directory))
-  "File name where the files `org-remark' tracks is saved.
+  "Define file path to save the files `org-remark' tracks.
 When `org-remark-global-tracking-mode' is active, opening a file
 saved in `org-remark-tracking-file' automatically loads highlights."
   :group 'org-remark
diff --git a/org-remark.el b/org-remark.el
index 0da0aefda9..c819811209 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -63,7 +63,7 @@ Set to nil if you prefer for it not to."
   :type 'boolean)
 
 (defcustom org-remark-notes-file-path "marginalia.org"
-  "Specify the file path to store the location of highlights and write 
annotations.
+  "Define the file path to store the location of highlights and write 
annotations.
 The default is one file per directory.  Ensure that it is an Org
 file."
   :type 'file)
@@ -125,7 +125,7 @@ The newly created pen function will be registered to 
variable
 `org-remark-available-pens'.  It is used by `org-remark-change'
 as a selection list.
 
-LABEL is the name of the highlighter and mandatoryy.  The function
+LABEL is the name of the highlighter and mandatory.  The function
 will be named `org-remark-mark-LABEL'.
 
 The highlighter pen function will apply FACE to the selected region.