docs: Some editing and clarification

- Edited hacking and interfacing sections for clarity
- Explicit warning about incomplete commands section
- Rewrites and edits in the intro

doc/source/commands.rst

@@ -1,6 +1,10 @@
 Command reference
 =================
 
+This documentation is still missing many parts. Refer to the [Nodebox
+documentation](https://www.nodebox.net/code/index.php/Reference) for the best
+reference in the meantime.
+
 Drawing shapes
 --------------
 
@@ -275,6 +279,12 @@ Stop applying strokes to new paths.
   * return: Color object containing the color.
 
 
+Color
+-----
+
+[TODO: Describe all the possible color syntax options, and link the above
+commands to these.]
+
 Text
 ----
 

doc/source/hacking.rst

@@ -1,61 +1,46 @@
 Hacking Shoebot
 ===============
 
-This section is for the Python hackers who want to get dirty with canvas manipulation and so on.
+This section is for the Python hackers who want to get into the more involved
+features of Shoebot.
 
 Using Shoebot as a Python module
 --------------------------------
 
-Shoebot can also be loaded as a module. For now, scripts taking advantage of
-this must be placed inside the shoebot dir.
-
-After including an import statement,
+Shoebot can be easily loaded as a module inside a Python script.
 
 .. code-block:: python
 
     import shoebot
 
-a NodeBot object needs to be created, and all further drawing commands can be 
-called on that instance.
-
-The quickest way is to use the create_bot function, it sets up an appropriate
-canvas and lets us draw to it.
-
-.. code-block:: python
-
+    # set up a canvas
     bot = shoebot.create_bot(outputfile="output.svg")
-    bot.size(400,400)
-    bot.rect(10,10,100,100)
 
-When you're finished with drawing, just call
+    # size() needs to be called first
+    bot.size(400,400)
 
-.. code-block:: python
+    # now we can draw!
+    bot.rect(10,10,100,100)
 
+    # finish() should be called after all drawing commands
     bot.finish()
 
-and your output file should be created.
-
-Also, you can save snapshots of the current state if the Bot instance like so:
+Take a snapshot of the current state:
 
 .. code-block:: python
 
     bot.snapshot("snap.png")
 
-You can even call external Shoebot/Nodebox scripts from your Python script:
+Run a Shoebot/Nodebox script:
 
 .. code-block:: python
 
     bot.run("example.bot")
 
-
-Working directly with Cairo
----------------------------
-TODO
-
 Command-line usage
 ------------------
 
-Enter sbot -h to see available options, they are split into logical groups:
+Enter `sbot -h` to see all the available options:
 
 .. code:: text
 
@@ -130,3 +115,10 @@ Debugging / Dev flags:
                             disable running bot code in background thread.
       -V, --verbose         Show internal shoebot error information in traceback
 
+
+Working directly with Cairo
+---------------------------
+
+TODO
+
+

doc/source/interfacing.rst

@@ -1,15 +1,16 @@
 Interfacing with the outside world
 ==================================
 
-Shoebot is not limited to what you write inside your .bot file; you can open your sketch for receiving and reacting to data from outside applications and environments.
+Shoebot is not limited to what you write inside your .bot file; you can open
+your sketch for receiving and reacting to data from outside applications and
+environments.
 
-Introducing live variables
---------------------------
+Live variables
+--------------
 
-These can be set from the commandline using JSON syntax,
---vars '{ "varname": value }'
+These can be set from the commandline using JSON syntax:
 
-$ sbot -w --vars='{ "hue": 32 }' examples/basic/var_number_hsb.bot
+    $ sbot -w --vars='{ "hue": 32 }' examples/basic/var_number_hsb.bot
 
 You can also set these values from the socketserver (see below),
 or running the live shell.
@@ -18,9 +19,11 @@ or running the live shell.
 Using the live variables GUI
 ----------------------------
 
-When a script uses the var keyword, an element will appear in the live variables GUI.
+When a script uses the `var` keyword, the corresponding widget will appear in
+the live variables GUI.
 
-The following code will make a slider from 0-100 starting at 25
+The following code will make a slider with a minimum value of 0, a maximum
+value of 100, and an initial (default) value of 25.
 
 .. code-block:: python
 
@@ -31,23 +34,30 @@ The following code will make a slider from 0-100 starting at 25
 Socketserver
 ------------
 
-If shoebot is run with  --serverport  shoebot will run a socketserver.
+If shoebot is run with the `--serverport` option, a socket server will also be
+started. Socket servers can accept connections from other applications or even
+across the network in order to set variables inside Shoebot scripts. The
+default socket server port is 7777.
 
-You can run one of the examples on the default port of 7777 like this:
+    $ sbot -ws -p examples/animation/hypnoval.bot
+    Listening on port 7777...
 
-$ sbot -ws -p examples/animation/hypnoval.bot
-Listening on port 7777...
+Once it's running, it's easy to connect with telnet:
 
-Once it's running it's easy to connect with telnet:
+    $ telnet 127.0.0.1 7777
 
-$ telnet 127.0.0.1 7777
+This gets you into the shell, where you can use the commands below to list and
+set variables, rewind and go to frames. 
 
-This gets you into the shell, where you can use commands to list and
-set variables, rewind and go to frames.
+The following commands can also be sent through other applications like Pure
+Data; there is a simple PD example in `examples/socketcontrol/helloworld.pd`.
 
+Be sure to take a look at the socket server examples in action inside the
+`examples/socketserver` directory.
 
-Commands
-~~~~~~~~
+
+Socketserver commands
+---------------------
 
 
     Playback Commands
@@ -81,27 +91,26 @@ Commands
     ==================   ======================================
 
 
-Socket server examples are available in  examples/socketserver
 
 
-Editors/IDEs and the live shell
--------------------------------
+Live coding: Editors/IDEs and the live shell
+--------------------------------------------
 
-Shoebot provides a live shell for communication with editors.
+Shoebot provides a live shell for communication with text editors.
 
-All the commands in the socketserver are available as well as load_base64
+All the socket server commands above are available, as well as `load_base64`
 which allows livecoding.
 
 To experiment with the livecoding shell, run an example with the -l option
 
-$ sbot -wl examples/animation/hypnoval.bot
+    $ sbot -wl examples/animation/hypnoval.bot
 
 This has all the commands that the socket server has, and extra commands
 that can be useful for an editor or IDE.
 
 
-Commands
-~~~~~~~~
+Live Shell commands
+-------------------
 
     Live Shell Commands
 
@@ -122,10 +131,8 @@ create_bot and output image formats (see 'using shoebot as a module').
 
 
 
-
 Pure Data
 ---------
-* There is an example of linking puredata with shoebot in  examples/socketcontrol/helloworld.pd
 
 
 

doc/source/intro.rst

@@ -1,16 +1,33 @@
 Introduction
 ============
 
-Shoebot is, simply put, an application for the purpose of scripting pictures. In
-case you're familiar with the 'sketch' approach of Processing and Nodebox, you
-can skip over to the ___ section.
+Shoebot is a tool to automate the process of drawing vector graphics using a
+minimal and easy-to-understand syntax.
 
 Using code to create and tweak shapes, colours and features is a model that
-departs from the WYSIWYG paradigm that is present in applications like GIMP and
-Inkscape (Adobe Photoshop and Illustrator being the proprietary alternatives).
-The most evident purpose of scripting is to automate repetitive tasks; for
-example, one could create an image with 2000 randomly positioned circles with
-two lines of code:
+departs from the WYSIWYG paradigm that is present in mainstream graphics
+applications. Shoebot was inspired by a rich lineage of tools dedicated to
+generative creativity:
+
+  * Nodebox
+  * Drawbot
+  * Processing
+  * Paper.js
+  * Scriptographer
+  * Design By Numbers
+
+Shoebot is a fork/rewrite of [Nodebox
+1](https://www.nodebox.net/code/index.php/Home), which is itself based on
+[DrawBot](http://www.drawbot.com/); there are slightly different syntax
+approaches in each language, and Shoebot tries to support both.
+
+
+Why scripting?
+--------------
+
+The most evident purpose of scripting is to automate repetitive
+tasks; for example, one could create an image with 2000 randomly positioned
+circles with two lines of code:
 
 .. shoebot::
     :snapshot:
@@ -19,24 +36,28 @@ two lines of code:
     for step in range(2000):
         ellipse(random(WIDTH), random(HEIGHT), 10, 10)
 
-This is something that you'd find a bit more convoluted to create using your
-mouse and keyboard to draw on the canvas manually. While the GUI editing
-applications certainly have many upsides to them, using scripts to control
+This is something that would be much more involved to create using the
+mouse and keyboard to draw on the canvas manually. Using scripts to control
 your output offers many new uses and possibilities for image generation and
 manipulation. 
 
-One common use for this kind of approach is the creation of dynamic systems
-to generate drawings, be them 'generative' (systems that grow, often
-unpredictably, from a set of initial parameters) or 'procedural' (systems...)
+One common use for this kind of approach is the creation of dynamic systems to
+generate drawings, be them 'generative' (systems that grow, often
+unpredictably, from a set of initial parameters) or 'procedural' (rule-based
+systems).
+
 
 Capabilities
 ------------
 
-The output of Shoebot scripts can be exported to a few vector file formats --
-SVG, Postscript (.ps) and PDF -- as well as the PNG bitmap format.
+[TODO: Make links to other sections.]
+
+The output of Shoebot scripts can be exported to the most widely used vector
+file formats -- SVG, PDF and PostScript -- as well as the PNG bitmap
+format.
 
 A script's variables can be accessed through an automatically generated GUI or
-even from outside applications (see the ___ section).
+even from outside applications (see the Interfacing section).
 
 There's many libraries ported from Nodebox which enable SVG importing, Spiro
 splines, image fetching and manipulation and other goodies; there's also Shoebot