update starter pack (#1)

* update starter pack - include definitions - add a web link to the api book in the starter pack root - use relative links in book, remove url_root argument from generate app - archive using XRNX_Starter_Pack as name
renoise · Aug 2, 2024 · e77f76a · e77f76a
1 parent 997b63c
commit e77f76a
Show file tree

Hide file tree

Showing 110 changed files with 2,305 additions and 2,297 deletions.
diff --git a/.github/workflows/archive.yml b/.github/workflows/archive.yml
@@ -16,20 +16,22 @@ jobs:
 
       - name: Build the book
         run: |
-          ./generate/build.sh "3.9.3" ""
+          ./generate/build.sh "3.9.3"
           cargo install mdbook
           cargo install mdbook-linkcheck
           mdbook build
 
       - name: Create XRNX_Starter_Pack
         run: |
           mkdir dist
-          cp -rf book dist/docs
+          cp -rf definitions dist/definitions
+          cp -rf book/html dist/docs
           cp -rf tools dist/tools
-          cd dist && zip -r -q ../XRNX_Starter_Pack.zip .
+          rm -rf dist/*/.git dist/*/.gitignore
+          echo -e '<html>\n<body>\n<script type="text/javascript">\n\twindow.location.href = "./docs/index.html";\n</script>\n</body>\n</html>' > dist/docs.html 
         
       - name: Archive
         uses: actions/upload-artifact@v4
         with:
-          name: Archive
-          path: XRNX_Starter_Pack.zip
+          name: XRNX_Starter_Pack
+          path: dist
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -1,6 +1,9 @@
 name: Build and Deploy mdBook
 
-on: [push]
+on:
+  push:
+    branches:
+      - master
 
 jobs:
   build:
@@ -16,7 +19,7 @@ jobs:
 
       - name: Build the book
         run: |
-          ./generate/build.sh "3.9.3" "/xrnx/"
+          ./generate/build.sh "3.9.3"
           cargo install mdbook
           cargo install mdbook-linkcheck
           mdbook build
@@ -25,7 +28,7 @@ jobs:
         uses: actions/upload-pages-artifact@v3
         with:
           name: github-pages
-          path: ./book
+          path: ./book/html
 
   deploy:
     # Add a dependency to the build job

diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 Cargo.lock
 /book/
+/dist/
 /generate/Cargo.lock
 /generate/target/
 /generate/lua-language-server/

diff --git a/README.md b/README.md
@@ -4,20 +4,24 @@
 
 Welcome to the Renoise Lua Scripting Repository! This site is for developers who want to write their own scripts & tools for [Renoise](http://www.renoise.com/). If you are only interested in downloading tools for Renoise and not in developing your own, please have a look at the [Renoise Tools Page](http://tools.renoise.com/).
 
-### Getting Started
+### Documentation & Guides
 
-Read the [Renoise Scripting Development Book](https://renoise.github.io/xrnx)
+Read the [Renoise Scripting Development Book](https://renoise.github.io/xrnx).
 
 This book is highly recommended for anyone who wants to get into all this Renoise scripting. Please read it first to get an overview of what's needed to develop tools for Renoise. It contains an introduction, some guides and the full API documentation.
 
-### Example tools
+### Example Tools
 
-In addition to the documentation, this repository also contains some sample tools in the [tools folder](./tools) that are intended for new tool developers only. You can download them, install them, and read them as an interactive tutorial.
+In addition to the documentation, this repository also contains some sample tools in the [tools folder](./tools) that are intended for new tool developers only. You can download them, install them, and read them as an interactive tutorial. The example tools are also included in the XRNX Starter pack (see below).
 
-See https://github.com/renoise/tools for tools created by the Renoise team that actually do something. 
+See [github.com/renoise/tools](https://github.com/renoise/tools) for tools created by the Renoise team that actually do something. 
+
+### Starter Pack
+
+The scripting development book, API definition and example tools, can also be downloaded as a "starter pack" bundle file from the [releases page](https://github.com/renoise/xrnx/releases).
 
 ### Need more help?
 
 For any questions regarding the Lua API or this repository, please have a look at the [Renoise Scripting Development Forum](https://forum.renoise.com/c/renoise-tool-development).
 
-*Have fun scripting and hacking Renoise!
+*Have fun scripting and hacking Renoise!*
diff --git a/book.toml b/book.toml
@@ -12,5 +12,5 @@ create-missing = false
 default-theme = "dark"
 preferred-dark-theme = "coal"
 
-#[output.linkcheck]
-#warning-policy = "ignore"
+[output.linkcheck]
+warning-policy = "ignore"
diff --git a/docs/API/builtins/table.md b/docs/API/builtins/table.md
@@ -3,22 +3,22 @@ A built-in type representing associative arrays, [see details](https://www.lua.o
 
 ---  
 ## Functions
-### `clear`(t : [`table`](/API/builtins/table.md)) {#clear}
+### `clear`(t : [`table`](../../API/builtins/table.md)) {#clear}
 Recursively clears and removes all table elements.
-### `copy`(t : [`table`](/API/builtins/table.md)) {#copy}
-`->`[`table`](/API/builtins/table.md)  
+### `copy`(t : [`table`](../../API/builtins/table.md)) {#copy}
+`->`[`table`](../../API/builtins/table.md)  
 
 Copy the metatable and all first level elements of the given table into a
 new table. Use table.rcopy to do a recursive copy of all elements
-### `count`(t : [`table`](/API/builtins/table.md)) {#count}
+### `count`(t : [`table`](../../API/builtins/table.md)) {#count}
 Count the number of items of a table, also works for non index
 based tables (using pairs).
 ### examples:
 ```lua
 t = {["a"]=1, ["b"]=1}; print(table.count(t)) --> 2
 ```
-### `create`(t : [`table`](/API/builtins/table.md)[`?`](/API/builtins/nil.md)) {#create}
-`->`[`table`](/API/builtins/table.md) | tablelib  
+### `create`(t : [`table`](../../API/builtins/table.md)[`?`](../../API/builtins/nil.md)) {#create}
+`->`[`table`](../../API/builtins/table.md) | tablelib  
 
 Create a new, or convert an exiting table to an object that uses the global
 'table.XXX' functions as methods, just like strings in Lua do.
@@ -27,8 +27,8 @@ Create a new, or convert an exiting table to an object that uses the global
 t = table.create(); t:insert("a"); rprint(t) -> [1] = a;
 t = table.create{1,2,3}; print(t:concat("|")); -> "1|2|3";
 ```
-### `find`(t : [`table`](/API/builtins/table.md), value : [`any`](/API/builtins/any.md), start_index : [`integer`](/API/builtins/integer.md)[`?`](/API/builtins/nil.md)) {#find}
-`->`key_or_nil : [`string`](/API/builtins/string.md) | [`number`](/API/builtins/number.md)[`?`](/API/builtins/nil.md)  
+### `find`(t : [`table`](../../API/builtins/table.md), value : [`any`](../../API/builtins/any.md), start_index : [`integer`](../../API/builtins/integer.md)[`?`](../../API/builtins/nil.md)) {#find}
+`->`key_or_nil : [`string`](../../API/builtins/string.md) | [`number`](../../API/builtins/number.md)[`?`](../../API/builtins/nil.md)  
 
 Find first match of *value* in the given table, starting from element
 number *start_index*.<br>
@@ -40,8 +40,8 @@ t = {a=1, b=2}; table.find(t, 2) --> "b"
 t = {"a", "b", "a"}; table.find(t, "a", 2) --> "3"
 t = {"a", "b"}; table.find(t, "c") --> nil
 ```
-### `is_empty`(t : [`table`](/API/builtins/table.md)) {#is_empty}
-`->`[`boolean`](/API/builtins/boolean.md)  
+### `is_empty`(t : [`table`](../../API/builtins/table.md)) {#is_empty}
+`->`[`boolean`](../../API/builtins/boolean.md)  
 
 Returns true when the table is empty, else false and will also work
 for non indexed tables
@@ -50,22 +50,22 @@ for non indexed tables
 t = {};          print(table.is_empty(t)); -> true;
 t = {66};        print(table.is_empty(t)); -> false;
 t = {["a"] = 1}; print(table.is_empty(t)); -> false;
-### `keys`(t : [`table`](/API/builtins/table.md)) {#keys}
-`->`[`table`](/API/builtins/table.md)  
+### `keys`(t : [`table`](../../API/builtins/table.md)) {#keys}
+`->`[`table`](../../API/builtins/table.md)  
 
 Return an indexed table of all keys that are used in the table.
 ### examples:
 ```lua
 t = {a="aa", b="bb"}; rprint(table.keys(t)); --> "a", "b"
 t = {"a", "b"};       rprint(table.keys(t)); --> 1, 2
 ```
-### `rcopy`(t : [`table`](/API/builtins/table.md)) {#rcopy}
-`->`[`table`](/API/builtins/table.md)  
+### `rcopy`(t : [`table`](../../API/builtins/table.md)) {#rcopy}
+`->`[`table`](../../API/builtins/table.md)  
 
 Deeply copy the metatable and all elements of the given table recursively
 into a new table - create a clone with unique references.
-### `values`(t : [`table`](/API/builtins/table.md)) {#values}
-`->`[`table`](/API/builtins/table.md)  
+### `values`(t : [`table`](../../API/builtins/table.md)) {#values}
+`->`[`table`](../../API/builtins/table.md)  
 
 Return an indexed table of all values that are used in the table
 ### examples:

diff --git a/docs/API/modules/bit.md b/docs/API/modules/bit.md
@@ -5,8 +5,8 @@ Integer, Bit Operations, provided by <http://bitop.luajit.org/>
 
 ---  
 ## Functions
-### `arshift`(x : [`integer`](/API/builtins/integer.md), n : [`integer`](/API/builtins/integer.md)) {#arshift}
-`->`[`integer`](/API/builtins/integer.md)  
+### `arshift`(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) {#arshift}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns the bitwise arithmetic right-shift of its first argument by the
 number of bits given by the second argument.
@@ -15,27 +15,27 @@ Logical shifts treat the first argument as an unsigned number and shift in
 0-bits. Arithmetic right-shift treats the most-significant bit as a sign bit
 and replicates it. Only the lower 5 bits of the shift count are used (reduces
 to the range [0..31]).
-### `band`(x1 : [`integer`](/API/builtins/integer.md), ...[`integer`](/API/builtins/integer.md)) {#band}
-`->`[`integer`](/API/builtins/integer.md)  
+### `band`(x1 : [`integer`](../../API/builtins/integer.md), ...[`integer`](../../API/builtins/integer.md)) {#band}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns the bitwise and of all of its arguments. Note that more than two
 arguments are allowed.
-### `bnot`(x : [`integer`](/API/builtins/integer.md)) {#bnot}
-`->`[`integer`](/API/builtins/integer.md)  
+### `bnot`(x : [`integer`](../../API/builtins/integer.md)) {#bnot}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns the bitwise **not** of its argument.
-### `bor`(x1 : [`integer`](/API/builtins/integer.md), ...[`integer`](/API/builtins/integer.md)) {#bor}
-`->`[`integer`](/API/builtins/integer.md)  
+### `bor`(x1 : [`integer`](../../API/builtins/integer.md), ...[`integer`](../../API/builtins/integer.md)) {#bor}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns the bitwise or of all of its arguments. Note that more than two
 arguments are allowed.
-### `bswap`(x : [`integer`](/API/builtins/integer.md)) {#bswap}
-`->`[`integer`](/API/builtins/integer.md)  
+### `bswap`(x : [`integer`](../../API/builtins/integer.md)) {#bswap}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Swaps the bytes of its argument and returns it. This can be used to convert
 little-endian 32 bit numbers to big-endian 32 bit numbers or vice versa.
-### `lshift`(x : [`integer`](/API/builtins/integer.md), n : [`integer`](/API/builtins/integer.md)) {#lshift}
-`->`[`integer`](/API/builtins/integer.md)  
+### `lshift`(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) {#lshift}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns the bitwise logical left-shift of its first argument by the number of
 bits given by the second argument.
@@ -44,26 +44,26 @@ Logical shifts treat the first argument as an unsigned number and shift in
 0-bits. Arithmetic right-shift treats the most-significant bit as a sign bit
 and replicates it. Only the lower 5 bits of the shift count are used (reduces
 to the range [0..31]).
-### `rol`(x : [`integer`](/API/builtins/integer.md), n : [`integer`](/API/builtins/integer.md)) {#rol}
-`->`[`integer`](/API/builtins/integer.md)  
+### `rol`(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) {#rol}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns bitwise left rotation of its first argument by the number of bits
 given by the second argument. Bits shifted out on one side are shifted back
 in on the other side.
 
 Only the lower 5 bits of the rotate count are used (reduces to the range
 [0..31]).
-### `ror`(x : [`integer`](/API/builtins/integer.md), n : [`integer`](/API/builtins/integer.md)) {#ror}
-`->`[`integer`](/API/builtins/integer.md)  
+### `ror`(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) {#ror}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns bitwise right rotation of its first argument by the number of bits
 given by the second argument. Bits shifted out on one side are shifted back
 in on the other side.
 
 Only the lower 5 bits of the rotate count are used (reduces to the range
 [0..31]).
-### `rshift`(x : [`integer`](/API/builtins/integer.md), n : [`integer`](/API/builtins/integer.md)) {#rshift}
-`->`[`integer`](/API/builtins/integer.md)  
+### `rshift`(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) {#rshift}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns the bitwise logical right-shift of its first argument by the number of
 bits given by the second argument.
@@ -72,20 +72,20 @@ Logical shifts treat the first argument as an unsigned number and shift in
 0-bits. Arithmetic right-shift treats the most-significant bit as a sign bit
 and replicates it. Only the lower 5 bits of the shift count are used (reduces
 to the range [0..31]).
-### `tobit`(x : [`integer`](/API/builtins/integer.md)) {#tobit}
-`->`[`integer`](/API/builtins/integer.md)  
+### `tobit`(x : [`integer`](../../API/builtins/integer.md)) {#tobit}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Normalizes a number to the numeric range for bit operations and returns it.
 This function is usually not needed since all bit operations already normalize
 all of their input arguments. Check the operational semantics for details.
-### `tohex`(x : [`integer`](/API/builtins/integer.md), n : [`integer`](/API/builtins/integer.md)[`?`](/API/builtins/nil.md)) {#tohex}
+### `tohex`(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)[`?`](../../API/builtins/nil.md)) {#tohex}
 Converts its first argument to a hex string. The number of hex digits is
 given by the absolute value of the optional second argument. Positive numbers
 between 1 and 8 generate lowercase hex digits. Negative numbers generate
 uppercase hex digits. Only the least-significant 4*|n| bits are used. The
 default is to generate 8 lowercase hex digits.
-### `xor`(x1 : [`integer`](/API/builtins/integer.md), ...[`integer`](/API/builtins/integer.md)) {#xor}
-`->`[`integer`](/API/builtins/integer.md)  
+### `xor`(x1 : [`integer`](../../API/builtins/integer.md), ...[`integer`](../../API/builtins/integer.md)) {#xor}
+`->`[`integer`](../../API/builtins/integer.md)  
 
 Returns the bitwise xor of all of its arguments. Note that more than two
 arguments are allowed.  

diff --git a/docs/API/modules/global.md b/docs/API/modules/global.md
@@ -2,8 +2,8 @@
 
 ---  
 ## Functions
-### `class`(name : [`string`](/API/builtins/string.md)) {#class}
-`->`[`function`](/API/builtins/function.md)  
+### `class`(name : [`string`](../../API/builtins/string.md)) {#class}
+`->`[`function`](../../API/builtins/function.md)  
 
 Luabind "class" registration. Registers a global class object and returns a
 closure to optionally set the base class.
@@ -43,31 +43,31 @@ class 'Mammal' (Animal)
 local mamal = Mammal("Cow")
 mamal:show()
 ```
-### `objinfo`(object : [`userdata`](/API/builtins/userdata.md)) {#objinfo}
-`->`[`string`](/API/builtins/string.md)`[]`  
+### `objinfo`(object : [`userdata`](../../API/builtins/userdata.md)) {#objinfo}
+`->`[`string`](../../API/builtins/string.md)`[]`  
 
 Return a string which lists properties and methods of class objects.
-### `oprint`(object : [`userdata`](/API/builtins/userdata.md)) {#oprint}
+### `oprint`(object : [`userdata`](../../API/builtins/userdata.md)) {#oprint}
 Dumps properties and methods of class objects (like renoise.app()).
-### `rawequal`(obj1 : [`any`](/API/builtins/any.md), obj2 : [`any`](/API/builtins/any.md)) {#rawequal}
+### `rawequal`(obj1 : [`any`](../../API/builtins/any.md), obj2 : [`any`](../../API/builtins/any.md)) {#rawequal}
 
 Checks whether v1 is equal to v2, without invoking the `__eq` metamethod.
 
 [View documents](http://www.lua.org/manual/5.4/manual.html#pdf-rawequal)
 ### `ripairs`(table : <T:table>) {#ripairs}
-`->`fun(table: <V>[], i?: integer):integer, <V>, <T:table>, i : [`integer`](/API/builtins/integer.md)  
+`->`fun(table: <V>[], i?: integer):integer, <V>, <T:table>, i : [`integer`](../../API/builtins/integer.md)  
 
 An iterator like ipairs, but in reverse order.
 ### examples:
 ```lua
 t = {"a", "b", "c"}
 for k,v in ripairs(t) do print(k, v) end -> "3 c, 2 b, 1 a"
 ```
-### `rprint`(value : [`any`](/API/builtins/any.md)) {#rprint}
+### `rprint`(value : [`any`](../../API/builtins/any.md)) {#rprint}
 Recursively dumps a table and all its members to the std out (console).
 This works for standard Lua types and class objects as well.
-### `tostring`(pattern_line : [`renoise.PatternLine`](/API/renoise/renoise.PatternLine.md)) {#tostring}
-`->`[`string`](/API/builtins/string.md)  
+### `tostring`(pattern_line : [`renoise.PatternLine`](../../API/renoise/renoise.PatternLine.md)) {#tostring}
+`->`[`string`](../../API/builtins/string.md)  
 
 
 Receives a value of any type and converts it to a string in a human-readable format.
@@ -78,8 +78,8 @@ For complete control of how numbers are converted, use [string.format](http://ww
 
 
 [View documents](http://www.lua.org/manual/5.4/manual.html#pdf-tostring)
-### `type`(value : [`any`](/API/builtins/any.md)) {#type}
-`->`[`string`](/API/builtins/string.md)  
+### `type`(value : [`any`](../../API/builtins/any.md)) {#type}
+`->`[`string`](../../API/builtins/string.md)  
 
 
 Returns the type of its only argument, coded as a string. The possible results of this function are `"nil"` (a string, not the value `nil`), `"number"`, `"string"`, `"boolean"`, `"table"`, `"function"`, `"thread"`, and `"userdata"`.