[elpa] externals/jarchive 214a7db52f 22/33: Update readme with better examples and explanations

[ELPA Syncer]

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

    Update readme with better examples and explanations
---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 50 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index c5adaaf4d4..b5cf885849 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,41 @@
-Jarchive teaches emacs how to navigate to files inside jars.
-
-With it enabled things like this will open up `page.clj` in a read-only buffer.
-
-``` emacs-lisp
-(find-file 
"~/.m2/repository/hiccup/hiccup/1.0.5/hiccup-1.0.5.jar::/hiccup/page.clj")
-```
-
-When using eglot, invoking `xref-find-definitions` on symbols defined in JAR 
files should correctly open the files inside the jars.
-
-This package is intended to be used with eglot and lsp-servers like 
clojure-lsp that provide URIs to files contained in jars through methods like 
`textDocument/definition`.
+Jarchive teaches emacs how to open project dependencies that reside inside jar 
files.
 
 # Package status
 
 This package is still under active development and is not yet ready for 
widespread use. Proceed with caution!
 
+It current works well with eglot on the Emacs master branch. 
+If you are using eglot from melpa or the eglot github, this won't work.
+I will update the README when this changes.
+
 # Installing
 
-Add this repository to your emacs load-path
+This package is not available on any package repositories yet.
+
+Write now I recommend cloning this repository and adding it to your emacs 
load-path:
 
 ``` emacs-lisp
 (add-to-list 'load-path "path/to/jarchive")
 ```
 
-Then load and initialize the repository
+There is also an example of a [guix 
recipe](https://git.sr.ht/~abcdw/rde/tree/90af100a4d70d7016261d39b91b6748768ac374b/rde/packages/emacs-xyz.scm#L330).
+
+Load and initialize the repository
 
 ``` emacs-lisp
 (require 'jarchive)
-(jarchive-setup)
+(with-eval-after-load "init"
+  (jarchive-setup))
 ```
 
 It can also be done in a hook (recommended)
 
 ``` emacs-lisp
-(add-hook 'clojure-mode-hook #'jarchive-setup)
+(add-hook 'eglot-managed-mode-hook #'jarchive-setup)
 ```
 
 or interactively, via `M-x jarchive-setup`.
 
-# Usage
-
-With eglot, `xref-find-definitions` should correctly open up source files 
found in jar dependencies.
-
-Once a file is opened, typing `M-x jarchive-move-to-visiting-project` will 
move the file and it's buffer
-to the project that was used to visit it.
-This will allow you to edit the file and let eglot manage it as part of the 
real project.
-
 ## 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.
@@ -52,6 +43,42 @@ Some Emacs "distributions" like doom set the 
`file-name-handler-alist` var to ni
 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.
 
+# Usage
+
+With it enabled, things like this will open up `page.clj` in a read-only 
buffer.
+
+``` emacs-lisp
+(find-file 
"jar:file:///.m2/repository/hiccup/hiccup/1.0.5/hiccup-1.0.5.jar!/hiccup/page.clj")
+```
+
+When using eglot connected to a JVM language server, invoking 
`xref-find-definitions` should correctly open any dependencies that reside in 
JAR files.
+
+## Other usage considerations
+
+If you want eglot to manage the opened jar'd file in your project's current 
lsp session, set
+``` emacs-lisp
+(setq eglot-extend-to-xref t) 
+```
+This will allow xref to work across your project and the opened file.
+
+If you do not want that, the eglot will probably start a new server to manage 
the newly opened file.
+There are legitimate reasons to do this, because including it in the current 
LSP session will mean it is included when looking up references.
+Large files, like the clojure core library, could create a lot of noise in 
xref lookups.
+Another recommendation if you don't want them managed by eglot is to set
+``` emacs-lisp
+(setq eglot-autoshutdown t)
+```
+so that the transient lsp server that is started when opening the file is 
closed along with it.
+
+## Language server compatibility
+
+I personally only test this with [clojure-lsp](https://clojure-lsp.io/).
+I have heard from other users that it also works with some unspecified java 
language server.
+Any language server that provides jar: scheme URIs should be picked up by this 
package.
+If it doesn't, please let me know and I'd be happy to take a look.
+
 ## Questions
 
 Questions and patches can be submitted to the [mailing 
list](https://lists.sr.ht/~dannyfreeman/jarchive-dev).
+Any bugs found should include steps to reproduce. 
+If possible, and example repository containing a project and instructions (or 
a nix shell) for installing the language servers would be appreciated.