branch: externals/org-remark
commit 5e55f8757d4c62d74a10080deba13000a13007ce
Author: Noboru Ota <m...@nobiot.com>
Commit: Noboru Ota <m...@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 <m...@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."
