docs: Move from out of transforms (#4293) (#4294)

web/book/src/SUMMARY.md

@@ -1,21 +1,24 @@
 <!-- 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?) -->
 
-[Overview](./overview.md)
-
 # 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.
+
 - [Relations](./tutorial/relations.md)
 - [Filtering](./tutorial/filtering.md)
 - [Aggregation](./tutorial/aggregation.md)
 
-# How do I?
-
-- [Read files?](./how-do-i/read-files.md)
-- [Remove duplicates?](./how-do-i/distinct.md)
-- [Create ad-hoc relations?](./how-do-i/relation-literals.md)
+<!-- We used to have a "How do I", which I think would be good, but we didn't build enough to maintain it. If we find the Reference or Tutorial has enough content that we could move here, we could start it again  -->
+<!-- # How do I? -->
 
 # Reference
 
+In-depth information about the PRQL language. Includes justifications for
+language design decisions and formal specifications for parts of the language.
+
 - [Syntax](./reference/syntax/README.md)
 
   - [Literals](./reference/syntax/literals.md)
@@ -34,10 +37,16 @@
   - [Comments](./reference/syntax/comments.md)
   - [Parameters](./reference/syntax/parameters.md)
 
+- [Importing data](./reference/data/README.md)
+
+  - [From](./reference/data/from.md)
+  - [Reading files](./reference/data/read-files.md)
+  - [Ad-hoc data](./reference/data/relation-literals.md)
+
 - [Declarations]()
   <!-- I don't know what to call this section. -->
 
-  - [Variables](./reference/declarations/variables.md)
+  - [Variables — `let` & `into`](./reference/declarations/variables.md)
   - [Functions](./reference/declarations/functions.md)
 
 - [Standard library](./reference/stdlib/README.md)
@@ -48,7 +57,6 @@
     - [Append](./reference/stdlib/transforms/append.md)
     - [Derive](./reference/stdlib/transforms/derive.md)
     - [Filter](./reference/stdlib/transforms/filter.md)
-    - [From](./reference/stdlib/transforms/from.md)
     - [Group](./reference/stdlib/transforms/group.md)
     - [Join](./reference/stdlib/transforms/join.md)
     - [Loop](./reference/stdlib/transforms/loop.md)
@@ -61,6 +69,7 @@
   - [Date functions](./reference/stdlib/date.md)
   - [Mathematical functions](./reference/stdlib/math.md)
   - [Text functions](./reference/stdlib/text.md)
+  - [Removing duplicates](./reference/stdlib/distinct.md)
 
 - [Specification](./reference/spec/README.md)
 
@@ -71,6 +80,8 @@
 
 # Project
 
+General information about the project, tooling and development.
+
 - [Changelog](./project/changelog.md)
 
 - [Target & version](./project/target.md)

web/book/src/reference/data/README.md

@@ -0,0 +1 @@
+# Importing data

web/book/src/reference/stdlib/transforms/from.md → web/book/src/reference/data/from.md

@@ -14,7 +14,7 @@ select e.first_name
 ```
 
 Table names containing spaces or special characters
-[need to be contained within backticks](../../syntax/keywords.md#quoting):
+[need to be contained within backticks](../syntax/keywords.md#quoting):
 
 ```prql
 from `artist tracks`

web/book/src/how-do-i/read-files.md → web/book/src/reference/data/read-files.md

@@ -1,6 +1,6 @@
-# How do I: read files?
+# Reading files
 
-There are a couple of functions mainly designed for DuckDB:
+There are a couple of functions mainly designed for DuckDB to read from files:
 
 ```prql
 prql target:sql.duckdb
@@ -28,5 +28,5 @@ from `artists.parquet`
 
 ## See also
 
-- [Target and Version](../project/target.md)
-- [How do I: create ad-hoc relations?](./relation-literals.md)
+- [Target and Version](../../project/target.md)
+- [Ad-hoc data](./relation-literals.md)

web/book/src/reference/declarations/variables.md

@@ -1,4 +1,4 @@
-# Variables
+# Variables — `let` & `into`
 
 Variables assign a name — say `x` — to an expression, like in most programming
 languages. The name can then be used in any expression, acting as a substitute

web/book/src/how-do-i/distinct.md → web/book/src/reference/stdlib/distinct.md

@@ -4,7 +4,7 @@ PRQL doesn't have a specific `distinct` keyword. Instead duplicate tuples in a
 relation can be removed by using `group` and `take 1`:
 
 ```prql
-from employees
+from db.employees
 select department
 group employees.* (
   take 1
@@ -14,7 +14,7 @@ group employees.* (
 This also works with a wildcard:
 
 ```prql
-from employees
+from db.employees
 group employees.* (take 1)
 ```
 
@@ -26,7 +26,7 @@ To
 
 ```prql
 # youngest employee from each department
-from employees
+from db.employees
 group department (
   sort age
   take 1
@@ -37,7 +37,7 @@ Note that we can't always compile to `DISTINCT`; when the columns in the `group`
 aren't all the available columns, we need to use a window function:
 
 ```prql
-from employees
+from db.employees
 group {first_name, last_name} (take 1)
 ```
 
@@ -50,7 +50,7 @@ group {first_name, last_name} (take 1)
 ```prql
 prql target:sql.postgres
 
-from employees
+from db.employees
 group department (
   sort age
   take 1

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

@@ -23,7 +23,6 @@ These are the currently available transforms:
 
 | Transform   | Purpose                                                                         | SQL Equivalent              |
 | ----------- | ------------------------------------------------------------------------------- | --------------------------- |
-| `from`      | [Start from a table](./from.md)                                                 | `FROM`                      |
 | `derive`    | [Compute new columns](./derive.md)                                              | `SELECT *, ... AS ...`      |
 | `select`    | [Pick & compute columns](./select.md)                                           | `SELECT ... AS ...`         |
 | `filter`    | [Pick rows based on their values](./filter.md)                                  | `WHERE`, `HAVING`,`QUALIFY` |
@@ -34,3 +33,9 @@ These are the currently available transforms:
 | `aggregate` | [Summarize many rows into one row](./aggregate.md)                              | `SELECT foo(...)`           |
 | `window`    | [Apply a pipeline to overlapping segments of rows](./window.md)                 | `OVER`, `ROWS`, `RANGE`     |
 | `loop`      | [Iteratively apply a function to a relation until it's empty](./loop.md)        | `WITH RECURSIVE ...`        |
+
+## See also
+
+- [`from`](../../data/from.md) — `from` is the main way of getting data into a
+  pipeline (it's not listed above since it's not technically a transform, since
+  it doesn't receive an input).

web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__from__0.snap → web/book/tests/documentation/snapshots/documentation__book__reference__data__from__0.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "from artists\n"
+expression: "from db.artists\n"
 ---
 SELECT
   *

web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__from__1.snap → web/book/tests/documentation/snapshots/documentation__book__reference__data__from__1.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "from e = employees\nselect e.first_name\n"
+expression: "from e = db.employees\nselect e.first_name\n"
 ---
 SELECT
   first_name

web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__from__2.snap → web/book/tests/documentation/snapshots/documentation__book__reference__data__from__2.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "from `artist tracks`\n"
+expression: "from db.`artist tracks`\n"
 ---
 SELECT
   *

web/book/tests/documentation/snapshots/documentation__book__how-do-i__read-files__how-do-i-read-files__1.snap → web/book/tests/documentation/snapshots/documentation__book__reference__data__read-files__reading-files__1.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "from `artists.parquet`\n"
+expression: "from db.`artists.parquet`\n"
 ---
 SELECT
   *

web/book/tests/documentation/snapshots/documentation__book__how-do-i__relation-literals__array-literals__1.snap → web/book/tests/documentation/snapshots/documentation__book__reference__data__relation-literals__array-literals__1.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "let my_artists = [\n  {artist=\"Miles Davis\"},\n  {artist=\"Marvin Gaye\"},\n  {artist=\"James Brown\"},\n]\n\nfrom artists\njoin my_artists (==artist)\njoin albums (==artist_id)\nselect {artists.artist_id, albums.title}\n"
+expression: "let my_artists = [\n  {artist=\"Miles Davis\"},\n  {artist=\"Marvin Gaye\"},\n  {artist=\"James Brown\"},\n]\n\nfrom db.artists\njoin my_artists (==artist)\njoin db.albums (==artist_id)\nselect {artists.artist_id, albums.title}\n"
 ---
 WITH table_0 AS (
   SELECT

web/book/tests/documentation/snapshots/documentation__book__reference__declarations__variables__0.snap → web/book/tests/documentation/snapshots/documentation__book__reference__declarations__variables__variables--__0.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "let top_50 = (\n  from employees\n  sort salary\n  take 50\n  aggregate {total_salary = sum salary}\n)\n\nfrom top_50      # Starts a new pipeline\n"
+expression: "let top_50 = (\n  from db.employees\n  sort salary\n  take 50\n  aggregate {total_salary = sum salary}\n)\n\ntop_50      # Starts a new pipeline\n"
 ---
 WITH table_0 AS (
   SELECT

web/book/tests/documentation/snapshots/documentation__book__reference__declarations__variables__1.snap → web/book/tests/documentation/snapshots/documentation__book__reference__declarations__variables__variables--__1.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "from employees\ntake 50\ninto first_50\n\nfrom first_50\n"
+expression: "from db.employees\ntake 50\ninto first_50\n\nfirst_50\n"
 ---
 WITH first_50 AS (
   SELECT

web/book/tests/documentation/snapshots/documentation__book__reference__declarations__variables__2.snap → web/book/tests/documentation/snapshots/documentation__book__reference__declarations__variables__variables--__2.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "let grouping = s\"\"\"\n  SELECT SUM(a)\n  FROM tbl\n  GROUP BY\n    GROUPING SETS\n    ((b, c, d), (d), (b, d))\n\"\"\"\n\nfrom grouping\n"
+expression: "let grouping = s\"\"\"\n  SELECT SUM(a)\n  FROM tbl\n  GROUP BY\n    GROUPING SETS\n    ((b, c, d), (d), (b, d))\n\"\"\"\n\ngrouping\n"
 ---
 WITH table_0 AS (
   SELECT

web/book/tests/documentation/snapshots/documentation__book__how-do-i__distinct__how-do-i-remove-duplicates__0.snap → web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__distinct__how-do-i-remove-duplicates__0.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "from employees\nselect department\ngroup employees.* (\n  take 1\n)\n"
+expression: "from db.employees\nselect department\ngroup employees.* (\n  take 1\n)\n"
 ---
 SELECT
   DISTINCT department

web/book/tests/documentation/snapshots/documentation__book__how-do-i__distinct__how-do-i-remove-duplicates__1.snap → web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__distinct__how-do-i-remove-duplicates__1.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "from employees\ngroup employees.* (take 1)\n"
+expression: "from db.employees\ngroup employees.* (take 1)\n"
 ---
 SELECT
   DISTINCT *

web/book/tests/documentation/snapshots/documentation__book__how-do-i__distinct__remove-duplicates-from-each-group__0.snap → web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__distinct__remove-duplicates-from-each-group__0.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "# youngest employee from each department\nfrom employees\ngroup department (\n  sort age\n  take 1\n)\n"
+expression: "# youngest employee from each department\nfrom db.employees\ngroup department (\n  sort age\n  take 1\n)\n"
 ---
 WITH table_0 AS (
   SELECT

web/book/tests/documentation/snapshots/documentation__book__how-do-i__distinct__remove-duplicates-from-each-group__1.snap → web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__distinct__remove-duplicates-from-each-group__1.snap

@@ -1,6 +1,6 @@
 ---
 source: web/book/tests/documentation/book.rs
-expression: "from employees\ngroup {first_name, last_name} (take 1)\n"
+expression: "from db.employees\ngroup {first_name, last_name} (take 1)\n"
 ---
 WITH table_0 AS (
   SELECT