Update socket repl plugin readme todo

Author: jebberjeb

socket-repl-plugin/README.md

@@ -10,22 +10,35 @@ TODO: architecture diagram
 
 ## Usage
 
-After starting a Clojure application with a socket repl server.
+Start a Clojure program with a socket repl server. This can be done by
+adding the following JVM options to any Clojure application.
+
+```
+-Dclojure.server.repl="{:port 5555 :accept clojure.core.server/repl}"
+```
+
+Then, from within Neovim, connect to the socket repl.
 
 ```
 :Connect <host> <port>
 ```
 
-Create a buffer for displaying interaction with the repl. In that buffer:
+Create a buffer for displaying interaction with the repl.
 
 ```
+:vnew
 :ReplLog
 ```
 
 From there, to eval any buffer or form under cursor use:
 
 ```
 :EvalBuffer
+```
+
+or
+
+```
 :EvalCode
 ```
 
@@ -52,12 +65,19 @@ This plugin requires a version of the Java version 1.6 or higher. You've probabl
 
 ## Developing
 
-Start Neovim using:
+Start Neovim using, open the debug plugin script.
 
 ```
 NVIM_LISTEN_ADDRESS=127.0.0.1:7777 nvim plugin/socketrepl.vim.debug
 ```
 
+From within Neovim, source the debug plugin script. This causes it to use
+a socket connection, rather than stdio to communicate with the plugin.
+
+```
+:so %
+```
+
 Start the plugin. Then you'll need to connect to Neovim from the repl.
 
 ```
@@ -66,11 +86,18 @@ $> nc localhost 5555
 user=> (go)
 ```
 
-or, with Leiningen:
+or, with Leiningen
 
 ```
 $> lein repl
 $> (go)
 ```
 
-You can now use plugin commands from within Neovim `:Connect`, `:EvalBuffer`, etc.
+You can now use plugin commands from within Neovim `:Connect`, `:EvalBuffer`,
+etc.
+
+Note that you'll probably want to rely heavily on the asynchronous
+neovim-client functions when you want (the plugin) to make a request
+of neovim. This is because the Neovim function `rpcrequest` blocks until
+it has received a response (from your plugin). Using async on the plugin
+side is the easiest way to avoid deadlock.

socket-repl-plugin/TODO

@@ -15,13 +15,16 @@ TODO alpha
 	[_] implement doc (word under cursor)
 	[_] Pass host, port in connect
 	[_] Update README
-		Move NVIM_LISTEN... stuff to a debug section
+		[X] Move NVIM_LISTEN... stuff to a debug section
+		[_] demo video
+		[_] architecture diagram
+			nvim<--msgpack/stdio-->plugin(jar)<--localhost:5555-->socketrepl
 
-TODO final
+TODO next
 	[_] Rather than explicit repl output logging, can we intercept
 		channel
 		stream implementation
-	[_] Shut down the plugin if no input received for one minute
+	[X] Shut down the plugin if no input received for one minute
 	[X] evaluate form under cursor
 
 Goals
@@ -45,28 +48,6 @@ Goals
 		Accessible from vim buffer `:call ShowClojurePluginRepl()`
 	-Not a way of life
 		Does not include paredit, syntax highlight, etc
-	-Architecture Diagram
-		nvim <--msgpack/stdio--> plugin (jar) <--localhost:5555--> socket repl
 
 Questions
 	Figwheel cljs-repl support
-
-Usage/Installation
-	no other install outside of normal plugin (pathogen, vundle, etc)
-		** except the rtp thing **
-	add command line args to your project, so it starts socket repl
-		-Dclojure.server.repl="{:port 5555 :accept clojure.core.server/repl}"
-	on `:Connect` specify port (and host) to connect to
-	split a pane, `:ReplLog`
-
-Debugging notes
-	vim
-		start vim w/ NVIM_LISTEN_ADDRESS
-		`:so` plugin/socket-repl.vim.debug script
-	clj
-		start plugin w/ `run.sh`
-			this also starts a socket repl on 5555
-		note: use async!
-		: vim blocks if you make a synchronous call to clj which makes a sync
-		: call back to vim -- use async!
-