Add missing language docs

docs/configuration.md

@@ -20,6 +20,8 @@ Specify the order in which sprites are layered, by default the order is alphabet
 layers = ["sprite_name_1", "sprite_name_2"]
 ```
 
+Sprites are listed from back to front.
+
 ## Bitmap Resolution
 
 Controls the resolution handling for bitmap images (PNG, BMP) in your project.
@@ -106,3 +108,5 @@ notes = "NOTES.md" # default is unset
 Notes appear in a Stage comment beneath the goboscript logo.
 The logo is included even when no notes are provided. Comments longer than
 8000 characters are shortened.
+
+The notes path is relative to the project directory.

docs/contributing.md

@@ -78,6 +78,11 @@ If you want to validate some `.sb3` file, use:
 tools/sb3.py path/to/project.sb3 --validate # or `-v`
 ```
 
+## Documentation
+
+Install [uv](https://docs.astral.sh/uv/), then run `pnpm run build:docs` to build
+the docs or `pnpm run dev:docs` for a local preview.
+
 ## Conventions
 
 We use conventional commits. (See `git log --oneline` to understand this)

docs/getting-started/index.md

@@ -62,3 +62,7 @@ If the compilation fails, and you have got errors, the generated `.sb3` file wil
 invalid and should not be opened in Scratch.
 
 Run `goboscript build --help` for more information.
+
+## Shell completions
+
+For Bash completions, run `source <(goboscript completions bash)`.

docs/language/lists.md

@@ -52,6 +52,9 @@ If type is specified, each list item is made-up by N lines where N is the no. of
 
 ## Operations
 
+List indices start at `1`. `item in list_name` returns the first matching index,
+or `0` if absent.
+
 ### Add item to list
 
 ```goboscript
@@ -118,6 +121,8 @@ show list_name;
 hide list_name;
 ```
 
+For a struct list, `show` and `hide` apply to the list monitor for each field.
+
 ### Get random/last item in list
 
 ```goboscript

docs/language/macros.md

@@ -19,11 +19,12 @@ Include the contents of a file.
 The `.gs` extension is optional. If not specified (recommended), the file extension will
 be added automatically.
 
-If the include path is a directory, the file inside the directory with the same name as
-the directory will be included.
-
 By default, the include path is relative to the project root directory. To include a
-file relative to the current file, use `./` or `../`
+file relative to the current file, use `./` or `../`. Paths starting with `std/`
+refer to the [standard library](../standard-library.md).
+
+Each header is included once per sprite. Macro definitions do not cross sprite
+boundaries.
 
 !!! tip
     [`bkpk.py`](https://gist.github.com/aspizu/c81452bfb7a333d0819f0279e51e078a) is a small
@@ -94,9 +95,14 @@ all overloads for that name at once.
 
 ## Conditional compilation
 
+`%if name` checks whether a macro without arguments is defined, even if its value
+is `0`.
+
 ```goboscript
 %if macro_name
     code
+%else
+    other_code
 %endif
 ```
 
@@ -108,6 +114,8 @@ all overloads for that name at once.
 
 ## Concatenate Tokens
 
+`CONCAT` expands its arguments before joining them. Each must expand to one token.
+
 ```goboscript
 CONCAT(prefix, suffix) # becomes prefixsuffix
 ```

docs/language/operators.md

@@ -45,6 +45,22 @@
 | `x not in y` | ![](../assets/notin.png){width="125"} |
 | `x[y]` | ![](../assets/letterof.png){width="125"} |
 
+## Operator Precedence
+
+Highest precedence first:
+
+| Order | Operators | Grouping |
+| --- | --- | --- |
+| 1 | Calls `f(...)`, indexing `x[i]`, and field access `x.field` | Left to right |
+| 2 | Unary operators, including `-`, `not`, and `length` | Right to left |
+| 3 | `*`, `/`, `//`, `%` | Left to right |
+| 4 | `+`, `-` | Left to right |
+| 5 | `<`, `<=`, `>`, `>=` | Left to right |
+| 6 | `&` | Right to left |
+| 7 | `in`, `not in`, `==`, `!=` | Left to right |
+| 8 | `and` | Left to right |
+| 9 | `or` | Left to right |
+
 ## Reporters
 
 ### pick random () to ()

docs/language/reporters/sensing.md

@@ -242,10 +242,19 @@ user_answer = answer();
 
 ### difficult to name thing of thing block
 
+Use `object."property"` to read a sprite or Stage property or variable. The object
+may be an expression; the property must be a string literal.
+
 ```goboscript
 backdrop_number = "Stage"."backdrop #";
+other_score = "main"."score";
 ```
 
 ```scratchblocks
 ([backdrop #] of (Stage v))
 ```
+
+Sprite properties include `"x position"`, `"y position"`, `"direction"`,
+`"costume #"`, `"costume name"`, `"size"`, and `"volume"`. For the Stage, use
+`"backdrop #"`, `"backdrop name"`, or `"volume"`. To read a variable, use its name
+as the property string.

docs/language/reporters/turbowarp.md

@@ -0,0 +1,12 @@
+# TurboWarp Reporters
+
+Use these boolean reporters without parentheses:
+
+| Reporter            | Reports true when                                            |
+| ------------------- | ------------------------------------------------------------ |
+| `$tw_is_compiled`   | The script is running through a supported player's compiler. |
+| `$tw_is_turbowarp`  | The project is running in TurboWarp.                         |
+| `$tw_is_forkphorus` | The project is running in forkphorus.                        |
+
+The compiler check happens at runtime in the player. See the
+[TurboWarp blocks guide](https://docs.turbowarp.org/blocks).

docs/language/variables.md

@@ -33,6 +33,16 @@ If a variable is assigned to in `stage.gs`, it will be declared as **for all spr
 Variables are by-default declared as **for this sprite only**. If you want to declare a
 variable **for all sprites**, assign to it in `stage.gs`.
 
+## Cloud Variables
+
+Declare cloud variables in `stage.gs`:
+
+```goboscript
+cloud high_score;
+```
+
+Inside a script, you can also declare one with `cloud high_score = 100;`.
+
 ## Local Variables
 
 Local variables are accessible only within the procedure they are declared in.
@@ -77,3 +87,5 @@ show variable_name;
 ```goboscript
 hide variable_name;
 ```
+
+For a struct variable, `show` and `hide` apply to the monitor for each field.

mkdocs.yml

@@ -38,6 +38,7 @@ nav:
           - Sound: language/reporters/sound.md
           - Sensing: language/reporters/sensing.md
           - Music: language/reporters/music.md
+          - TurboWarp: language/reporters/turbowarp.md
       - Custom Blocks: language/custom-blocks.md
       - Functions: language/functions.md
       - Enums: language/enums.md