[elpa] externals/jarchive 149f37507e 31/33: Separate Eglot patching process to be invoked manually by the user

[ELPA Syncer]

branch: externals/jarchive
commit 149f37507e2e8c88dd66e3c821611414b615e317
Author: dannyfreeman <danny@dfreeman.email>
Commit: dannyfreeman <danny@dfreeman.email>

    Separate Eglot patching process to be invoked manually by the user
    
    package-lint gives warnings about using `with-eval-after-load' in
    packages, that it belongs in user configurations. If that is the case
    then having the user decided when to call the eglot patching process is
    the best solution IMO.
    
    Information is added to the readme to help explain.
---
 CHANGELOG.md |  9 ++++++++-
 README.md    | 22 +++++++++++++++++++---
 jarchive.el  | 19 ++++++++++++++-----
 3 files changed, 41 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0cb9ba24a3..c8e2cfe39b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Change Log
-## 2022-11-11 Release Notes
+
+## 2022-11-12 0.2.0 Release Notes
+- Documentation updates in preparation for submitting to elpa or melpa
+- BREAKING: Patching legacy Eglot no longer happens automatically when calling 
`jarchive-setup`.
+  - Users can call `(with-eval-after-load 'eglot (jarchive-patch-eglot))` now 
in their config instead.
+- `jarchive-patch-eglot` attempts to print warnings when it is called at the 
wrong time.
+
+## 2022-11-11 0.1.0 Release Notes
 
 - Now operates on full jar URIs and zipfile URIs
   - For example `jar:file:///path/to/library.jar!/path/in/jar/source.ext`
diff --git a/README.md b/README.md
index 69ca122433..a5d789bf9d 100644
--- a/README.md
+++ b/README.md
@@ -35,16 +35,32 @@ It can also be done in a hook (recommended)
 
 ``` emacs-lisp
 (add-hook 'eglot-managed-mode-hook #'jarchive-setup)
+;; OR something like
+(add-hook 'clojure-mode-hook #'jarchive-setup)
 ```
-
 or interactively, via `M-x jarchive-setup`.
 
+## Working with Eglot
+
+Jarchive will open jar dependencies provided to Eglot by lsp servers.
+
+If you are using an older version of Eglot, like the melpa version released on 
[2022-10-20](https://melpa.org/packages/eglot-20221020.1010.el "Eglot Melpa 
Release 2022-10-20"), then you need to call `jarchive-patch-eglot` after Eglot 
is loaded, like so
+
+``` emacs-lisp
+(with-eval-after-load 'eglot
+  (jarchive-patch-eglot))
+```
+
+This is _not_ required on newer versions of eglot. Installs that are up to 
date with eglot on [ELPA devel](https://elpa.gnu.org/devel/eglot.html "Eglot 
ELPA Devel Release") or eglot bundled with emacs 29 will work without patching.
+This patch function is included so those on older releases of eglot can also 
take advantage of this package.
+Eventually it will be removed (with some advanced notice).
+
 ## Note about when to call `jarchive-setup`
 
-Some Emacs "distributions" like doom set the `file-name-handler-alist` var to 
nil on startup, then restore it's value when startup is complete.
+Some Emacs distributions like [Doom](https://github.com/doomemacs/doomemacs) 
(and many personal configurations), set the `file-name-handler-alist` var to 
nil on startup, then restore it's value when startup is complete.
 
 If this is the case for you, `jarchive-setup` should be called AFTER 
everything is initialized.
-This package modifies `file-name-handler-alist`, so it relies on it not being 
reset after `jarchive-setup` is invoked.
+This package modifies `file-name-handler-alist`, so it relies on it _not_ 
being reset after `jarchive-setup` is invoked.
 
 # Usage
 
diff --git a/jarchive.el b/jarchive.el
index 4a042b1f98..621fd21638 100644
--- a/jarchive.el
+++ b/jarchive.el
@@ -158,16 +158,25 @@ handle it. If it is not a jar call ORIGINAL-FN."
         (apply 'funcall original-fn args)
       uri)))
 
+;;;###autoload
+(defun jarchive-patch-eglot ()
+  "Patch old versions of Eglot to work with Jarchive."
+  (interactive) ;; TODO, remove when eglot is updated in melpa
+  (cond
+   ((version<= "29" emacs-version)
+    (message "[jarchive] Eglot does not need to be patched. Skipping."))
+   ((or (not (fboundp 'eglot--path-to-uri))
+        (not (fboundp 'eglot--uri-to-path)))
+    (message "[jarchive] Eglot is not loaded, try calling 
`jarchive-patch-eglot' after loading eglot."))
+   (t (advice-add 'eglot--path-to-uri :around 
#'jarchive--wrap-legacy-eglot--path-to-uri)
+      (advice-add 'eglot--uri-to-path :around 
#'jarchive--wrap-legacy-eglot--uri-to-path)
+      (message "[jarchive] Eglot successfully patched."))))
+
 ;;;###autoload
 (defun jarchive-setup ()
   "Setup jarchive, enabling Emacs to open files inside jar archives.
 the files can be identified with the `jar' uri scheme."
   (interactive)
-  (with-eval-after-load 'eglot
-    (when (version< emacs-version "29") ;; TODO, remove when eglot is updated 
in melpa
-      (advice-add 'eglot--path-to-uri :around 
#'jarchive--wrap-legacy-eglot--path-to-uri)
-      (advice-add 'eglot--uri-to-path :around 
#'jarchive--wrap-legacy-eglot--uri-to-path)))
-
   (add-to-list 'file-name-handler-alist (cons jarchive--uri-regex 
#'jarchive--file-name-handler))
   (add-to-list 'find-file-not-found-functions #'jarchive--find-file-not-found))