Improve docs for shape and a la carte shaping functions (#5172)

docs/language/functions/cast.md

@@ -28,7 +28,7 @@ For complex types, the cast function visits each leaf value in `val` and
 casts that value to the corresponding type in `t`.
 When a complex value has multiple levels of nesting,
 casting is applied recursively down the tree.  For example, cast is recursively
-applied to each element in array of records and recursively applied to each record.
+applied to each element in an array of records and recursively applied to each record.
 
 If `val` is a record (or if any of its nested value is a record):
 * absent fields are ignored and omitted from the result,
@@ -41,6 +41,12 @@ to match the output type's order but rather just modifies the leaf values.
 If a cast fails, an error is returned when casting to primitive types
 and the input value is returned when casting to complex types.
 
+:::tip
+Many users seeking to `cast` record values prefer to use the
+[`shape` function](./shape.md) which applies the `cast`, [`fill`](./fill.md),
+and [`order`](./order.md) functions simultaneously.
+:::
+
 ### Examples
 
 _Cast primitives to type `ip`_

docs/language/functions/fill.md

@@ -11,13 +11,21 @@ fill(val: any, t: type) -> any
 ### Description
 
 The _fill_ function adds to the input record `val` any fields that are
-present in the output type `t` but not in the input.
+present in the output type `t` but not in the input.  Such fields are added
+after the fields already present in `t` and in the order they appear in the
+input record.
 
 Filled fields are added with a `null` value.  Filling is useful when
 you want to be sure that all fields in a schema are present in a record.
 
 If `val` is not a record, it is returned unmodified.
 
+:::tip
+Many users seeking the functionality of `fill` prefer to use the
+[`shape` function](./shape.md) which applies the `fill`, [`cast`](./cast.md),
+and [`order`](./order.md) functions simultaneously on a record.
+:::
+
 ### Examples
 
 _Fill a record_

docs/language/functions/order.md

@@ -26,6 +26,11 @@ the empty record type, i.e.,
 ```
 order(val, <{}>)
 ```
+:::tip
+Many users seeking the functionality of `order` prefer to use the
+[`shape` function](./shape.md) which applies the `order`, [`cast`](./cast.md),
+and [`fill`](./fill.md) functions simultaneously on a record.
+:::
 
 :::tip Note
 [Record expressions](../expressions.md#record-expressions) can also be used to

docs/language/functions/shape.md

@@ -11,12 +11,12 @@ shape(val: any, t: type) -> any
 ### Description
 
 The _shape_ function applies the
-[cast](cast.md),
-[fill](fill.md), and
-[order](order.md) functions to its input to provide an
-overall data shaping operation.
+[`cast`](cast.md),
+[`fill`](fill.md), and
+[`order`](order.md) functions to its input to provide an
+overall [data shaping](../shaping.md) operation.
 
-Note that _shape_ does not perform a _crop_ function so
+Note that `shape` does not perform a [`crop` function](./crop.md) so
 extra fields in the input are propagated to the output.
 
 ### Examples