[elpa] externals/org-remark 0db912919a 163/173: docs: update Makefile, README and user manual

[ELPA Syncer]

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

    docs: update Makefile, README and user manual
---
 .elpaignore                                    |  9 ++++
 .gitignore                                     |  5 ++-
 CHANGELOG                                      | 37 ++++++++++++++++
 Makefile                                       | 14 +++++--
 README.org                                     |  1 +
 demo/custom-pens.el                            |  6 +++
 demo/demo.txt                                  | 38 +++++++++++++++++
 demo/marginalia.org                            | 58 ++++++++++++++++++++++++--
 docs/marginalia.org                            | 22 ++++++++++
 docs/{org-remark-manual.org => org-remark.org} | 31 +++++++++++---
 org-remark.el                                  | 13 +++---
 11 files changed, 213 insertions(+), 21 deletions(-)

diff --git a/.elpaignore b/.elpaignore
new file mode 100644
index 0000000000..f143c8b8de
--- /dev/null
+++ b/.elpaignore
@@ -0,0 +1,9 @@
+demo
+test
+docs
+resources
+Makefile
+.gitignore
+.elpaignore
+.github
+.dir-locals.el
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index e2b91d9138..5953ca07fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,5 +4,6 @@
 
 *.elc
 
-/demo/2020-12-24_10-00-13.png
-/demo/Copy of 2020-12-24_10-00-13.png
+test
+test*
+
diff --git a/CHANGELOG b/CHANGELOG
new file mode 100644
index 0000000000..e1d621bdf1
--- /dev/null
+++ b/CHANGELOG
@@ -0,0 +1,37 @@
+** 0.0.6
+
+Feature:
+- feat: Add =org-marginalia-global-tracking-mode= with a separate .el file
+- feat: Use Org-ID to create a link from the marginal notes back to the main 
file
+  Add Customizable variable =org-marginalia-use-org-id=; default is =t=
+
+Change:
+- chg: Highlights are now overlay; no longer text-properties
+
+Improvement to existing functions
+- add: Deactivate mark after highlighting
+- add: org-marginalia-remove can take C-u to delete
+
+Fix & Internal Refactor
+- intrnl: Add housekeeping for =org-marginalia-highlights= variable
+- fix: org-id-uuid is not found
+- fix: Add highlighter face def for terminal
+
+** 0.0.5
+- break: Replace the prefix "om/" in the source code with "org-marginalia"
+- break: Remove default keybindings; add examples in readme instead. Addresses 
[#3](https://github.com/nobiot/org-marginalia/issues/3)
+
+** 0.0.4
+- feat: Add transient navigation to next/prev
+  See [[*Credits][§ Credits]] for the piece of code to achieve the transient 
map I used.
+
+** 0.0.3
+- feat: Add om/toggle for show/hide highlighters
+
+** 0.0.2
+- feat: Add om/next and /prev
+- break: Change om/open-at-point to org-marginalia-open
+- break: Change om/save-all to org-marginalia-save
+
+** 0.0.1
+Initial alpha release. I consider it to be the minimal viable scope.
diff --git a/Makefile b/Makefile
index 14bd50fd27..2c9ef4f47d 100644
--- a/Makefile
+++ b/Makefile
@@ -1,12 +1,18 @@
-org-remark.org: docs/org-remark-manual.org
-       -emacs --batch -L ../org-transclusion -l org-transclusion $< \
-              --eval '(progn (org-transclusion-add-all) (write-region nil nil 
"org-transclusion.org"))'
+# For ELPA, below should be added to the spec:
+# ("org-remark"        :url "https://github.com/nobiot/org-remark";
+#  :make "README-elpa"
+#  :doc "docs/org-remark.org"
+#  :auto-sync t)
+
+README-elpa: README.org
+       -emacs --batch $< -f org-ascii-export-to-ascii
+       -mv README.txt README-elpa
 
 .PHONY: test-compile
 test-compile:
        emacs --batch --eval "(add-to-list 'load-path default-directory)" \
              -f batch-byte-compile ./*.el
-       # Check declare-function
+# Check declare-function
        emacs --batch --eval "(check-declare-directory default-directory)"
 
 .PHONY: clean
diff --git a/README.org b/README.org
index 138446d454..48078d0316 100644
--- a/README.org
+++ b/README.org
@@ -1,4 +1,5 @@
 #+title: README – Org-remark
+#+options: toc:t cretor:nil author:nil broken-links:t
 
 #+html: <a href="https://www.gnu.org/software/emacs/";><img alt="GNU Emacs" 
src="https://img.shields.io/static/v1?logo=gnuemacs&logoColor=fafafa&label=Made%20for&message=GNU%20Emacs&color=7F5AB6&style=flat"/></a>
 #+html: <img alt="GPLv3" 
src="https://img.shields.io/badge/License-GPLv3-blue.svg";>
diff --git a/demo/custom-pens.el b/demo/custom-pens.el
new file mode 100644
index 0000000000..de7d80e467
--- /dev/null
+++ b/demo/custom-pens.el
@@ -0,0 +1,6 @@
+(org-remark-create "memorize"
+                   '(:foreground "white" :underline "black")
+                   '(CATEGORY "exam"))
+
+(org-remark-create "magenda"
+                   '(modus-themes-nuanced-magenta))
diff --git a/demo/demo.txt b/demo/demo.txt
index e296d96b98..d43bd66cc0 100644
--- a/demo/demo.txt
+++ b/demo/demo.txt
@@ -6,3 +6,41 @@
 
    † Name chagned from
       Org-marginalia
+
+---
+
+Art Nouveau
+Source: https://en.wikipedia.org/wiki/Art_Nouveau
+
+Art Nouveau (/ˌɑːrt nuːˈvoʊ, ˌɑːr/; French: [aʁ nuvo]) is an international 
style of art, architecture, and applied art, especially the decorative arts, 
known in different languages by different names: Jugendstil in German, Stile 
Liberty in Italian, Modernisme català in Catalan, etc. In English it is also 
known as the Modern Style. The style was most popular between 1890 and 1910 
during the Belle Époque period that ended with the start of World War I in 
1914.[1] It was a reaction against  [...]
+
+One major objective of Art Nouveau was to break down the traditional 
distinction between fine arts (especially painting and sculpture) and applied 
arts. It was most widely used in interior design, graphic arts, furniture, 
glass art, textiles, ceramics, jewellery and metal work.
+
+The mouvement responded to Viollet le Duc’s theories on rationalism which 
derided from his study of medieval art :
+
+- Function should define form[4].
+
+- Unity of the arts and the abolition of any distinction between major art 
(architecture) and minor arts (decorative arts).[5]
+
+- Nature’s logique is the model to be used for architecture[6].
+
+- Architecture should adapt itself to man’s environment and needs.
+
+- Use of modern technologie and materials [7]. 
+
+---
+
+Custom pens
+
+Example 1
+
+| (org-remark-create "magenda"     
+|                    '(modus-themes-nuanced-magenta)) 
+
+
+Example 2
+  
+| (org-remark-create "memorize"
+|                   '(:foreground "white" :underline "black")
+|                   '(CATEGORY "exam"))
+
diff --git a/demo/marginalia.org b/demo/marginalia.org
index 7be90a79ca..05a25297bc 100644
--- a/demo/marginalia.org
+++ b/demo/marginalia.org
@@ -56,7 +56,7 @@ Marginalia from Opticks or, A treatise of the reflexions, 
refractions, inflexion
 :org-remark-end: 113
 :org-remark-id: 76539dd9
 :org-remark-label: nil
-:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::8]]
+:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::32]]
 :END:
 
 *** Pronunciation
@@ -77,7 +77,7 @@ Marginalia from Opticks or, A treatise of the reflexions, 
refractions, inflexion
 :org-remark-id: 6a4de876
 :org-remark-label: yellow
 :CATEGORY: important
-:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::5]]
+:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::32]]
 :END:
 
 ** Highlight
@@ -86,5 +86,57 @@ Marginalia from Opticks or, A treatise of the reflexions, 
refractions, inflexion
 :org-remark-end: 31
 :org-remark-id: 4d94d0fb
 :org-remark-label: blue
-:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::4]]
+:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::32]]
+:END:
+
+** Belle Époque period
+:PROPERTIES:
+:org-remark-beg: 576
+:org-remark-end: 595
+:org-remark-id: ec7d2487
+:org-remark-label: blue
+:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::32]]
+:END:
+
+** 1890 and 1910
+:PROPERTIES:
+:org-remark-beg: 551
+:org-remark-end: 564
+:org-remark-id: 43249761
+:org-remark-label: memorize
+:CATEGORY: exam
+:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::15]]
+:END:
+
+** Catalan
+:PROPERTIES:
+:org-remark-beg: 453
+:org-remark-end: 460
+:org-remark-id: 934e0174
+:org-remark-label: memorize
+:CATEGORY: exam
+:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::15]]
+:END:
+
+** Modern Style
+:PROPERTIES:
+:org-remark-beg: 502
+:org-remark-end: 514
+:org-remark-id: 69bdf5cb
+:org-remark-label: magenda
+:org-remark-link: [[file:~/src/org-remark/demo/demo.txt::15]]
+:END:
+
+* custom-pens
+:PROPERTIES:
+:org-remark-file: ~/src/org-remark/demo/custom-pens.el
+:END:
+
+** org-remark-create
+:PROPERTIES:
+:org-remark-beg: 133
+:org-remark-end: 150
+:org-remark-id: 8a255247
+:org-remark-label: magenda
+:org-remark-link: [[file:~/src/org-remark/demo/custom-pens.el::5]]
 :END:
diff --git a/docs/marginalia.org b/docs/marginalia.org
new file mode 100644
index 0000000000..192fa7b60e
--- /dev/null
+++ b/docs/marginalia.org
@@ -0,0 +1,22 @@
+:PROPERTIES:
+:ID:       2022-01-15T093859
+:END:
+
+* Org-remark User Manual
+:PROPERTIES:
+:org-remark-file: ~/src/org-remark/docs/org-remark.org
+:END:
+
+** TODO vindex
+:PROPERTIES:
+:CATEGORY: important
+:END:
+
+- (defcustom org-remark-create-default-pen-set t
+
+                                                             
+- [ ] #+vindex: org-remark-notes-file-path
+
+- [ ] #+vindex: org-remark-notes-display-buffer-action
+
+                                                              - (defcustom 
org-remark-notes-buffer-name "*marginal notes*"                                 
                            - (defcustom org-remark-use-org-id nil              
                                                
diff --git a/docs/org-remark-manual.org b/docs/org-remark.org
similarity index 83%
rename from docs/org-remark-manual.org
rename to docs/org-remark.org
index 313cdb85ae..a47d4fe0a1 100644
--- a/docs/org-remark-manual.org
+++ b/docs/org-remark.org
@@ -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. 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 similar ways as the example keybindings below.
 
 Below are example keybindings you might like to consider:
 
@@ -98,9 +98,9 @@ Below are example keybindings you might like to consider:
 
 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.
 
-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.
+The menu bar item "Org-remark" is available when you turn on 
~org-remark-mode~. It helps you discover Org-remark's main commands. If you use 
Emacs version 28 or newer, a context menu is also available by right click of 
your mouse. Turn on the Emacs built-in ~context-menu-mode~ to enable the 
context menu.
 
-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 [...]
+To 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 for you 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 entr [...]
 
 ** Navigating from One Highlight to Another
 
@@ -133,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. [[#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. [[#create-custom-pens][Create Your Own Custom Pens]] for how to do 
it. 
 
-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. 
+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. 
 
 * Usage
 :PROPERTIES:
@@ -195,7 +195,7 @@ Without this global minor mode, you would need to remember 
to activate ~org-rema
 
 ** Marginal Notes File
 
-#+cindex: marginal notes file
+#+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*. By default, it will be named 
~marginalia.org~ and created in the same directory as the file you are editing 
([[#customizing][Customizing]]).
@@ -221,6 +221,25 @@ When you display the marginal notes with ~org-remark-view~ 
or ~org-remark-open~
 
 Org-remark displays the marginal notes buffer narrowed to the highlight the 
cursor is on. 
 
+** Other Commands
+
+#+findex: org-remark-toggle
+#+findex: org-remark-change
+#+findex: org-remark-remove
+
+- Command ~org-remark-toggle~ ::
+  Toggle showing/hiding of highlights in current buffer.
+  If you would like to hide/show the highlights in the current buffer, it is 
recommended to use this command instead of ~org-remark-mode~. This command only 
affects the display of the highlights and their locations are still kept 
tracked.  Toggling off ~org-remark-mode~ stops this tracking completely, which 
will likely result in inconsistency between the marginal notes file and the 
current main buffer.
+
+- Command ~org-remark-change~ ::
+  Change the highlight at point to one by another pen.
+This command will show you a list of available pens to choose from.
+
+- Command ~org-remark-remove~ ::
+  Remove the highlight at point.
+  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.
+
 * Customizing
 :PROPERTIES:
 :CUSTOM_ID: customizing
diff --git a/org-remark.el b/org-remark.el
index e08f459173..9ed904494b 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -480,12 +480,13 @@ the sequence like so:
 
 (defun org-remark-toggle ()
   "Toggle showing/hiding of highlights in current buffer.
-This function only affects the display of the highlights.  Their
-locations are still kept tracked.  On buffer-save the correct
-locations are to be saved in the marginal notes file when the
-highlights are hidden, thus it is recommended to use this
-function, instead of `org-remark-mode', if you would just like to
-hide the highlights."
+  If you would like to hide/show the highlights in the current
+  buffer, it is recommended to use this command instead of
+  `org-remark-mode'. This command only affects the display of the
+  highlights and their locations are still kept tracked.
+  Toggling off ~org-remark-mode~ stops this tracking completely,
+  which will likely result in inconsistency between the marginal
+  notes file and the current main buffer."
   (interactive)
   (if org-remark-highlights-hidden
       (org-remark-highlights-show)