[nongnu] elpa/geiser-kawa 5521b28 025/119: Update README after joining of geiser-kawa and kawa-geiser projects

[Philip Kaludercic]

branch: elpa/geiser-kawa
commit 5521b2830673e7a5b66a53ab0d64ff25fd9a2768
Author: spellcard199 <spellcard199@protonmail.com>
Commit: spellcard199 <spellcard199@protonmail.com>

    Update README after joining of geiser-kawa and kawa-geiser projects
---
 README.org | 98 +++++++++++++++++++++++++++++++++-----------------------------
 1 file changed, 52 insertions(+), 46 deletions(-)

diff --git a/README.org b/README.org
index abc40a4..1bec66c 100644
--- a/README.org
+++ b/README.org
@@ -2,7 +2,11 @@
 * geiser-kawa
 ** Project description
 
-geiser-kawa is the emacs side of a geiser-kawa implementation that uses 
[[https://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]] for its Kawa side.
+=geiser-kawa= is a geiser implementation for Kawa Scheme.
+
+It has 2 parts:
+- =geiser-kawa=: elisp package inside the =elisp= directory that gives the 
name to the whole project
+- =kawa-geiser=: maven project written using Kawa's Java API that adds the 
functions that geiser-kawa calls to get the data it needs to a Kawa Scheme REPL
 
 ** Supported Kawa versions
 :PROPERTIES:
@@ -11,18 +15,6 @@ geiser-kawa is the emacs side of a geiser-kawa 
implementation that uses [[https:
 
 Only versions of Kawa > 3.1 are supported, mostly due to the fact that before 
the 3.1 release some necessary Kawa classes were private.
 
-** Try geiser-kawa without modifying your emacs configuration
-
-1. Get Emacs, Cask, Maven and make them available through your $PATH
-2. Clone this repository
-3. cd into the cloned dir
-4. Tell cask to install emacs dependencies with:
-  : cask install
-5. Pull [[http://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]] maven 
dependencies (the first time takes ~1 minute), compile them and start 
geiser-kawa's scratch buffer and repl with:
-  : cask emacs -Q --load quickstart.el
-
-The reason you don't need Kawa to try geiser-kawa is that =quickstart.el= uses 
the compiled [[https://gitlab.com/groups/kashell/][Kawa's master branch]] that 
is one of [[http://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]]'s 
dependencies. To do so =quickstart.el= calls =mvn package= (wrapped by 
=geiser-kawa-compile-java-dependencies=), which produces a jar that includes 
all [[http://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]]'s dependencies.
-
 ** Supported features
 
 - geiser-related:
@@ -41,7 +33,42 @@ The reason you don't need Kawa to try geiser-kawa is that 
=quickstart.el= uses t
 - kawa- and java-specific:
     - completion for java classes' fields and methods accessed through 
colon-notation: don't expect java-grade reliability
 
-*** About completion for java classes' fields and methods
+** Unsupported features
+
+geiser-related:
+- macroexpand
+- find-file
+- symbol-location
+- module-location
+- symbol-documentation
+- module-exports
+- callers
+- callees
+- generic-methods
+
+kawa- and java-specific:
+- completion for java package names and class names
+
+** Try geiser-kawa without modifying your emacs configuration
+
+1. Get Emacs and [[https://github.com/cask/cask][Cask]] and make them 
available through your $PATH
+2. Clone this repository
+  : git clone "https://gitlab.com/spellcard199/geiser-kawa.git";
+3. cd into the cloned dir:
+  : cd geiser-kawa
+4. Tell cask to install emacs dependencies:
+  : cask install
+5. Pull kawa-geiser maven dependencies (the first time takes ~1 minute), 
compile them and start geiser-kawa's scratch buffer and repl:
+  : cask emacs -Q --load quickstart.el
+6. You should now have an emacs frame containing a scratch buffer in 
=geiser-mode= and a repl buffer, both with geiser-kawa support
+
+To try geiser-kawa you need neither Maven nor Kawa:
+- =mvnw= ([[https://github.com/takari/maven-wrapper][maven-wrapper]]) takes 
care of downloading a project-specific Maven version
+- kawa-geiser has [[https://gitlab.com/groups/kashell/][Kawa's master branch]] 
as one of its dependencies. When =quickstart.el= calls =./mvnw package= 
(wrapped by =geiser-kawa-compile-java-dependencies=), it produces a jar that 
includes kawa-geiser and all its dependencies, including Kawa itself.
+
+** About completion for java classes' fields and methods
+
+The whole project is in a persistent "experimental" state, but this part even 
more so.
 
 The main interactive elisp function is 
=geiser-kawa-complete-java-fom-at-point=. It's not bound to a key by default.
 
@@ -50,11 +77,11 @@ For this to work you have to:
 - avoid syntax errors (e.g. unbalanced parentheses, wrong number of children 
sexps inside a form, etc...)
 
 How it works (the region getting part is quite rudimentray):
-1. A region of the current buffer and cursor point inside it are sent to 
[[https://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]], which uses 
[[https://gitlab.com/spellcard199/kawa-devutil][kawa-devutil]] for actual 
functionality. The region of the buffer goes:
-     - from either:
+1. A region of the current buffer and cursor point inside it are sent to 
kawa-geiser, which uses 
[[https://gitlab.com/spellcard199/kawa-devutil][kawa-devutil]] for actual 
functionality. The region of the buffer goes:
+     - from: either:
          - =(geiser-syntax--pop-to-top)=, if non-nil
          - =(line-beginning-position)=, if =(geiser-syntax--pop-to-top)= is 
=nil=
-     - to either:
+     - to: either:
          - end of sexp beginning at toplevel, if =(geiser-syntax--pop-to-top)= 
is non-nil
          - =(line-end-position)=, if =(geiser-syntax--pop-to-top)= is =nil=
 2. An arbitrary symbol is added at cursor point, so it can be found again in 
the AST
@@ -63,41 +90,20 @@ How it works (the region getting part is quite rudimentray):
      - one of them matches: the matcher function itself then also has to tell 
which class we are completing for
      - none are left: empty data
 
-** Unsupported features
-
-geiser-related:
-- macroexpand
-- find-file
-- symbol-location
-- module-location
-- symbol-documentation
-- module-exports
-- callers
-- callees
-- generic-methods
-
-kawa- and java-specific:
-- completion for java package names and class names
-
 ** Difference from 
[[https://gitlab.com/spellcard199/geiser-kawa-scheme][geiser-kawa-scheme]]
 
-- The Kawa side of geiser-kawa uses 
[[https://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]], which is written 
using Kawa's Java API.
-- The Kawa side of geiser-kawa-scheme is written directly in Kawa Scheme.
-- I'm going to add more features to geiser-kawa but I probably won't port them 
to geiser-kawa-scheme.
-
-Reasons for rewriting and translating the old geiser-kawa from Kawa Scheme to 
Java:
-- Easier to add as a scripting language in Java projects: just add the jitpack 
repo and the kawa-geiser dependency (see pom.xml as an example)
-- Easier to inculde external java libraries via maven central for additional 
functionalities (e.g. [[https://github.com/classgraph/classgraph][classgraph]])
-- Tooling for Java is excellent, tooling for Kawa is poor
+This project (geiser-kawa) is a translation/rewrite of 
[[https://gitlab.com/spellcard199/geiser-kawa-scheme][geiser-kawa-scheme]], 
which has been my first attempt at writing geiser-kawa. After 
geiser-kawa-scheme confirmed me that a geiser-kawa implementation was possible 
I decided to rewrite the Kawa side using Kawa's Java API, for the several 
reasons:
+- Easier to add as a scripting language in Java projects: just add the jitpack 
resolver and this project's repository as a dependency
+- Easier to inculde external java libraries via maven central for additional 
functionalities
+- Tooling for Java is excellent, tooling for Kawa is not
 - Fully static type checking: probably it's because I'm bad at programming, 
but it helps me a lot
-- Possibility to share code between kawa-devutil and Kawa's Language Server
 - The old geiser-kawa's scheme implementation logic has been split in 2 
projects:
-    - [[https://www.gitlab.com/spellcard199/kawa-devutil][kawa-devutil]]: 
functions that take care of getting data and general functionalities (e.g. eval 
capturing output)
+    - [[https://www.gitlab.com/spellcard199/kawa-devutil][kawa-devutil]]: 
functions that take care of getting data and general functionalities (e.g. 
output-capturing eval)
     - kawa-geiser:
-        - it's the maven project included with this project, made up by the 
file =pom.xml= and the directory =src=
+        - the included maven project
         - gets data and features through kawa-devutil and wraps the result in 
the geiser protocol
-
-The fact that kawa-devutil is now a project separated from geiser means that 
it may also be used to avoid re-writing the data-getting logic if one wanted to 
implement a protocol for a tool other than geiser (e.g. nrepl, jupyter, 
swank/slime).
+- Possibility to share code between kawa-devutil and Kawa's Language Server
+- Since kawa-devutil is now a different project from geiser-kawa, one could 
use it to avoid re-writing the data-getting logic if he wanted to implement a 
Kawa server for a tool other than geiser (e.g. nrepl, jupyter, swank/slime)
 
 geiser-kawa VS geiser-kawa-scheme - recap table: