[elpa] externals/drepl 1eb913d872 5/5: Expand readme

[ELPA Syncer]

branch: externals/drepl
commit 1eb913d872e2bc3b9e07894dc26d620b4c4b4e04
Author: Augusto Stoffel <arstoffel@gmail.com>
Commit: Augusto Stoffel <arstoffel@gmail.com>

    Expand readme
---
 README.org | 114 +++++++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 73 insertions(+), 41 deletions(-)

diff --git a/README.org b/README.org
index ad234140ad..00c6c24e6d 100644
--- a/README.org
+++ b/README.org
@@ -9,13 +9,11 @@ the moment it supports the following interpreters:
 The following features are available, subject to variations across
 different REPLs (IPython supports all of them):
 
-- [X] Completion, including annotations and also on continuation lines
-- [X] Multi-line input editing
-- [X] Eldoc integration
-- [X] Normal pty interaction during code evaluation (e.g. debuggers)
-- [X] Graphics support via 
[[https://github.com/astoff/comint-mime][comint-mime]]
-- [ ] Remote interpreters via Tramp
-- [ ] Persistent history
+- Completion, including annotations and also on continuation lines
+- Multi-line input editing
+- Eldoc integration
+- Normal pty interaction during code evaluation (e.g. debuggers)
+- Graphics support via [[https://github.com/astoff/comint-mime][comint-mime]]
 
 In fancier terms, dREPL can be described as a REPL protocol for the
 dumb terminal.  One Elisp library defines the user interface and the
@@ -27,7 +25,7 @@ straightforward.
 
 ** Usage
 
-To start a REPL, use one of the =M-x drepl-run-*= commands (making
+To start a REPL, use one of the =M-x drepl-*= commands (making
 sure first that you have the target language dependencies installed,
 as described above).  The rest should look familiar.
 
@@ -64,7 +62,7 @@ how to multiplex control messages and regular IO.
 
 At any given point in time, the subprocess expects either a framed
 messages like this or regular IO.  Emacs keeps track of the state of
-the subprocess through status notifications as described below.
+the subprocess through =status= notifications as described below.
 
 There are three types of message: /requests/, to which a /response/ is
 expected, and /notifications/, to which no response is expected.  A
@@ -80,45 +78,79 @@ message contains the following fields:
 
 The following operations are defined:
 
-- =status=: Interpreter notification with one parameter, =status=.
-  The value can be =ready= (subprocess is expecting a framed
-  message) or =busy= (IO, if it occurs, should not be framed).
-
-- =eval=: Editor request with one argument, the string =code=.  The
-  REPL should evaluate the code, print the result, and send an empty
-  response.
-
-- =complete=: Editor request with arguments =code= and =offset=.  The
-  interpreter returns possible completions of the code at the given
-  position.  The response has one item, =candidates=, which is a list
-  of objects containing:
-  - =text=: The completed text, including existing prefix.
-  - =annot=: Annotation text to be displayed next to the candidate in
-    the completion UI.
-
-- =checkinput=: Editor request with one argument, the string =code=.
-  The interpreter returns:
-  - =status=: One of =complete= (the code is valid), =incomplete=
-    (the code is syntactically invalid, but may become so by adding
-    more text) or =invalid= (there is a syntax error in the existing
-    portion of code).
-  - =indent=: If present, this is the expected indentation of a
-    continuation line, as a string.
+- =status= (interpreter notification): The interpreter indicates
+  whether or not it is ready to receive a framed operation message.
+
+  Parameters:
+  - =status=: Either =ready= (subprocess is expecting a
+    framed message) or =busy= (IO, if it occurs, should not be
+    framed).
+
+  Note: Some changes in the tracked state happen implicitly.  Most
+  importantly, when an editor request is sent, tracked state changes
+  to =busy=.
+
+- =eval= (editor request).  Evaluate some code, blocking until the
+  computation is complete.
+
+  Parameters:
+  - =code=: The code to be evaluated
+
+  Result: The response contains no data (that is, it includes only the
+  original request id).  The REPL should evaluate the code and print
+  the result.
+
+- =complete= (editor request): Get completions at point.
+
+  Parameters:
+  - =code=: A code snippet containing the completion point.
+  - =offset=: The offset (zero-based) from start of =code= to
+    the point of completion.
+
+  Response:
+  - =candidates= (optional): A list of objects, each containing the
+    following attributes.
+    - =text=: The completed text, including the existing prefix.
+    - =annot=: Annotation text to be displayed next to the candidate
+      in the completion UI.
+
+- =checkinput= (editor request): Check if a continuation line is
+  needed.
+
+  Parameters:
+  - =code= (string): A code snippet.
+
+  Result:
+  - =status=: One of =complete= (the code is valid),
+    =incomplete= (the code is syntactically invalid, but may become so
+    by adding more text) or =invalid= (there is a syntax error in the
+    existing portion of code).
+  - =indent= (optional): If present, this is the expected indentation
+    of a continuation line, as a string.
   - =prompt=: The prompt of a continuation line.
 
-- =describe=: Editor request to obtain information on the symbol at
-  point.  The parameters are =code= and =offset=.  The response can
-  include any of the following:
+- =describe= (editor request): Obtain information on the symbol at
+  point.
+
+  Parameters:
+  - =code=: A code snippet.
+  - =offset=: An offset (zero-based) from start of =code= containing
+    the symbol of interest.
+
+  Result: The response may be empty (no information on the symbol) or
+  as follows.
   - =name=: The symbol name.
-  - =type=: The symbol type or function signature.
-  - =text=: Free-form documentation on the symbol.
+  - =type= (optional): The symbol type or function signature.
+  - =text= (optional): Free-form documentation on the symbol.
 
-- =setoptions=: Editor request to set configuration options.  The
+- =setoptions= (editor request): Set configuration options.  The
   parameters are arbitrary and interpreter-specific.  The interpreter
   must send an empty response.
 
-- =getoptions=: Interpreter notification to request a =setoptions=
-  notification.
+- =getoptions= (interpreter notification).  Indicates that the editor
+  should send a =setoptions= request.  Typically emitted when the
+  interpreter is initialized but before printing the first prompt.
+  Implicitly changes the tracked interpreter state to =ready=.
 
 ** Why