Guide updates (#5)

* updated guides 
* update definitions

.gitmodules

@@ -1,4 +1,4 @@
 [submodule "definitions"]
 	path = definitions
 	url = [email protected]:renoise/definitions
-	branch = feature/api-docs
+	branch = master

docs/API/README.md

@@ -1,29 +1,26 @@
 # Renoise Lua API Overview
 
-The XXX.API files in this documentation folder will list all available Lua
-functions and classes that can be accessed from scripts in Renoise.
-If you are familiar with Renoise, the names of the classes, functions and
-properties should be self explanitory.
+The API files in this documentation folder will list all available Lua functions and classes that can be accessed from scripts in Renoise. If you are familiar with Renoise, the names of the classes, functions and properties should be self explanitory.
 
 A note about the general API design:
 
 - Whatever you do with the API, you should never be able to fatally crash Renoise. If you manage to do this, then please file a bug report in our forums so we can fix it. All errors, as stupid they might be, should always result in a clean error message from Lua.
 
-- The Renoise Lua API also allows global File IO and external program execution (via os.execute()) which can obviously be hazardous. Please be careful with these, as you would with programming in general...
+- The Renoise Lua API also allows global File IO and external program execution (via `os.execute()`) which can obviously be hazardous. Please be careful with these, as you would with programming in general...
 
 Some notes about the documentation, and a couple of tips:
 
-- All classes, functions in the API, are nested in the namespace (Lua table) "renoise". E.g: to get the application object, you will have to type "renoise.app()"
+- All classes, functions in the API, are nested in the namespace (Lua table) `renoise`. E.g: to get the application object, you will have to type `renoise.app()`
 
-- The API is object-oriented, and thus split into classes. The references will first note the class name (e.g. 'renoise.Application'), then list its Constants, Properties, Functions and Operators. All properties and functions are always listed with their full path to make it clear where they belong and how to access them.
+- The API is object-oriented, and thus split into classes. The references will first note the class name (e.g. `renoise.Application`), then list its Constants, Properties, Functions and Operators. All properties and functions are always listed with their full path to make it clear where they belong and how to access them.
 
-- Nearly all functions are actually "methods", so you have to invoke them via the colon operator ":" E.g. 'renoise.app():show_status("Status Message")' If you're new to Lua, this takes a while to get used to. Don't worry, it'll make sense sooner or later. ;)
+- Nearly all functions are actually *methods*, so you have to invoke them via the colon operator `:` E.g. `renoise.app():show_status("Status Message")` If you're new to Lua, this takes a while to get used to. Don't worry, it'll make sense sooner or later. ;)
 
-- Properties are syntactic sugar for get/set functions. "song().comments" will invoke a function which returns "comments". But not all properties have setters, and thus can only be used as read-only "getters". Those are marked as "**READ-ONLY**".
+- Properties are syntactic sugar for get/set functions. `song().comments` will invoke a function which returns *comments*. But not all properties have setters, and thus can only be used as read-only *getters*. Those are marked as `**READ-ONLY**`.
 
-- All exposed "objects" are read-only (you can not add new fields, properties). In contrast, the "classes" are not. This means you can extend the API classes  with your own helper functions, if needed, but can not add new properties to objects. Objects, like for example the result of "song()", are read-only to make it easier to catch typos. `song().transport.bmp = 80` will fire an error, because there is no such property 'bmp.' You probably meant `song().transport.bpm = 80` here. If you need to store data somewhere, do it in your own tables, objects instead of using the Renoise API objects.
+- All exposed *objects* are read-only (you can not add new fields, properties). In contrast, the *classes* are not. This means you can extend the API classes  with your own helper functions, if needed, but can not add new properties to objects. Objects, like for example the result of `song()`, are read-only to make it easier to catch typos. `song().transport.bmp = 80` will fire an error, because there is no such property 'bmp.' You probably meant `song().transport.bpm = 80` here. If you need to store data somewhere, do it in your own tables, objects instead of using the Renoise API objects.
 
-- "some_property, _observable" means, that there is also an observer object available for the property. An observable object allows you to attach notifiers (global functions or methods) that will be called as soon as a value has changed. Please see Renoise.Document.API for more info about observables and related classes. 
+- *some_property, _observable* means, that there is also an observer object available for the property. An observable object allows you to attach notifiers (global functions or methods) that will be called as soon as a value has changed. Please see Renoise.Document.API for more info about observables and related classes. 
 
 A small example using bpm:
 ```lua
@@ -37,6 +34,6 @@ renoise.song().transport.bpm = 120
 
 The above notifier is called when anything changes the bpm, including your script, other scripts, or anything else in Renoise (you've automated the BPM in the song, entered a new BPM value in Renoise's GUI, whatever...)
 
-Lists like "renoise.song().tracks[]" can also have notifiers. But these will only fire when the list layout has changed: an element was added, removed or elements in the list changed their order. They will not fire when the list values changed. Attach notifiers to the list elements to get such notifications.
+Lists like `renoise.song().tracks[]` can also have notifiers. But these will only fire when the list layout has changed: an element was added, removed or elements in the list changed their order. They will not fire when the list values changed. Attach notifiers to the list elements to get such notifications.
 
 - Can't remember what the name of function XYZ was? In the scripting terminal you can list all methods/properties of API objects (or your own class objects) via the global function `oprint(some_object)` - e.g. `oprint(renoise.song())`. To dump the renoise module/class layout, use `rprint(renoise)`.

docs/SUMMARY.md

@@ -11,12 +11,16 @@
   - [Classes](guide/classes.md)
   - [Observables](guide/observables.md)
   - [Files & Bits](guide/files&bits.md)
+  - [Sockets](guide/sockets.md)
   - [MIDI](guide/midi.md)
   - [OSC](guide/osc.md)
   - [Pattern Iterator](guide/pattern_iterator.md)
   - [Track Automation](guide/track_automation.md)
   - [Sample Buffers](guide/sample_buffer.md)
-  - [*TODO*](guide/TODO.md)
+  - [Keybindings](guide/keybindings.md)
+  - [Menu Entries](guide/menus.md)
+  - [Views](guide/views.md)
+  - [Preferences](guide/preferences.md)
 - [API Reference](API/README.md)
   <!-- API TOC START -->
   - [renoise](API/renoise.md)

docs/guide/classes.md

@@ -1,20 +1,10 @@
 # Classes
 
-Renoises lua API has a simple OO support inbuilt -> `class "MyClass"`. All 
-Renoise API objects use such classes.
+The Lua language has by default no `class` construct. But the Renoises lua API has a simple OO support inbuilt -> `class "MyClass"`. All Renoise API objects use such classes and you can use them too in your tools.
 
 See [luabind docs](https://www.rasterbar.com/products/luabind/docs.html#defining-classes-in-lua)
 for more technical info and below for some simple examples
 
-Something to keep in mind:
-
-* constructor `function MyClass:__init(args)` must be defined for each class, 
-  or the class can't be used to instantiate objects.
-
-* class defs are always global, so even locally defined classes will be 
-  registered globally.
-
-
 ## Examples
 
 ```lua
@@ -74,6 +64,15 @@ for _,animal in pairs(farm) do
 end
 ```
 
+Something to keep in mind:
+
+* constructor `function MyClass:__init(args)` must be defined for each class, 
+  or the class can't be used to instantiate objects.
+
+* class defs are always global, so even locally defined classes will be 
+  registered globally.
+
+
 ## Class operators
 
 You can overload most operators in Lua for your classes. You do this by 

docs/guide/files&bits.md

@@ -1,5 +1,9 @@
 # Files&Bits.lua
 
+In order to access the raw bits and bytes of some data, e.g. to read or write binary (file) streams, you can use the Lua `bit` library. It's built into the Renoise API. There's no need to `require` it.  
+
+See [bit documentation](https://bitop.luajit.org/) for more info and examples.
+
 ```lua
 -- reading integer numbers or raw bytes from a file
 
@@ -43,4 +47,3 @@ print(read_word(file) or "unexpected end of file")
 print(read_dword(file) or "unexpected end of file")
 ```
 
-more bit manipulation? -> See [bit documentation](https://bitop.luajit.org/)

docs/guide/keybindings.md

@@ -0,0 +1,57 @@
+# Keybindings
+
+Tools can add custom key bindings somewhere in Renoise's existing set of bindings, which will be activated and 
+mapped by the user just as any other key binding in Renoise.
+
+Keybindings can be global (applied everywhere in the GUI) or can be local to a specific part of the GUI, like the Pattern Editor.
+
+Please note: there's no way to define default keyboard shortcuts for your entries. Users manually have to bind them in the keyboard prefs pane. As soon as they do, they'll get saved just like any other key binding in Renoise.
+
+To do so, we are using the tool's [add_keybinding](../API/renoise/renoise.ScriptingTool.md#add_keybinding) function.
+
+### Example
+
+```lua
+renoise.tool():add_keybinding {
+  name = "Global:Tools:Example Script Shortcut",
+  invoke = function(repeated)
+    if (not repeated) then -- we ignore soft repeated keys here
+      renoise.app():show_prompt(
+        "Congrats!",
+        "You've pressed a magic keyboard combo "..
+        "which was defined by a scripting tool.",
+        {"OK?"}
+      )
+    end
+  end
+}
+```
+
+### Scopes
+
+The scope, name and category of the key binding use the form: 
+`$scope:$topic_name:$binding_name`:
+
+* `scope` is where the shortcut will be applied, just like those
+in the categories list for the keyboard assignment preference pane.
+Your key binding will only fire, when the scope is currently focused,
+except it's the global scope one.
+Using an unavailable scope will not fire an error, instead it will render
+the binding useless. It will be listed and mappable, but never be invoked.
+
+* `topic_name` is useful when grouping entries in the key assignment pane.
+Use "tool" if you can't come up with something meaningful.
+
+* `binding_name` is the name of the binding.
+
+Currently available scopes are:
+
+See API Docs for [KeybindingEntry](../API/renoise/renoise.ScriptingTool.md#toolkeybindingentry).
+
+### Separating entries
+
+To divide entries into groups (separate entries with a line), prepend one or more dashes to the name, like 
+
+```lua
+"--- Main Menu:Tools:My Tool Group Starts Here"
+```