branch: externals/org-remark
commit a55d0b7717d312b0e92ca4d2c48d733b3c68a5d5
Author: Noboru Ota <m...@nobiot.com>
Commit: Noboru Ota <m...@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 <m...@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 \]\)
