[elpa] externals/org-remark a55d0b7717 165/173: docs: README and user manaul

[ELPA Syncer]

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

    docs: README and user manaul
---
 README.org          | 16 ++++++++--------
 docs/org-remark.org | 51 +++++++++++++++++++++++++++++++--------------------
 org-remark.el       |  4 ++--
 3 files changed, 41 insertions(+), 30 deletions(-)

diff --git a/README.org b/README.org
index 6e1f636950..150774ef2a 100644
--- a/README.org
+++ b/README.org
@@ -35,15 +35,13 @@ For customization, refer to the customization group 
`org-transclusion' or user m
 * Screenshots :noexport:
 
 [[./resources/images/2022-01-22-Title.png]]
-*Figure 1*. Left: Org-mode with text enlarged; Right marginal notes with the 
inline image display on
-
-Refer to the screenshots below for a teaser of what it can do.
+*Figure 1*. Left: Org-mode with text enlarged; Right: marginal notes with an 
inline image
 
 [[./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 note can be any text files. Left: marginal notes file; Right: 
an ~org-remark.el~ file with a highlight.
+*Figure 3*. Main notes can be any text files. Left: marginal notes file; 
Right: an ~org-remark.el~ file with a highlight.
 
 * Installation
 :PROPERTIES:
@@ -65,7 +63,7 @@ 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~. 
+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:
 
@@ -99,14 +97,16 @@ Thank you.
 
 This work is licensed under a GPLv3 license. For a full copy of the license, 
refer to [[./LICENSE][LICENSE]].
 
-* org-remark :noexport:
+* Marginal Notes                                                   :noexport:
 :PROPERTIES:
 :org-remark-file: ~/src/org-remark/org-remark.el
 :END:
 
-** (defmacro org-remark-create
+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
 :PROPERTIES:
-:org-remark-beg: 4000
+:org-remark-beg: 4001
 :org-remark-end: 4027
 :org-remark-id: c759f435
 :org-remark-label: nil
diff --git a/docs/org-remark.org b/docs/org-remark.org
index a47d4fe0a1..3042ee11df 100644
--- a/docs/org-remark.org
+++ b/docs/org-remark.org
@@ -1,7 +1,7 @@
 #+title: Org-remark User Manual
 #+author: Noboru Ota <me@nobiot.com>
 #+macro: version 0.1.x
-#+macro: modified 22 January 2022
+#+macro: modified 23 January 2022
 
 #+language: en
 #+export_file_name: org-remark.texi
@@ -64,7 +64,7 @@ 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. You can control the timing of loading ~org-remark~ by 
autoloading some commands in similar ways as the example keybindings below.
+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:
 
@@ -94,7 +94,7 @@ 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
+#+cindex: Marginal notes file
 
 Once you have installed and set it up ([[#installation][Installation]]), 
Org-remark is simple to use. Select a part of text and call ~M-x 
org-remark-mark~ to highlight it. You will see the selected text gets 
highlighted.
 
@@ -106,26 +106,23 @@ To display the marginal notes for the highlight you have 
just marked, place your
 
 #+findex: org-remark-view-next
 #+findex: org-remark-view-prev
-#+findex: org-remark-remove
 #+cindex: Menu in the menu bar
 #+cindex: Context menu
 
-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.
+After you have added a couple of highlights in the text, you can move through 
the highlights easily. Use ~org-remark-view-next~ and ~org-remark-view-prev~ to 
browse 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:
+To make it easy for you 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~
+- ~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/previous 
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
+** Create Your Own Highlighter Pens
 
-#+findex: org-remark-create
-#+findex: org-remark-mark-yellow
-#+findex: org-remark-mark-red-line
+#+cindex: Custom highlighter pens
 
 Org-remark has a default highlighter pen function, and comes with a set of two 
additional pens by default:
 
@@ -133,21 +130,21 @@ Org-remark has a default highlighter pen function, and 
comes with a set of two a
 - ~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 tool-tips
 
-Org-remark let 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. [[#create-custom-pens][Create Your Own Custom Pens]] for how to do 
it. 
+Org-remark let 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. For how to do it, [[#create-custom-pens][How to Create Custom 
Highlighter Pens]].
 
-This is all you need to started. For more detail, refer to the rest of this 
user manual, especially [[#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. 
+This is all you need to get started. For more detail, refer to the rest of 
this user manual, especially [[#usage][Usage]] and 
[[#customizing][Customizing]] sections. There is more to the commands 
introduced in this section and more ways in which you can customize Org-remark. 
 
 * Usage
 :PROPERTIES:
 :CUSTOM_ID: usage
 :END:
 
-** Create Your Own Custom Highlighter Pen
+** How to Create Custom Highlighter Pens
 :PROPERTIES:
 :CUSTOM_ID: create-custom-pens
 :END:
 
-#+cindex: User-defined custom highlighter pen functions
+#+cindex: Custom highlighter pens
 #+cindex: Org-remark properties for highlights
 #+findex: org-remark-mark
 #+findex: org-remark-mark-yellow
@@ -211,7 +208,7 @@ Essentially, the marginal notes file is a database in the 
plain text with using
 
 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.
 
-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 (for how to create your own pens, 
[[#create-custom-pens][Create Your Own Custom Pens]]). 
+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 (for how to create your own pens, 
[[#create-custom-pens][How to Create Custom Highligh [...]
 
 ** =*marginal-notes*= Buffer
 
@@ -226,6 +223,8 @@ Org-remark displays the marginal notes buffer narrowed to 
the highlight the curs
 #+findex: org-remark-toggle
 #+findex: org-remark-change
 #+findex: org-remark-remove
+#+findex: org-remark-next
+#+findex: org-remark-prev
 
 - Command ~org-remark-toggle~ ::
   Toggle showing/hiding of highlights in current buffer.
@@ -240,6 +239,18 @@ This command will show you a list of available pens to 
choose from.
   It will remove the highlight and the properties from the marginal notes 
file, but will keep the headline and annotations. This is to ensure to keep any 
notes you might have written intact.
   You can let this command DELETE the entire heading subtree for the highlight 
along with the annotations you have written, by passing a universal argument 
with ~C-u~. If you have done so by error, you could still ~undo~ it in the 
marginal notes buffer, but not from within the current buffer as adding and 
removing overlays are not part of the undo tree.
 
+To navigate through highlights in the current buffer, you can use 
~org-remark-view-next~ / ~org-remark-view-prev~ or the following pair of 
commands. The former moves your cursor and displays the marginal notes buffer; 
the latter only moves your cursor.
+
+- Command ~org-remark-next~ ::
+  Move to the next highlight, if any.
+  If there is none below the point but there is a highlight in the buffer, 
cycle back to the first one.
+  After the point has moved to the next highlight, this command
+lets you move further by re-entering only the last letter like
+this example:  =C-n ] ] ] ] ]= (assuming this command is bound to C-n ])
+
+- Command ~org-remark-prev~ ::
+  Move to the previous highlight, if any.
+
 * Customizing
 :PROPERTIES:
 :CUSTOM_ID: customizing
diff --git a/org-remark.el b/org-remark.el
index 9ed904494b..38e75228c7 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -6,7 +6,7 @@
 ;; URL: https://github.com/nobiot/org-remark
 ;; Version: 0.1.0
 ;; Created: 22 December 2020
-;; Last modified: 22 January 2022
+;; Last modified: 23 January 2022
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, writing, note-taking, marginal-notes
 
@@ -435,7 +435,7 @@ buffer, cycle back to the first one.
 
 After the point has moved to the next highlight, this command
 lets you move further by re-entering only the last letter like
-this example:v
+this example:
 
    C-n \] \] \] \] \] \(assuming this command is bound to C-n \]\)