update documentation

README.org

@@ -2,37 +2,46 @@
 ** Why do I even?
 [[https://orgmode.org/][Org-mode]] makes [[http://literateprogramming.com/][literate programming]] easy via [[https://orgmode.org/worg/library-of-babel.html][Library of Babel]]. Il simply allows to mix text with executable /code blocks/ (which can also be extracted (/tangled/) into separate, executable files. The beauty the Library of Babel implementation in org-mode lies in the fact that it supports many languages. I craved support for [[https://github.com/supercollider/supercollider][SuperCollider]] and craving became an itch when I needed to document a working pipeline alternating between executing sclang and shell scripts. I scratched an itch with this little module.
 ** How to install?
-First of all, you will need emacs and SuperCollider (with emacs support) installed. Modern emacsen (>25) and Spacemacs come with bundled org-mode. At this point I am the sole user of this plugin and have just written it so I am not itching yet for MELPA or inclusion in the official org-mode repositories, so installation is manual. You can either drop [[file:ob-sclang.el]] somewhere in your Emacs' path or add it to =.init= file:
+First of all, you will need emacs and SuperCollider (with emacs support) installed. Modern emacsen (>25) and Spacemacs come with bundled org-mode. At this point I am the sole user of this plugin and have just written it so I am not itching yet for MELPA or inclusion in the official org-mode repositories, so installation is manual. You can either drop [[file:ob-sclang.el]] somewhere in your Emacs' path or add its containing directory to ~load-path~ in =.init= file:
 #+BEGIN_SRC elisp
-(add-to-list 'load-path "/path/to/ob-sclang.el")
+ (add-to-list 'load-path "/path/to/ob-sclang/")
 #+END_SRC
 
 You will also have to add it to =(org-babel-do-load-languages)=
 #+BEGIN_SRC elisp
+(require 'ob-sclang)
 (org-babel-do-load-languages
- '(org-babel-load-languages
-   (quote
-    ((sclang . t)))))
+    'org-babel-load-languages
+    '((sclang . t)))
 #+END_SRC
 ** And then?
-well, then you type a clock like this one:
-#+BEGIN_SRC org :results none
-#+BEGIN_SRC sclang
-"boo".postln;
+well, then you type a block like this one:
+#+BEGIN_SRC org
+  ,#+BEGIN_SRC sclang
+    "boo".postln;
+  ,#+END_SRC
 #+END_SRC
+And after you hit /C-c C-c/ you should see the string appear in your =SCLang:PostBuffer*=
+
+You can also include variables to be passed to you sclang code:
+#+BEGIN_SRC org
+  ,#+BEGIN_SRC sclang :var boo="hoo" :var pi=3.14159 :var year=2000 :var buf='foo
+    boo.postln;
+    pi.postln;
+    year.postln;
+    buf.postln;
+  ,#+END_SRC
 #+END_SRC
-And you should see the string appear in your =SCLang:PostBuffer*=
+
 *Note:*, that if you have not already started SuperCollider process, the plugin will do it for you as soon as you create a source block of type =sclang=.
 ** Known issues
 At this point, this plugin has a very crude functionality. It allows unidirectional control of SuperCollider process running inside Emacs. As such, here is a list of issues:
 
 - sclang process has a tendency to replace Emacs frames with =Workspace= and =PostBuffer= when it lunches, therefore if have not already started sclang, your code block with start it for you, but your current buffer will loose focus.
-- There is no support for any parameters that code blocks usually support
-- The code you execute will not return anything back to the document you are working in
+- The code you execute will not return anything back to the document you are working in (well, it just prints back all lines it executed so simply use =:results none= to limit the noise.
 
 I may raise the first point with the current sclang-mode maintainer...
-I will probably address the second point in the near future. I have not used this set up much yet (actually, almost at all, as I just scratched my itch and only now I am ready to complete the project at hand) but could see the usefulness of passing variables from other code blocks to sclang.
 
-The last point is probably more problematic but it may be useful to get some datatypes from sclang.
+The last point is probably more problematic but it may be useful to get some datatypes from sclang. It merits some thought.
 
 Of course feel free to open questions, suggestions, discussions and even pull requests.