chore: Backport #4495 to web (#4496)

Co-authored-by: Maximilian Roos <[email protected]>

README.md

@@ -35,7 +35,7 @@ aggregate {                                   # `aggregate` reduces each column
 }
 ```
 
-Here's a fuller example of the language;
+Here's a fuller example of the language:
 
 ```elm
 from employees

web/book/src/README.md

@@ -0,0 +1,60 @@
+# PRQL language book
+
+**P**ipelined **R**elational **Q**uery **L**anguage, pronounced "Prequel".
+
+PRQL is a modern language for transforming data — a simple, powerful, pipelined
+SQL replacement. Like SQL, it's readable, explicit and declarative. Unlike SQL,
+it forms a logical pipeline of transformations, and supports abstractions such
+as variables and functions. It can be used with any database that uses SQL,
+since it compiles to SQL.
+
+This book serves as a tutorial and reference guide on the language and the
+broader project. It currently has three sections, navigated by links on the
+left:
+
+- **Tutorial** — A friendly & accessible guide for learning PRQL. It has a
+  gradual increase of difficulty and requires only basic understanding of
+  programming languages. Knowledge of SQL is beneficial, because of many
+  comparisons to SQL, but not required.
+- **Reference** — In-depth information about the PRQL language. Includes
+  justifications for language design decisions and formal specifications for
+  parts of the language.
+- **Project** — General information about the project, tooling and development.
+
+---
+
+To lead with a couple of examples, with a comparison to SQL: the language can be
+as simple as:
+
+```prql
+from tracks
+filter artist == "Bob Marley"                 # Each line transforms the previous result
+aggregate {                                   # `aggregate` reduces each column to a value
+  plays    = sum plays,
+  longest  = max length,
+  shortest = min length,                      # Trailing commas are allowed
+}
+```
+
+...and here's a fuller example:
+
+```prql
+from employees
+filter start_date > @2021-01-01               # Clear date syntax
+derive {                                      # `derive` adds columns / variables
+  gross_salary = salary + (tax ?? 0),         # Terse coalesce
+  gross_cost = gross_salary + benefits_cost,  # Variables can use other variables
+}
+filter gross_cost > 0
+group {title, country} (                      # `group` runs a pipeline over each group
+  aggregate {                                 # `aggregate` reduces each group to a value
+    average gross_salary,
+    sum_gross_cost = sum gross_cost,          # `=` sets a column name
+  }
+)
+filter sum_gross_cost > 100_000               # `filter` replaces both of SQL's `WHERE` & `HAVING`
+derive id = f"{title}_{country}"              # F-strings like Python
+derive country_code = s"LEFT(country, 2)"     # S-strings allow using SQL as an escape hatch
+sort {sum_gross_cost, -country}               # `-country` means descending order
+take 1..20                                    # Range expressions (also valid here as `take 20`)
+```

web/book/src/SUMMARY.md

@@ -1,5 +1,9 @@
 <!-- markdownlint-disable MD042 — some pages aren't finished yet (though the graying out of top level pages is not ideal — it's either that, or links to pages that are blank. Or maybe we try and write a useful page for each heading?) -->
 
+# Introduction
+
+[Introduction](./README.md)
+
 # Tutorial
 
 A friendly & accessible guide for learning PRQL. It has a gradual increase of

web/book/tests/documentation/snapshots/documentation__book__README__prql-language-book__0.snap

@@ -0,0 +1,12 @@
+---
+source: web/book/tests/documentation/book.rs
+expression: "from tracks\nfilter artist == \"Bob Marley\"                 # Each line transforms the previous result\naggregate {                                   # `aggregate` reduces each column to a value\n  plays    = sum plays,\n  longest  = max length,\n  shortest = min length,                      # Trailing commas are allowed\n}\n"
+---
+SELECT
+  COALESCE(SUM(plays), 0) AS plays,
+  MAX(length) AS longest,
+  MIN(length) AS shortest
+FROM
+  tracks
+WHERE
+  artist = 'Bob Marley'

web/book/tests/documentation/snapshots/documentation__book__README__prql-language-book__1.snap

@@ -0,0 +1,45 @@
+---
+source: web/book/tests/documentation/book.rs
+expression: "from employees\nfilter start_date > @2021-01-01               # Clear date syntax\nderive {                                      # `derive` adds columns / variables\n  gross_salary = salary + (tax ?? 0),         # Terse coalesce\n  gross_cost = gross_salary + benefits_cost,  # Variables can use other variables\n}\nfilter gross_cost > 0\ngroup {title, country} (                      # `group` runs a pipeline over each group\n  aggregate {                                 # `aggregate` reduces each group to a value\n    average gross_salary,\n    sum_gross_cost = sum gross_cost,          # `=` sets a column name\n  }\n)\nfilter sum_gross_cost > 100_000               # `filter` replaces both of SQL's `WHERE` & `HAVING`\nderive id = f\"{title}_{country}\"              # F-strings like Python\nderive country_code = s\"LEFT(country, 2)\"     # S-strings allow using SQL as an escape hatch\nsort {sum_gross_cost, -country}               # `-country` means descending order\ntake 1..20                                    # Range expressions (also valid here as `take 20`)\n"
+---
+WITH table_1 AS (
+  SELECT
+    title,
+    country,
+    salary + COALESCE(tax, 0) + benefits_cost AS _expr_1,
+    salary + COALESCE(tax, 0) AS _expr_2
+  FROM
+    employees
+  WHERE
+    start_date > DATE '2021-01-01'
+),
+table_0 AS (
+  SELECT
+    title,
+    country,
+    AVG(_expr_2) AS _expr_0,
+    COALESCE(SUM(_expr_1), 0) AS sum_gross_cost
+  FROM
+    table_1
+  WHERE
+    _expr_1 > 0
+  GROUP BY
+    title,
+    country
+)
+SELECT
+  title,
+  country,
+  _expr_0,
+  sum_gross_cost,
+  CONCAT(title, '_', country) AS id,
+  LEFT(country, 2) AS country_code
+FROM
+  table_0
+WHERE
+  sum_gross_cost > 100000
+ORDER BY
+  sum_gross_cost,
+  country DESC
+LIMIT
+  20