chore: Backport #3190 to web (#3194)

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>

web/book/src/reference/stdlib/transforms/join.md

@@ -9,11 +9,12 @@ join side:{inner|left|right|full} table (condition)
 ## Parameters
 
 - `side` specifies which rows to include, defaulting to `inner`.
-- _table_ - a reference to a relation, possibly including an assignment, e.g.
-  `var= ...`
+- _table_ - a reference to a relation, possibly including an alias, e.g.
+  `a=artists`
 - _condition_ - a boolean condition
-  - If the condition evaluates to True, the rows will be joined
-  - If name is the same from both tables, it can be expressed with only `==col`.
+  - If the condition evaluates to true for a given row, the row will be joined
+  - If name is the same from both tables, it can be expressed with only
+    `(==col)`.
 
 ## Examples
 
@@ -30,8 +31,18 @@ join side:left p=positions (employees.id==p.employee_id)
 ```prql
 from tracks
 join side:left artists (
+  # This adds a `country` condition, as an alternative to filtering
   artists.id==tracks.artist_id && artists.country=='UK'
-  # As an alternative to filtering
+)
+```
+
+[`this` & `that`](../../syntax/keywords.md#this--that) can be used to refer to
+the current & other table respectively:
+
+```prql
+from tracks
+join side:inner artists (
+  this.id==that.artist_id
 )
 ```
 

web/book/src/reference/syntax/keywords.md

@@ -23,7 +23,8 @@ aggregate (
 )
 ```
 
-Within a `join`, `that` refers to the other table:
+Within a [`join`](../stdlib/transforms/join.md), `that` refers to the other
+table:
 
 ```prql
 from invoices

web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__3.snap

@@ -0,0 +1,11 @@
+---
+source: web/book/tests/documentation/book.rs
+expression: "from tracks\njoin side:inner artists (\n  this.id==that.artist_id\n)\n"
+---
+SELECT
+  tracks.*,
+  artists.*
+FROM
+  tracks
+  JOIN artists ON tracks.id = artists.artist_id
+