[elpa] externals/org-remark 5e55f8757d 159/173: chg: menu squence; docs: add menu and context menu to user manual

[ELPA Syncer]

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

    chg: menu squence; docs: add menu and context menu to user manual
---
 README.org                 | 16 ++++-------
 docs/org-remark-manual.org | 68 ++++++++++++++++++++++++----------------------
 org-remark.el              | 46 +++++++++++++++----------------
 3 files changed, 63 insertions(+), 67 deletions(-)

diff --git a/README.org b/README.org
index 8e31cc2e0c..8c20391adb 100644
--- a/README.org
+++ b/README.org
@@ -23,11 +23,13 @@ This feature is designed to work automatically and 
transparently to you, meaning
 
 Org-remark lets you highlight and annotate any text file with using Org mode.
 
-A complete [[https://nobiot.github.io/org-remark/][user manual]] is available 
online (Info file will be available when Org-remark is added to ELPA/MELPA).
+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).
 
-For installation and minimum configuration, refer to 
[[#installation][Installation]] below or the corresponding section in the user 
manual.
+For installation and minimum configuration, refer to 
[[#installation][Installation]] below or the user manual: 
[[https://nobiot.github.io/org-remark/#Installation][online]].
 
-[[https://nobiot.github.io/org-remark/#getting-started][Getting Started]] in 
the user manual will get you started in 5 minutes.
+Getting Started in the user manual will get you started in 5 minutes: 
[[https://nobiot.github.io/org-remark/#getting-started][online]].
+
+For customization, refer to the customization group `org-transclusion' or user 
manual: [[https://nobiot.github.io/org-remark/#Customizing][online]].
 
 * Screenshots :noexport:
 
@@ -69,7 +71,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. 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:
 
@@ -117,9 +119,3 @@ This work is licensed under a GPLv3 license. For a full 
copy of the licese, refe
 :PROPERTIES:
 :org-remark-file: ~/src/org-remark/org-remark.el
 :END:
-
-** defun
-:PROPERTIES:
-:CATEGORY: correction
-:END:
-[[file:~/src/org-remark/org-remark.el::211][org-remark]]
diff --git a/docs/org-remark-manual.org b/docs/org-remark-manual.org
index 74bce92544..313cdb85ae 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 0.1.x
-#+macro: modified 18 January 2022
+#+macro: modified 22 January 2022
 
 #+language: en
 #+export_file_name: org-remark.texi
@@ -96,17 +96,19 @@ Below are example keybindings you might like to consider:
 #+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. 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.
+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.
 
-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 [...]
+Menu bar "Org-remark" is available to help you discover main commands. If you 
use Emacs version 28 or newer, a context menu is also available by right 
clicking the mouse. Turn on ~context-menu-mode~ for this.
 
-[fn:1] Set a mark and activate a region in Emacs terminology.
+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 [...]
 
 ** Navigating from One Highlight to Another
 
 #+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.
 
@@ -131,9 +133,9 @@ 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 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. 
+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. [[#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. 
+This is all now to get you 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. 
 
 * Usage
 :PROPERTIES:
@@ -145,7 +147,7 @@ This is it. It's all to get you started. For more detail, 
refer to the rest of t
 :CUSTOM_ID: create-custom-pens
 :END:
 
-#+cindex: user-defined custom highlighter pen functions
+#+cindex: User-defined custom highlighter pen functions
 #+cindex: Org-remark properties for highlights
 #+findex: org-remark-mark
 #+findex: org-remark-mark-yellow
@@ -177,7 +179,7 @@ This is it. It's all to get you started. For more detail, 
refer to the rest of t
 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
 
-** Tracking to Automatically Load Highlights after Re-starting Emacs
+** Automatically Turn on Highlights after Re-starting Emacs
 
 #+findex: org-remark-global-tracking-mode
 #+findex: org-remark-mode
@@ -187,7 +189,7 @@ It is recommended that ~org-remark-global-tracking-mode~ be 
turned on as part of
 
 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~.
+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~). By default, this file is named 
~.org-remark-tracking~ ([[#customizing][Customizing]]).
 
 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. 
 
@@ -196,7 +198,7 @@ Without this global minor mode, you would need to remember 
to activate ~org-rema
 #+cindex: marginal notes file
 #+cindex: Org-remark properties for highlights
 
-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.
+When you mark a part of text with a highlighter pen function, Org-remark will 
automatically create a *marginal notes file*. By default, it will be named 
~marginalia.org~ and created in the same directory as the file you are editing 
([[#customizing][Customizing]]).
 
 The important thing to note is that Org-remark uses following properties in 
the property drawer of the headline to remember the highlights:
 
@@ -209,13 +211,13 @@ 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 (refer to [[#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][Create Your Own Custom Pens]]). 
 
 ** =*marginal-notes*= Buffer
 
 #+cindex: *marginal notes* buffer
 
-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.
+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. 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 ([[#customizing][Customizing]]).
 
 Org-remark displays the marginal notes buffer narrowed to the highlight the 
cursor is on. 
 
@@ -231,40 +233,38 @@ Org-remark displays the marginal notes buffer narrowed to 
the highlight the curs
 #+vindex: org-remark-use-org-id
 #+vindex: org-remark-tracking-file
 
-Org-remark's user options are available in the ~org-remark~ group.
+Org-remark's user options are available in the customization group 
~org-remark~.
 
 - Face: ~org-remark-highlighter~ ::
   Default face for ~org-remark-mark~
 
-- Customizable variable: ~org-remark-create-default-pen-set~ ::
+- Option: ~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~ ::
+- Option: ~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.
+  The default is one file per directory. Ensure that it is an Org file.
 
-- Customizable variable: ~org-remark-notes-display-buffer-action~ ::
+- Option: ~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.
+  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~ ::
+- Option: ~org-remark-notes-buffer-name~ ::
   Define the buffer name of the marginal notes.
-~org-remark-open~ creates an indirect clone buffer with this
-name.
+  ~org-remark-open~ creates an indirect clone buffer with this name.
 
-- Customizable variable: ~org-remark-use-org-id~ ::
+- Option: ~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~ ::
+- Option: ~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.
+  When ~org-remark-global-tracking-mode~ is active, opening a file saved in
+ ~org-remark-tracking-file~ automatically loads highlights.
 
 * Known Limitations
 
+- No export together with the main file :: There is no out-of-the-box feature 
to export marginal notes together with the main file.  Nevertheless, the 
marginal notes is a normal Org file, thus if the main file is also an Org file, 
you could use the built-in =include= feature, for example, to include relevant 
parts of the marginal notes into the export output.
+
 - Copy & pasting loses highlights :: Overlays are not part of the kill; thus 
cannot be yanked.
   
 - Undo highlight does not undo it :: Overlays are not part of the undo list; 
you cannot undo highlighting. Use ~org-remark-remove~ command instead.
@@ -275,7 +275,7 @@ saved in ~org-remark-tracking-file~ automatically loads 
highlights.
 
 To create this package, I was inspired by the following packages. I did not 
copy any part of them, but borrowed some ideas from them -- e.g. saving the 
margin notes in a separate file.
 
-- [[https://github.com/jkitchin/ov-highlight][Ov-highlight]] :: John Kitchin's 
(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.
+- [[https://github.com/jkitchin/ov-highlight][Ov-highlight]] :: John Kitchin's 
(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.
   
 - [[https://github.com/bastibe/annotate.el][Annotate.el]] :: Bastian 
Bechtold's (author of Org-journal). Unique display of annotations right next to 
(or on top of) the text. It seems to be designed for very short annotations, 
and perhaps for code review (programming practice); I have seen recent issues 
reported when used with variable-pitch fonts (prose).
   
@@ -285,13 +285,15 @@ To create this package, I was inspired by the following 
packages. I did not copy
   
 - Transient navigation feature :: To implement the transient navigation 
feature, I liberally copied the relevant code from a wonderful Emacs package, 
[[https://github.com/rnkn/binder/blob/24d55db236fea2b405d4bdc69b4c33d0f066059c/binder.el#L658-L665][Binder]]
 by Paul W. Rankin (GitHub user [[https://github.com/rnkn][rnkn]]). 
 
-* Feedback
+* Contributing & Feedback
+
+Create issues, discussion, and/or pull requests in the GitHub repository. All 
welcome.
 
-Feedback welcome in this repo, or in 
[[https://org-roam.discourse.group/t/prototype-org-marginalia-write-margin-notes-with-org-mode/1080][Org-roam
 Discourse forum]]. 
+Feedback welcome in this repo, or in 
[[https://org-roam.discourse.group/t/prototype-org-marginalia-write-margin-notes-with-org-mode/1080][Org-roam
 Discourse forum]].
 
-* Contributing
+Org-transclusion is part of 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]]).
 
-To be added
+Thank you.
 
 * Index - Features
 :PROPERTIES:
diff --git a/org-remark.el b/org-remark.el
index 060a1232bb..1c07d584e7 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: 21 January 2022
+;; Last modified: 22 January 2022
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, writing, note-taking, marginal-notes
 
@@ -166,12 +166,12 @@ highlight.  In this case, no new ID gets generated."
        (add-to-list 'org-remark-available-pens
                     (intern (format "org-remark-mark-%s" ,label)))
 
-       ;; Add custom pens to the minor-mode menu
+       ;; Add the custom pen function to the minor-mode menu
        (define-key-after org-remark-pen-map
          [,(intern (format "org-remark-mark-%s" label))]
          '(menu-item ,(format "%s pen" label) ,(intern (format 
"org-remark-mark-%s" label))))
 
-       ;; Add custom pen change function for the minor-mode menu
+       ;; Add the custom pen change function to the minor-mode menu
        (define-key-after org-remark-change-pen-map
          [,(intern (format "org-remark-change-to-%s" label))]
          '(menu-item ,(format "%s pen" label)
@@ -244,14 +244,6 @@ recommended to turn it on as part of Emacs initialization.
 (defvar org-remark-menu-map
   (make-sparse-keymap "Org-remark"))
 
-(define-key-after org-remark-menu-map
-  [org-remark-view-next]
-  '(menu-item "View next" org-remark-view-next))
-
-(define-key-after org-remark-menu-map
-  [org-remark-view-prev]
-  '(menu-item "View previous" org-remark-view-prev))
-
 (define-key-after org-remark-menu-map
   [org-remark-open]
   '(menu-item "Open" org-remark-open))
@@ -261,8 +253,12 @@ recommended to turn it on as part of Emacs initialization.
   '(menu-item "View" org-remark-view))
 
 (define-key-after org-remark-menu-map
-  [org-remark-change]
-  '(menu-item "Change" org-remark-change))
+  [org-remark-view-next]
+  '(menu-item "View next" org-remark-view-next))
+
+(define-key-after org-remark-menu-map
+  [org-remark-view-prev]
+  '(menu-item "View previous" org-remark-view-prev))
 
 (define-key-after org-remark-menu-map
   [org-remark-toggle]
@@ -272,10 +268,6 @@ recommended to turn it on as part of Emacs initialization.
   [org-remark-remove]
   '(menu-item "Remove" org-remark-remove))
 
-(define-key org-remark-mode-map
-            [menu-bar org-remark]
-            (list 'menu-item "Org-remark" org-remark-menu-map))
-
 ;; Make pen functions menu
 (defvar org-remark-pen-map
   (make-sparse-keymap "Org-remark-mark"))
@@ -294,18 +286,21 @@ recommended to turn it on as part of Emacs initialization.
                           (interactive)
                           (org-remark-change #'org-remark-mark))))
 
+;; Add change menu to the parent menu
+(define-key-after org-remark-menu-map
+  [org-remark-change-pens]
+  (list 'menu-item "Change pen to..." org-remark-change-pen-map)
+  'org-remark-toggle)
 
-;; FIXME somehow the change goes below other menu items
-;; Add change menu to the main menu
-(define-key org-remark-menu-map
-            [org-remark-change]
-            (list 'menu-item "Change pen to..." org-remark-change-pen-map))
-
-;; Add pen menu to the main menu
+;; Add pen menu to the parent menu
 (define-key org-remark-menu-map
             [org-remark-pens]
             (list 'menu-item "Highlight with..." org-remark-pen-map))
 
+;; Add all to the main menu
+(define-key org-remark-mode-map
+            [menu-bar org-remark]
+            (list 'menu-item "Org-remark" org-remark-menu-map))
 
 
 ;;;; Other Commands
@@ -816,6 +811,9 @@ Minimal properties are:
 - org-remark-source-beg :: BEG
 - org-remark-source-end :: END
 
+And the following are also reserved for Org-remark:
+- org-remark-link
+
 For PROPS, if the property name is CATEGORY \(case-sensitive\) or
 prefixed with \"org-remark-\" set them to to headline's property
 drawer."