[elpa] externals/org-remark 09d95e7519 20/67: Merge branch 'main' into dev/nov.el

[ELPA Syncer]

branch: externals/org-remark
commit 09d95e751987597c35e44c5fb26e9b2746f51b3c
Merge: e1b7a3a1ba f603ad6769
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>

    Merge branch 'main' into dev/nov.el
---
 CHANGELOG                     |  54 ++++++++++++++++
 NEWS                          | 141 ++++++++++++++++++++++++++----------------
 README.org                    |  60 +++++++++---------
 docs/org-remark.org           |  28 ++++++++-
 org-remark-eww.el             |   2 +-
 org-remark-global-tracking.el |   2 +-
 org-remark.el                 |   4 +-
 7 files changed, 203 insertions(+), 88 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index e1d621bdf1..db0db84d3b 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,57 @@
+[More recent changes v1.0.0 are in NEWS file]
+
+Version 0.2.0
+  - add: org-remark-delete
+  - rm: Adding Org-ID automatically to file level when file is empty
+
+Version 0.1.0
+* Features & additions
+
+  - docs: comprehensive user manual (online - Info to be added on ELPA release)
+
+  - feat: org-remark-create macro to let users create their own custom pens
+
+  - feat: minor-mode menu for menu-bar-mode
+
+          This works as mouse context-menu for the new context-menu-mode (>=
+          Emacs 28)
+
+  - add: browse-next/prev: move and display next/prev marginal notes at the 
same
+         time
+
+  - add: view/open to display side-window by default (user option)
+
+  - add: org-remark-link property in marginal notes file with ::line-number
+         search option
+
+  - feat: org-remark-legacy-convert as a separate feature
+
+          This is for automatically converting legacy Org-marginalia file to
+          Org-remark.
+
+  - feat: Legacy data facility with org-remark-tracking
+
+* Changes
+
+  - chg: `remove' (and delete) only removes one highlight at a time instead of
+         remove all at point
+
+  - chg: Save marginal notes on `mark' instead of wainting for `save'
+
+  - chg: define org-remark-mark explicitly for autoload cookie
+
+  - chg: `org-remark-view' and `org-remark-open'. View will stay in the
+          current main note; open will move the cursor to the marginal notes
+          buffer for further editing.
+
+  - chg: When updating the existing headline and position properties, don't
+         update the headline text when it already exists. Let the user decide
+         how to manage headlines.
+
+  - doc: copyright assignment to FSF; copyright years
+
+* Alpha
+
 ** 0.0.6
 
 Feature:
diff --git a/NEWS b/NEWS
index 6cda4aef05..38deb4e40d 100644
--- a/NEWS
+++ b/NEWS
@@ -1,7 +1,91 @@
-Development
+Version 1.1.0-rc -- Current development version
+
+  Features:
+
+  - feat: notes-and-source sync
+          Previously, Org-remark was designed to create/update/delete
+          highlights from the source buffer to its marginal notes
+          buffer; this was always one-way from the source to the notes.
+
+          Now we have implemented the updating process in the other
+          direction from the notes to source.
+
+          Functionally, we currently have echo-text/tooltip containing
+          an excerpt from the body of notes from the notes buffer
+          (thanks to @mooseyboots).
+
+          Other than this additional feature, there should be no visible
+          change for end users.  The update should all happen
+          transparently behind the scenes with no to little change for
+          end users of Org-remark.
+
+  - feat: echo-text update from the marginal notes to the source buffer
+          This is a code contribution by marty hiatt (@mooseyboots).  He
+          has done FSF copyright assignment in July, 2022.
+
+          Now the source buffer can Display annotation text as help-echo
+          or tooltip. Thank you, @mooseyboots.
+
+          This has opened up an avenue to implement "notes sync" feature
+          which updates select elements of marginal notes buffer back
+          into the source buffer for highlight overlays.
+
+  - feat: Extend support for non-file-visiting buffer
+          We now have an approach to extend Org-remark to support
+          non-file-visiting buffers of various modes.  Currently it is
+          assumed that the support is to be implemented per mode
+          basis. We have support for EWW with 'org-remark-eww-mode' and
+          its dedicated file and feature 'org-remark-eww'. Refer to its
+          implementation as a reference as to how this approach is
+          currently practiced.
+
+  - feat: Global minor mode org-remark-eww-mode
+          Support taking annotations in eww buffers for websites A new
+          feature contributed by Vedang Manerikar (@vedang).  He has
+          completed FSF paperwork in May, 2022 and received a PDF
+          regarding the same from the FSF.
+
+          This has opened up a big new avenue to support highlights in
+          non-file visiting buffers. Thank you @vedang.
+
+          EWW support is modularized in a separate file
+          'org-remark-eww.el'.
+
+          org-remark-link: prop for EWW
+          Now 'org-remark-link' property in the marginal notes buffer
+          contains the URL that you can follow for the source website.
+
+  - add: org-remark-open-hook #40
+         Hook run when a note buffer is opened/visited. The current
+         buffer is the note buffer.
+
+  Fixes:
+
+  - refactor: change the default colors of yellow pen #52
+         This is to cater to users who have dark theme that may render
+         the highlighted text illegible due to the default background
+         color of yellow.
+
   - fix: Text cut off in notes if the highlight spans across two lines #56
-    Thanks to GitHub user @sati-bodhi for reporting and suggesting a fix
-    (code implemented by nobiot)
+         Thanks to GitHub user @sati-bodhi for reporting and suggesting a fix
+         (code implemented by nobiot). Thank you @sati-bodhi.
+
+  - fix: issue #44 change CATEGORY
+         Now CATEGORY property from the highlight can be properly
+         deleted if a new pen does not have CATEGORY.
+
+  - fix: case for highlight-get-text empty notes at the bottom of buffer
+
+  - fix: text-property org-remark-label to be symbol
+         Fixes the error when you do 'describe-text-properties' on the
+         highlight overlay
+
+  - fix: move org-remark-source-find-file-name to tracking
+         After EWW support, 'org-remark-source-get-file-name' is now
+         moved to 'org-remark-global-tracking.el' file
+
+  - fix: source-file-name incorrect issue #39
+         PR #38 by Nan Jun Jie (@nanjj).  Thank you @nanjj.
 
 Version 1.0.5
   - fix #28 toggle causes error on saving highlights
@@ -77,53 +161,4 @@ Version 1.0.0
          returns a file name like this: "FILE-notes.org" by adding
          "-notes.org" as a suffix to the file name without the extension.
 
-
-Version 0.2.0
-  - add: org-remark-delete
-  - rm: Adding Org-ID automatically to file level when file is empty
-
-Version 0.1.0
-* Features & additions
-
-  - docs: comprehensive user manual (online - Info to be added on ELPA release)
-
-  - feat: org-remark-create macro to let users create their own custom pens
-
-  - feat: minor-mode menu for menu-bar-mode
-
-          This works as mouse context-menu for the new context-menu-mode (>=
-          Emacs 28)
-
-  - add: browse-next/prev: move and display next/prev marginal notes at the 
same
-         time
-
-  - add: view/open to display side-window by default (user option)
-
-  - add: org-remark-link property in marginal notes file with ::line-number
-         search option
-
-  - feat: org-remark-legacy-convert as a separate feature
-
-          This is for automatically converting legacy Org-marginalia file to
-          Org-remark.
-
-  - feat: Legacy data facility with org-remark-tracking
-
-* Changes
-
-  - chg: `remove' (and delete) only removes one highlight at a time instead of
-         remove all at point
-
-  - chg: Save marginal notes on `mark' instead of wainting for `save'
-
-  - chg: define org-remark-mark explicitly for autoload cookie
-
-  - chg: `org-remark-view' and `org-remark-open'. View will stay in the
-          current main note; open will move the cursor to the marginal notes
-          buffer for further editing.
-
-  - chg: When updating the existing headline and position properties, don't
-         update the headline text when it already exists. Let the user decide
-         how to manage headlines.
-
-  - doc: copyright assignment to FSF; copyright years
+[Older changes before v1.0.0 are in CHANGELOG file]
diff --git a/README.org b/README.org
index e653ebf66c..87ad5d35d2 100644
--- a/README.org
+++ b/README.org
@@ -4,25 +4,14 @@
 #+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";>
 
-* ❦❦❦ IMPORTANT NOTICE ❦❦❦ :noexport:
+* Breaking Changes :noexport:
 
-[This notice written on 18 January 2022]
-
-Happy 2022!
-
-I have changed the name of the project and package to "*Org-remark*" from 
Org-marginalia.
-
-If you are using Org-marginalia now, there are breaking changes. This package 
includes the feature that automatically converts the old Org-marginalia data 
into the new Org-remark data. Add ~org-remark-convert-legacy~ feature like this:
-
-#+begin_src elisp
-  (require 'org-remark-convert-legacy)
-#+end_src
-
-This feature is designed to work automatically and transparently to you, 
meaning you should not have to do anything, as long as you did not customize 
~org-marginala-notes-file-path~. If you did, you also need to customize 
~org-remark-notes-file-path~. You can also manually do data conversion if you 
wish. For more detail, refer to the docstring of function 
~org-remark-convert-legacy-data~.
+- [18 January 2022] Package name change from Org-marginalia to Org-remark. See 
[[https://github.com/nobiot/org-remark/issues/11#issuecomment-1382824948][detail
 on data conversion]]. In most cases, no action is required for you.
 
 * Introduction
 
-Org-remark lets you highlight and annotate any text file with using Org mode.
+Org-remark lets you highlight and annotate text files and websites with
+using Org mode [fn:1].
 
 A user manual is available [[https://nobiot.github.io/org-remark/][online]] or 
Emacs in-system as an Info node `(org-remark)': (~C-h i~ and find the 
=Org-remark= node).
 
@@ -34,6 +23,16 @@ For customization, refer to the customization group 
`org-remark' or user manual:
 
 An [[https://youtu.be/c8DHrAsFiLc][introductory video]] (8 minutes) is 
available on YouTube.
 
+[fn:1]: Feature to highlight and annotate websites is new in the latest 
[[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] and is planned 
to be part of v1.1.0.
+
+* Features
+
+- Highlight and annotate any text file. The highlights and notes are kepted in 
an Org file as the plain text database. This lets you easily manage your 
marginal notes and use the built-in Org fecilities on them -- e.g. create a 
sparse tree based on the category of the notes
+
+- Have the same highlighting and annotating functionality for websites when 
you use EWW to browse them (new in latest 
[[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] and is planned 
to be part of v1.1.0.)
+
+- Create your your own highlighter pens with different colors, type (e.g. 
underline, squiggle, etc. optionally with Org's category for search and filter 
on your highlights and notes)
+
 * Screenshots and Videos                                           :noexport:
 
 [[./resources/images/2022-01-22-Title.png]]
@@ -66,8 +65,11 @@ GNU ELPA should be already set up in your Emacs by default. 
If you wish to add G
 After installation, we suggest you put the setup below in your configuration.
 
 #+begin_src emacs-lisp
-  (require 'org-remark-global-tracking)
   (org-remark-global-tracking-mode +1)
+
+  ;; Optional if you would like to highlight websites via eww-mode
+  (with-eval-after-load 'eww
+    (org-remark-eww-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 a similar way with the example keybindings below.
@@ -96,6 +98,20 @@ Org-remark is available on GNU ELPA and thus copyrighted by 
the [[http://fsf.org
 
 Thank you.
 
+* Contributors
+- New features ::
+- ~echo-text~ update from the marginal notes to the source buffer by marty 
hiatt (@mooseyboots)
+- Support for websites with ~eww-mode~ by Vedang Manerikar (@vedang)
+
+- Bug fixes ::
+Nan Jun Jie (@nanjj), @sgati-bodhi
+
+- Documentation (including README, NEWS, CHANGELOG) ::
+@randomwangran, marty hiatt (@mooseyboots)
+
+- All the comments, issues, and questions on GitHub ::
+@randomwangran, @karthink, @holtzermann17, @shombando, @magthe, @linwaytin, 
@rtrppl, @ryanprior, @ericsfraga, @darcamo, @zhewy, @QMeqGR, 
@Vidianos-Giannitsis, @AtomicNess123, @mooseyboots, @ouboub, @dian-yu-luo, 
@SylvianHemus, @basaran, @Ypot, @oatmealm, @sati-bodhi
+
 * License
 
 This work is licensed under a GPLv3 license. For a full copy of the license, 
refer to [[./LICENSE][LICENSE]].
@@ -110,15 +126,3 @@ This section is created by Org-remark for the source file. 
It serves as an examp
 ** defmacro org-remark-create
 
 This macro was inspired by 
[[https://github.com/jkitchin/ov-highlight][Ov-highlight]].  It's by John 
Kitchin (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.
-
-* org-remark
-:PROPERTIES:
-:org-remark-file: org-remark.el
-:END:
-
-** org-remark-notes-send-data
-
-** org-remark-highlights-load
-
-** goto
-This is no longer empty.
diff --git a/docs/org-remark.org b/docs/org-remark.org
index 7a013f1bc6..5e42e9330c 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 1.0.x
-#+macro: modified 24 April 2022
+#+macro: modified 14 January 2023
 #+language: en
 #+export_file_name: org-remark.texi
 #+texinfo_dir_category: Emacs
@@ -56,11 +56,17 @@ GNU ELPA should be already set up in your Emacs by default. 
If you wish to add G
 
 After installation, we suggest you put the setup below in your configuration.
 
+#+name: basic-setup
 #+begin_src emacs-lisp
-  (require 'org-remark-global-tracking)
   (org-remark-global-tracking-mode +1)
+
+  ;; Optional if you would like to highlight websites via eww-mode
+  (with-eval-after-load 'eww
+    (org-remark-eww-mode +1))
 #+end_src
 
+~org-remark-global-tracking-mode~ automatically turns on ~org-remark-mode~ 
when you open a file or website via EWW [fn:1] that has a marginal notes file 
associated to it. This is useful to keep the location of your highlights 
correct across Emacs sessions after you shutdown Emacs.
+
 Unless you explicitly load ~org~ during Emacs initialization, we 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:
@@ -79,6 +85,8 @@ Below are example keybindings you might like to consider:
     (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove))
 #+end_src
 
+[fn:1]: Feature to highlight and annotate websites is new in the latest 
[[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] and is planned 
to be part of v1.1.0.
+
 * Getting Started
 :PROPERTIES:
 :CUSTOM_ID: getting-started
@@ -130,6 +138,13 @@ Org-remark lets you create your own custom pen functions 
with ~org-remark-create
 
 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.
 
+** Highlight and Annotate Websites (new in latest 
[[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]]; to be part of 
v1.1.0)
+
+#+cindex: Highlighting websites with EWW
+#+findex: org-remark-eww-mode
+
+~org-remark-eww-mode~ lets you highlight and annotate websites just like text 
files. It is a global minor mode. It does not require any additional 
configuration. All you need is to turn it on, visit a website with ~eww-mode~, 
and select text and highlight it. Refer to the example of a basic setup given 
in [[#installation][Instalaltion]].
+
 * Usage
 :PROPERTIES:
 :CUSTOM_ID: usage
@@ -223,11 +238,16 @@ In addition to the properties above that Org-remark 
reserves for itself, you can
 *** =*marginal-notes*= Buffer
 
 #+cindex: *marginal notes* buffer
+#+cindex: Echo text / Tool tip on the Highlight
 
 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.
 
+After all the properties, you can freely write your notes for the highlight. 
Once you save the notes buffer, an excerpt of the text (currently up to 200 
characters) gets updated back onto the highlight in the source buffer. You can 
hover your mouse over the highlight to see the excerpt displayed in the echo 
area (bottom of the screen) of Emacs. If you have ~tooltip-mode~ mode turned 
on, the excerpt is displayed as a took tip for the highlight [fn:2].
+
+[fn:2]: Feature to display an excerpt of the body of marginal notes is new in 
latest [[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] and is 
planned to be part of v1.1.0.
+
 *** How to Change Where Marginal Notes File is Saved
 :PROPERTIES:
 :CUSTOM_ID: change-marginal-notes-filename
@@ -237,7 +257,7 @@ Org-remark displays the marginal notes buffer narrowed to 
the highlight the curs
 
 The location of the marginal notes file is specified by user option 
~org-remark-notes-file-name~ and its default is "marginalia.org". This means 
the marginal notes file will reside in the same directory as the source files 
as a separate file.
 
-If you use the ~customize~ command to customize ~org-remark-notes-file-name~, 
you will have an option to choose a =File= or =Function= (customization group 
~org-remark~). The default is =File= with the default "marginalial.org" as 
noted above.  Use a string to specify the single file name; you can specify a 
relative path like the default or an absolute path.
+If you use the ~customize~ command to customize ~org-remark-notes-file-name~, 
you will have an option to choose a =File= or =Function= (customization group 
~org-remark~). The default is =File= with the default "marginal.org" as noted 
above.  Use a string to specify the single file name; you can specify a 
relative path like the default or an absolute path.
 
 If you would like to dynamically change the location based on the file and 
various different conditions, select the function as an option.  The default 
function is ~org-remark-notes-file-name-function~. It adds =-notes.org= as a 
suffix to the source file's name without the extension. For example, for a file 
named =my-source-file.txt=,  Org-remark will store highlights in  
=my-source-file-notes.org=.  You can create your own function and use it.
 
@@ -377,6 +397,8 @@ Org-remark's user options are available in the 
customization group ~org-remark~.
 
 - Moving source files and marginal notes files :: Moving your files and remark 
file to another directory does not update the source paths and file names 
stored in the marginal notes file. One way to keep the links between the source 
files and marginal notes files is to use relative file names with 
~org-remark-source-file-name~ (default).
 
+- With ~org-remark-eww-mode~ highlights can get displaced :: This happens when 
the website is edited and its content changes outside Emacs -- of course this 
is normal for websites. Currently there is no way to fix the location of 
highlights.
+
 * Credits
 
 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.
diff --git a/org-remark-eww.el b/org-remark-eww.el
index 3e94593de4..7d48fa5516 100644
--- a/org-remark-eww.el
+++ b/org-remark-eww.el
@@ -6,7 +6,7 @@
 ;;          Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-remark
 ;; Created: 23 December 2022
-;; Last modified: 11 January 2023
+;; Last modified: 14 January 2023
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp
 
diff --git a/org-remark-global-tracking.el b/org-remark-global-tracking.el
index a7dbc63978..b963085f49 100644
--- a/org-remark-global-tracking.el
+++ b/org-remark-global-tracking.el
@@ -5,7 +5,7 @@
 ;; Author: Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-remark
 ;; Created: 15 August 2021
-;; Last modified: 11 January 2023
+;; Last modified: 14 January 2023
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp
 
diff --git a/org-remark.el b/org-remark.el
index 419572777e..f9b1f98383 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -6,7 +6,7 @@
 ;; URL: https://github.com/nobiot/org-remark
 ;; Version: 1.0.5
 ;; Created: 22 December 2020
-;; Last modified: 13 January 2023
+;; Last modified: 14 January 2023
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp,
 
@@ -804,7 +804,7 @@ This function assumes the current buffer is the source 
buffer."
 (defvar org-remark-notes-headline-functions
   '((default . ((1 . org-remark-highlight-add-source-headline-maybe)))))
 
-(make-obsolete #'org-remark-highlight-save #'org-remark-highlight-add "1.3.0")
+(make-obsolete #'org-remark-highlight-save #'org-remark-highlight-add "1.2.0")
 
 (defun org-remark-highlight-add (overlay source-buf notes-buf)
   "Add a single HIGHLIGHT in the marginal notes file.