Edits to super-sql/declarations docs (#6455)

Author: philrz

book/src/super-sql/declarations/constants.md

@@ -7,7 +7,7 @@ const <id> = <expr>
 where `<id>` is an [identifier](../queries.md#identifiers)
 and `<expr>` is a constant [expression](../expressions/intro.md)
 that must evaluate at compile time without referencing any
-runtime state such as `this` or a field of `this`.
+runtime state such as [this](../intro.md#pipe-scoping) or a field of `this`.
 
 Constant declarations must appear in the declaration section of a
 [scope](../queries.md#scope).

book/src/super-sql/declarations/functions.md

@@ -5,7 +5,7 @@ New functions are declared with the syntax
 fn <id> ( [<param> [, <param> ...]] ) : <expr>
 ```
 where
-* `<id>` is an identifier representing the name of the function,
+* `<id>` is an [identifier](../queries.md#identifiers) representing the name of the function,
 * each `<param>` is an identifier representing a positional argument to the function, and
 * `<expr>` is any [expression](../expressions/intro.md) that implements the function.
 
@@ -14,9 +14,9 @@ Function declarations must appear in the declaration section of a [scope](../que
 The function body `<expr>` may refer to the passed-in arguments by name.
 
 Specifically, the references to the named parameters are
-field references of the special value `this`, as in any expression.
+field references of the [special value](../intro.md#pipe-scoping) `this`, as in any expression.
 In particular, the value of `this` referenced in a function body
-is formed as record from the actual values passed to the function
+is formed as a [record](../types/record.md) from the actual values passed to the function
 where the field names correspond to the parameters of the function.
 
 For example, the function `add` as defined by
@@ -25,21 +25,21 @@ fn add(a,b): a+b
 ```
 when invoked as
 ```
-values {x:1} | values add(x,1)
+values {x:1} | values add(x,2)
 ```
 is passed the record the `{a:x,b:1}`, which after resolving `x` to `1`,
-is `{a:1,b:1}` and thus evaluates the expression
+is `{a:1,b:2}` and thus evaluates the expression
 ```
 this.a + this.b
 ```
-which results in `2`.
+which results in `3`.
 
-Any function-as-value arguments passed to a function do not appear in the `this`
+Any [function references](../expressions/functions.md#function-references) passed to a function do not appear in the `this`
 record formed from the parameters.  Instead, function values are expanded at their
-call sites in a macro-like fashion.
+call sites in a [macro](https://en.wikipedia.org/wiki/Macro_(computer_science))-like fashion.
 
 Functions may be recursive.  If the maximum call stack depth is exceeded,
-the function returns an error value indicating so.  Recursive functions that
+the function returns an [error](../types/error.md) value indicating so.  Recursive functions that
 run for an extended period of time without exceeding the stack depth will simply
 be allowed to run indefinitely and stall the query result.
 
@@ -56,7 +56,7 @@ fn <id> ( [<param> [, <param> ...]] ) : (
 where `<query>` is any [query](../queries.md) and is simply wrapped in parentheses
 to form the subquery.
 
-As with any subquery, when multiple results are expected, an array subquery
+As with any subquery, when multiple results are expected, an [array subquery](../expressions/subqueries.md#array-subqueries)
 may be used by wrapping `<query>` in square brackets instead of parentheses:
 ```
 fn <id> ( [<param> [, <param> ...]] ) : [
@@ -67,24 +67,35 @@ fn <id> ( [<param> [, <param> ...]] ) : [
 Note when using a subquery expression in this fashion,
 the function's parameters do not appear in the scope of the expressions
 embedded in the query.  For example, this function results in a type error:
-```
+```mdtest-spq fails {data-layout='no-labels'} {style='margin:auto;width:85%'}
+# spq
 fn apply(a,val): (
   unnest a
-  | collect(this+val))
+  | collect(this+val)
 )
 values apply([1,2,3], 1)
+# input
+
+# expected output
+"val" no such field at line 3, column 18:
+  | collect(this+val)
+                 ~~~
 ```
 because the field reference to `val` within the subquery does not exist.
-Instead the parameter `val` can be carried into the subquery using the
-alternative form of [unnest](../operators/unnest.md):
-```
+Instead the parameter `val` can be carried into the subquery using
+the compound form of [unnest](../operators/unnest.md):
+```mdtest-spq {data-layout='no-labels'} {style='margin:auto;width:85%'}
+# spq
 fn apply(a,val): (
   unnest {outer:val,item:a}
   | collect(outer+item)
 )
 values apply([1,2,3], 1)
+# input
+
+# expected output
+[2,3,4]
 ```
-See the example below.
 
 ### Examples
 
@@ -139,7 +150,7 @@ values stats(a)
 {avg:4.,min:4,max:4,mode:4}
 ```
 ---
-_Function arguments are actually fields in the "this" record_
+_Function arguments are actually fields in the `this` record_
 
 ```mdtest-spq
 # spq
@@ -151,7 +162,7 @@ values that(x,y,3)
 {a:1,b:2,c:3}
 ```
 ---
-_Functions passed as values do not appear in the "this" record_
+_Functions passed as values do not appear in the `this` record_
 
 ```mdtest-spq
 # spq

book/src/super-sql/declarations/intro.md

@@ -12,7 +12,7 @@ Declarations may be created for
 * [operators](operators.md), or
 * [pragmas](pragmas.md).
 
-All of the names defined in a given scope are available to other declarations defined
+With the exception of types that reference other types, all of the names defined in a given scope are available to other declarations defined
 in the same scope (as well as containing scopes) independent of the order of declaration,
 i.e., a declaration may forward-reference another declaration that is defined in the
 same scope.

book/src/super-sql/declarations/operators.md

@@ -9,7 +9,7 @@ op <name> [<param> [, <param> ...]] : (
 where
 * `<name>` is an [identifier](../queries.md#identifiers)
   representing the name of the new operator,
-* each `<param>` is an [identifier](../queries.md#identifiers)
+* each `<param>` is an identifier
   representing a positional parameter to the operator, and
 * `<query>` is any [query](../queries.md).
 
@@ -20,7 +20,7 @@ Operator declarations must appear in the declaration section of a [scope](../que
 A declared operator is invoked by its name
 using the [call](../operators/intro.md#call) keyword.
 Operators can be invoked without the `call` keyword as a shortcut when such use
-is unambiguous with the built-in operators.
+is unambiguous with the [built-in operators](../operators/intro.md).
 
 A called instance of a declared operator consumes input, operates on that input,
 and produces output.  The body of the
@@ -43,7 +43,7 @@ In contrast to function calls, where the arguments are evaluated at the call sit
 and values are passed to the function, operator arguments are instead passed to the
 operator body as an expression _template_ and the expression is evaluated in the
 context of the operator body.  That said, any other declared identifiers referenced
-by these expressions (e.g., constants, functions, named queries, etc.) are bound to
+by these expressions (e.g., [constants](constants.md), [functions](functions.md), [named queries](queries.md), etc.) are bound to
 those entities using the lexical scope where they are defined rather than the
 scope of their expanded use in the operator's definition.
 
@@ -58,14 +58,14 @@ the operator expressions here are not generators and do not implement backtracki
 
 ---
 
-_Trivial operator that echoes its input_
+_Trivial operator that echoes its input, invoked with explicit `call`_
 
 ```mdtest-spq
 # spq
 op echo: (
   values this
 )
-echo
+call echo
 # input
 {x:1}
 # expected output
@@ -74,7 +74,7 @@ echo
 
 ---
 
-_Simple example that adds a new field to inputs records_
+_Simple example that adds a new field to input records_
 
 ```mdtest-spq
 # spq

book/src/super-sql/declarations/pragmas.md

@@ -8,7 +8,7 @@ pragma <id> = <expr>
 where `<id>` is an [identifier](../queries.md#identifiers)
 and `<expr>` is a constant [expression](../expressions/intro.md)
 that must evaluate at compile time without referencing any
-runtime state such as `this` or a field of `this`.
+runtime state such as [this](../intro.md#pipe-scoping) or a field of `this`.
 
 Pragmas must appear in the declaration section of a [scope](../queries.md#scope).
 

book/src/super-sql/declarations/queries.md

@@ -7,7 +7,7 @@ let <name> = ( <query> )
 where `<name>` is an [identifier](../queries.md#identifiers)
 and `<query>` is any standalone [query](../queries.md) that sources its own input.
 
-Named queries are similar to [common-table expressions (CTE)](../sql/with.md)
+Named queries are similar to SQL [common-table expressions (CTE)](../sql/with.md)
 and may be likewise invoked in a [from](../operators/from.md) operator by referencing
 the query's name, as in
 ```
@@ -25,12 +25,11 @@ As with any expression subquery, multiple values result in an error, so when
 this is expected, the query reference may be enclosed in brackets to form
 an array subquery.
 
-To create a query that can be used as an operator and thus can operate on its input,
-declare an [operator](operators.md).
+To create a query that can operate on its input, declare an [operator](operators.md).
 
 A common use case for a named query is to compute a complex query that returns a scalar,
-then embedding that scalar result in an expression.  Even though the named query
-appears syntactically as a sub-query in this case, the result is efficient
+then embedding that scalar result in an [expression](../expressions/intro.md).  Even though the named query
+appears syntactically as a subquery in this case, the result is efficient
 because the compiler will materialize the result and reuse it on each invocation.
 
 ### Examples

book/src/super-sql/declarations/types.md

@@ -4,25 +4,25 @@ Named types are declared with the syntax
 ```
 type <id> = <type>
 ```
-where `<id>` is an identifier and `<type>` is a [type](../types/intro.md).
+where `<id>` is an [identifier](../queries.md#identifiers) and `<type>` is a [type](../types/intro.md).
 This creates a new type with the given name in the type system.
 
 Type declarations must appear in the declaration section of a [scope](../queries.md#scope).
 
 Any named type that appears in the body of a type declaration must be previously
-declared in the same scope or in an ancestor scope, i.e., types cannot contained
+declared in the same scope or in an ancestor scope, i.e., types cannot contain
 forward references to other named types.  In particular, named types cannot be recursive.
 
 >[!NOTE]
 > A future version of SuperSQL may include recursive types.  This is a research topic
 > for the SuperDB project.
 
-Input data may create named types that conflict with type declarations.  In this case,
+Input data may create [named types](../../formats/model.md#3-named-type) that conflict with type declarations.  In this case,
 a reference to a declared type in the query text uses the type definition of the nearest
 containing scope that binds the type name independent of types in the input.
 
-When a named type is referenced as a string argument to cast, then any type definition
-with that name is ignored and the named type is bound to the type of the argument of cast.
+When a named type is referenced as a string argument to [cast](../functions/types/cast.md), then any type definition
+with that name is ignored and the named type is bound to the type of the first argument of `cast`.
 This does not affect the binding of the type used in other expressions in the query text.
 
 Types can also be bound to identifiers without creating a named type using a
@@ -78,7 +78,7 @@ true
 
 ---
 
-_A type name argument to cast in the form of a string is independent type declarations_
+_A type name argument to `cast` in the form of a string is independent of type declarations_
 
 ```mdtest-spq
 # spq

book/src/super-sql/operators/unnest.md

@@ -47,7 +47,7 @@ If `<expr>` is a record, it must have two fields of the form:
 {<first>: <any>, <second>:<array>}
 ```
 where `<first>` and `<second>` are arbitrary field names, `<any>` is any
-SuperSQL value, and `<array>` is an array value.  In this case, the derived
+SuperSQL value, and `<array>` is an array value.  In this compound form of `unnest`, the derived
 sequence has the form:
 ```
 {<first>: <any>, <second>:<elem0>}