Jupyter integration improvements: support $APPLAUSE_OPTS and document how to display graphics and rich text

3 files changed, 15 insertions, 11 deletions

diff --git a/README.md b/README.md
index 2d0b7a5..6e2eac2 100644
--- a/README.md
+++ b/README.md
@@ -85,7 +85,7 @@ git clone https://github.com/guysv/ilua.git --recurse-submodules
 cd ilua
 python3 -m venv env
 . env/bin/activate
-pip install twisted==22.10.0 ilua
+pip install twisted==22.10.0 .
 ```
 
 You can now directly run an Applause Jupyter Console session:
@@ -96,10 +96,11 @@ ilua --lua-interpreter=./applause
 ```
 
 In order to tweak Applause command line parameters and be independant of the execution directory, use
-the included wrapper script:
+the included wrapper script.
+It also allows passing in additional arguments to Applause, e.g.:
 
 ```
-ilua --lua-interpreter=./ilua-wrapper.sh
+APPLAUSE_OPTS="-o 2" ilua --lua-interpreter=./ilua-wrapper.sh
 ```
 
 You can symlink this to `lua` in the Python environment to make Applause the default
@@ -118,19 +119,19 @@ pip install notebook
 Now launch a web server and follow the onscreen instructions:
 
 ```
-jupyter notebook
+APPLAUSE_OPTS="-o 2" jupyter notebook --MultiKernelManager.default_kernel_name=lua
 ```
 
-In the Jupyter Notebook dashboard, when creating a new notebook, you will be asked to select the kernel.
-If you choose Lua, this will in fact launch Applause (assuming that you symlinked to `lua`
-as described above).
+This works assuming that you symlinked `ilua-wrapper.sh` to `lua` as described above.
 An alternative might be to create a custom Jupyter kernel configuration (kernel.json).
 
 Please note the following restrictions/bugs:
 
 * You cannot publicly host the Jupyter Notebook as the sound is generated on the host machine.
-* You cannot currently interrupt an endlessly running stream without restarting the kernel (**FIXME**)
+* You cannot currently interrupt an endlessly running stream without restarting the kernel
+  (see this [ILua bug](https://github.com/guysv/ilua/issues/1)).
 * ILua does not work well with our custom Stream:tostring() metamethods
 * The output of other functions like Stream:toplot() is garbled.
-* You cannot currently output rich text or graphics
-  (it would be really cool if we could display SVG generated by gnuplot in notebook cells for instance).
+* You cannot currently output rich text or graphics -
+  it would be really cool if we could display SVG generated by gnuplot in notebook cells for instance.
+  There is a [workaround](https://github.com/guysv/ilua/issues/5), though.
diff --git a/TODO b/TODO
index 99d4ad6..b1a5e62 100644
--- a/TODO
+++ b/TODO
@@ -5,6 +5,9 @@
   For Stream:play() this is solved differently.
 * The MIDIStream should be flushed when starting via Stream:play().
 * There are lots of limitations with Jupyter servers (see README).
+  Perhaps it would be better to use xeus-lua, but that would require us to refactor everything
+  into a proper Lua library.
+  https://github.com/jupyter-xeus/xeus-lua
 
 # Features
 
diff --git a/ilua-wrapper.sh b/ilua-wrapper.sh
index 344de5d..b5494f8 100755
--- a/ilua-wrapper.sh
+++ b/ilua-wrapper.sh
@@ -5,4 +5,4 @@
 # Thirdly, if you create a symbolic link to lua in a Python environment of ILua, this invoke
 # Applause by default and it will even work with Jupyter Notebooks without further tweaks.
 cd $(dirname $(readlink -m "$0"))
-exec ./applause -o 2 "$@"
+exec ./applause $APPLAUSE_OPTS "$@"