Docs: Update Language Reference

src/blog/2023-10-03-malloy-four/index.malloynb

@@ -51,11 +51,11 @@ the [4.0 Messages FAQ](../../documentation/language/m4warnings.malloynb) documen
   * The `declare:` statement has been removed, use `dimension:` or `measure:`
   * `join_:` statements in a query must be in the `extend: {}` block
 * The new [run statement](../../documentation/language/statement.malloynb#run-statements), `run:` replaces `query:` with no name
-* The `sql:` statement is replaced by [SQL sources](../../documentation/language/sql_sources.malloynb), e.g. `duckdb.sql("SELECT ...")`
+* The `sql:` statement is replaced by [SQL blocks](../../documentation/language/sql_blocks.malloynb), e.g. `duckdb.sql("SELECT ...")`
 * [Table sources](../../documentation/language/source.malloynb#sources-from-tables-or-views) have new syntax: `connection_name.table('table_path')` instead of `table('connection_name:table_path')`
 * [Projections](../../documentation/language/views.malloynb#projection) are performed with `select:` instead of `project:` 
 * The `from()` function to create a source from a query is no longer needed
-* When [nesting Malloy code inside a SQL string](../../documentation/language/sql_sources.malloynb#embedding-malloy-queries-in-an-sql-block-a-k-a-turducken-), the syntax 
+* When [nesting Malloy code inside a SQL string](../../documentation/language/sql_blocks.malloynb#embedding-malloy-queries-in-an-sql-block--turducken-), the syntax 
   is `%{ <<malloy query>> }` and not `%{ <<malloy query>> }%` 
 * [Explicit aggregate locality](../../documentation/language/aggregates.malloynb#required-explicit-aggregate-locality) (using `source.`) is now required in some cases for `sum()` and `avg()` 
 * The filter shortcut `{? }` has been removed
@@ -79,6 +79,6 @@ these will continue to work. They are listed here to provide a complete record o
 * New [safe cast operator](../../documentation/language/expressions.malloynb#safe-type-cast) `:::`
 * Addition of [annotations and tags](../../documentation/language/tags.malloynb)
 * New [null-coalescing operator](../../documentation/language/expressions.malloynb#null-operations) `??`
-* [Selective imports](../../documentation/language/imports.malloynb#selective-imports) of objects from other files
+* [Selective imports](../../documentation/language/statement.malloynb#selective-imports) of objects from other files
 * [Analytic/window functions](../../documentation/language/calculations_windows.malloynb) using `calculate:`
 >>>markdown

src/documentation/experiments/experiments.malloynb

@@ -5,11 +5,9 @@ Before releasing language features, we like to get a feel for how they work when
 
 We value feedback during the experimental phase.  Please make sure you let us know what you think.
 
-Below is a list of currently running experiements and how to turn them on.
+Below is a list of currently running experiments and how to turn them on.
 
 * `##! experimental.join_types` - [Additional Join Type](joins.malloynb)
-* `## renderer_next` - [New table and visualization Rendering](renderer.malloynb)
-* `##! experimental { function_order_by partition_by aggregate_limit }` - [ordering and partitioning in calculations](window.malloynb)
 * `##! experimental.sql_functions` - [Write expression in SQL](sql_expressions.malloynb)
 * `##! experimental.parameters` - [Declare sources with parameters](parameters.malloynb)
 * `##! experimental.composite_sources` - [Create virtual sources backed by multiple cube tables or source definitions](composite_sources.malloynb)

src/documentation/experiments/sql_expressions.malloynb

@@ -1,14 +1,15 @@
 >>>markdown
 ## SQL Expressions
 
-Malloy allows you to call native database functions using `!type`. For example if you wanted to call the duckdb function bit_length that returns a number, in Malloy you couild write `bitlength!number("this string)`.
+To enable this feature, add `##! experimental{sql_functions}` at the top of your Malloy file.
 
-Sometimes the SQL expression you want to write can't be expressed this way.  For example in DUCKDB, the extract function looks like.
+Malloy allows you to call native database functions using `!type`. For example if you wanted to call the duckdb function bit_length that returns a number, in Malloy you could write `bitlength!number("this string")`.
 
-  `extract(part from date)`
+Sometimes the SQL expression you want to write can't be expressed this way. For example in DuckDB, the extract function looks like:
 
+  `extract(part from date)`
 
-In order to make Malloy write an expression like this you can escape to a `sql_<type>` function.  In the string parameter you can reference dimensions using the substitution operator `${dimension_name}`. 
+In order to make Malloy write an expression like this you can escape to a `sql_<type>` function. In the string parameter you can reference dimensions using the substitution operator `${dimension_name}`. 
 
 SQL functions are
 

src/documentation/language/aggregates.malloynb

@@ -1,7 +1,7 @@
 >>>markdown
 # Aggregates
 
-Malloy supports the standard aggregate functions `count`, `sum`, `avg`, `min`, and `max`. When these are used in a field's definition, they make that field a [measure](fields.malloynb#measures).
+Malloy supports the standard aggregate functions `count`, `sum`, `avg`, `min`, and `max`. When these are used in a field's definition, they make that field a measure.
 
 ## Basic Syntax
 

src/documentation/language/calculations_windows.malloynb

@@ -1,5 +1,5 @@
 >>>markdown
-# Calculations and Window Functions
+# Calculations
 
 Window functions in Malloy are expressed in _calculation_ fields, using the `calculate: ` keyword. Calculation fields operate on the results of a aggregation or selection, while still operating within the same query stage. Logically these calculation operations occur "after" the other operations, so their exact semantics can be challenging to understand. For a full list of the window functions that Malloy supports, visit our [function reference documentation](./functions.malloynb#window-functions).
 

src/documentation/language/changelog.malloynb

@@ -18,15 +18,15 @@ For more information about views, see the [Views](./views.malloynb) section.
 
 New syntax for defining sources based on tables, `duckdb.table('data/users.parquet')` has been introduced. The old syntax, `table('duckdb:data/users.parquet')` still works for the time being, but will be deprecated in 4.0.
 
-See the [Connections](./connections.malloynb#table-connection-method) section for more details.
+See the [Sources](./source.malloynb) section for more details.
 
 ### SQL Source Method
 
 New syntax for defining sources based on SQL queries, `duckdb.sql("""select * ... """)`, has been introduced. The old syntax, `sql: name is { select: """select * ..."""; connection: "duckdb" }` still works for the time being, but will be deprecated in 4.0.
 
 This makes `from_sql` no longer necessary, and it will be deprecated with the `sql:` statement.
 
-See the [SQL Sources](./sql_sources.malloynb) section for more details.
+See the [Sources](./source.malloynb#sources-from-sql-queries) section for more details.
 
 ### Source Extensions and Query Refinements