(Non)Position aesthetics name formatting (#241)

* review docs

* 'Non-position(al)' to 'Material'

* Rename 'positional' -> 'position'

* fix few vague descriptors of material aesthetics

* Lingering positional -> position

Author: teunbrand

CLAUDE.md

@@ -1396,7 +1396,7 @@ PROJECT [<aesthetic>, ...] TO <coord_type>
 
 **Components**:
 
-- **Aesthetics** (optional): Comma-separated list of positional aesthetic names. If omitted, uses coord defaults.
+- **Aesthetics** (optional): Comma-separated list of position aesthetic names. If omitted, uses coord defaults.
 - **TO**: Required keyword separating aesthetics from coord type.
 - **coord_type**: Either `cartesian` or `polar`.
 - **SETTING** (optional): Additional properties.
@@ -1437,7 +1437,7 @@ Note: For axis limits, use `SCALE x FROM [min, max]` or `SCALE y FROM [min, max]
 
 1. **Axis limits**: Use `SCALE x/y FROM [min, max]` to set axis limits
 2. **Aesthetic domains**: Use `SCALE <aesthetic> FROM [...]` to set aesthetic domains
-3. **Custom aesthetics**: User can define custom positional names (e.g., `PROJECT a, b TO cartesian`)
+3. **Custom aesthetics**: User can define custom position names (e.g., `PROJECT a, b TO cartesian`)
 4. **Multi-layer support**: All projection transforms apply to all layers
 
 **Status**:

doc/get_started/the_rest.qmd

@@ -11,7 +11,7 @@ Thankfully, we will give you a bit more help than the illustration above in unde
 ## Coordinate systems
 In the earlier section we talked about position aesthetics being special because they are being orchestrated by the coordinate system. The coordinate system is the entity that takes care of the spatial arrangement of graphic objects based on their position aesthetic mapping. When thinking about a coordinate system we tend to think about a Cartesian coordinate system which has a horizontal x-axis and a vertical y-axis. There are others though, like polar systems, cartographic maps, and ternary systems. 
 
-At the most basics a coordinate system is a projection function that takes the position aesthetic and projects them into a 2 dimensional plane on the screen or paper. While we commonly have 2 position aesthetics that gets projected to a 2 dimensional plane, this is not a necessity. 3 positional aesthetics could be projected to 2 dimensions using a perspective transform or by using a special coordinate system such as a ternary layout.
+At the most basics a coordinate system is a projection function that takes the position aesthetic and projects them into a 2 dimensional plane on the screen or paper. While we commonly have 2 position aesthetics that gets projected to a 2 dimensional plane, this is not a necessity. 3 position aesthetics could be projected to 2 dimensions using a perspective transform or by using a special coordinate system such as a ternary layout.
 
 ## Faceting
 Faceting is the process of dividing your data by one or more variables and visualizing each group as a small version next to the other group. This technique is also known as creating small multiples. Often, each single plot will share the same position scales so that it is very easy to compare the small representations against each other.

doc/syntax/clause/facet.qmd

@@ -2,7 +2,9 @@
 title: "Create small multiples with `FACET`"
 ---
 
-The `FACET` clause allows you to split your data, by one or two variables, and plot each group as a small version of the plot: a technique called 'small multiples'. The technique is great for preventing overplotting. Because each small plot shares the same positional scales by default, visual comparisons between groups become easy.
+The `FACET` clause allows you to split your data, by one or two variables, and plot each group as a small version of the plot: a technique called 'small multiples'. 
+The technique is great for preventing overplotting. 
+Because each small plot shares the same position scales by default, visual comparisons between groups become easy.
 
 ## Clause syntax
 The `FACET` syntax contains a number of subclauses that are all optional
@@ -28,7 +30,7 @@ SETTING <parameter> => <value>, ...
 
 This clause behaves much like the `SETTINGS` clause in `DRAW`, in that it allows you to fine-tune specific behavior of the faceting. The following parameters exist:
 
-* `free`: Controls whether the positional scales are independent across the small multiples. Permissible values are:
+* `free`: Controls whether the position scales are independent across the small multiples. Permissible values are:
   * `null` or omitted (default): Shared/fixed scales across all panels
   * `'x'`: Independent x-axis scale, shared y-axis scale
   * `'y'`: Shared x-axis scale, independent y-axis scale

doc/syntax/clause/project.qmd

@@ -2,7 +2,7 @@
 title: "Control the coordinate system with `PROJECT`"
 ---
 
-The `PROJECT` clause defines the projection of the plot, that is, how abstract positional aesthetics are translated (projected) onto the plane defined by the screen/paper where the plot is viewed on.
+The `PROJECT` clause defines the projection of the plot, that is, how abstract position aesthetics are translated (projected) onto the plane defined by the screen/paper where the plot is viewed on.
 
 ## Clause syntax
 The `PROJECT` syntax contains a number of subclauses
@@ -12,14 +12,19 @@ PROJECT <aesthetic>, ... TO <coordinate-system>
   SETTING <parameter> => <value>, ...
 ```
 
-The comma-separated list of `aesthetic` names are optional but allows you to define the names of the positional aesthetics in the plot. If omitted, the default aesthetic names of the coordinate system is used. The order given matters as the first name is used for the primary aesthetic, the second name for the secondary aesthetic and so on. For instance, using `PROJECT y, x TO cartesian` will flip the plot as anything mapped to `y` will now relate to the horizontal axis, and anything mapped to `x` will relate to the vertical axis. Note that it is not allowed to use the name of already established aesthetics as positional aesthetics, e.g. `PROJECT fill, stroke TO polar` is not allowed.
+The comma-separated list of `aesthetic` names are optional but allows you to define the names of the position aesthetics in the plot. 
+If omitted, the default aesthetic names of the coordinate system is used. 
+The order given matters as the first name is used for the primary aesthetic, the second name for the secondary aesthetic and so on. 
+For instance, using `PROJECT y, x TO cartesian` will flip the plot as anything mapped to `y` will now relate to the horizontal axis, and anything mapped to `x` will relate to the vertical axis. 
+Note that it is not allowed to use the name of already established aesthetics as position aesthetics, e.g. `PROJECT fill, stroke TO polar` is not allowed.
 
 ### `TO`
 ```ggsql
 TO <coordinate-system>
 ```
 
-The `TO` clause is required and is followed by the name of the [coordinate system](../index.qmd#coordinate-systems). The coordinate system provides default names for the positional aesthetics and is responsible for how to translate values mapped to these onto the plane defined by the screen or paper.
+The `TO` clause is required and is followed by the name of the [coordinate system](../index.qmd#coordinate-systems). 
+The coordinate system provides default names for the position aesthetics and is responsible for how to translate values mapped to these onto the plane defined by the screen or paper.
 
 ### `SETTING`
 ```ggsql

doc/syntax/clause/scale.qmd

@@ -23,7 +23,9 @@ The `type` defines the class of scale to use. It can be one of four different ty
 
 Read more about each type at their dedicated documentation. You do not have to specify the type as it is deduced from the transform, input range, or data if left blank.
 
-You *must* specify an aesthetic so that the scale knows which mapping it belongs to. For positional aesthetics you will provide the base name (`x` or `y`) even though you are mapping to e.g. `xmin`. Creating a scale for `colour` (or `color`) will create a scale for both fill and stroke colour based on the settings. 
+You *must* specify an aesthetic so that the scale knows which mapping it belongs to. 
+For position aesthetics you will provide the base name (`x` or `y`) even though you are mapping to e.g. `xmin`. 
+Creating a scale for `colour` (or `color`) will create a scale for both fill and stroke colour based on the settings. 
 
 ### `FROM`
 ```ggsql

doc/syntax/coord/cartesian.qmd

@@ -2,10 +2,11 @@
 title: Cartesian
 ---
 
-The Cartesian coordinate system is the most well-known and the default for ggsql. It maps the primary positional aesthetic along a horizontal axis and the secondary along a perpendicular vertical axis.
+The Cartesian coordinate system is the most well-known and the default for ggsql. 
+It maps the primary position aesthetic along a horizontal axis and the secondary along a perpendicular vertical axis.
 
 ## Default aesthetics
-The Cartesian coordinate system has the following default positional aesthetics which will be used if no others have been provided:
+The Cartesian coordinate system has the following default position aesthetics which will be used if no others have been provided:
 
 * **Primary**: `x` (horizontal position)
 * **Secondary**: `y` (vertical position)
@@ -16,15 +17,15 @@ Users can provide their own aesthetic names if needed, e.g.
 PROJECT p, q TO cartesian
 ```
 
-assuming they do not try to use a name that is already being used by any facet or non-positional aesthetics (e.g. `PROJECT fill, panel TO cartesian` is not allowed).
+assuming they do not try to use a name that is already being used by any facet or material aesthetics (e.g. `PROJECT fill, panel TO cartesian` is not allowed).
 
 ## Settings
 * `clip`: Should data be removed if it appears outside the bounds of the coordinate system. Defaults to `true`
 * `ratio`: The aspect ratio between the steps on the vertical and horizontal axis (must be > 0 if specified). Defaults to `null` (no enforced aspect ratio)
 
 ## Examples
 
-### Use custom positional aesthetic names
+### Use custom position aesthetic names
 
 ```{ggsql}
 VISUALISE bill_len AS p, bill_dep AS q FROM ggsql:penguins

doc/syntax/coord/polar.qmd

@@ -5,7 +5,7 @@ title: Polar
 The polar coordinate system interprets its primary aesthetic as the angular position relative to the center, and the secondary aesthetic as the distance from the center. It is most often used for pie-charts and radar plots.
 
 ## Default aesthetics
-The polar coordinate system has the following default positional aesthetics which will be used if no others have been provided:
+The polar coordinate system has the following default position aesthetics which will be used if no others have been provided:
 
 * **Primary**: `radius` (distance from center)
 * **Secondary**: `angle` (angular position)

doc/syntax/index.qmd

@@ -61,7 +61,8 @@ A scale is responsible for translating a data value to an aesthetic literal, e.g
 - [`identity`](scale/type/identity.qmd) scales passes the data through unchanged
 
 ## Coordinate systems
-The coordinate system defines how the abstract positional aesthetics are projected onto the screen or paper where the final plot appears. As such, it has great influence over the final look of the plot.
+The coordinate system defines how the abstract position aesthetics are projected onto the screen or paper where the final plot appears. 
+As such, it has great influence over the final look of the plot.
 
 - [`cartesian`](coord/cartesian.qmd) is the classic coordinate system consisting of two perpendicular axes, one being horizontal and one being vertical
 - [`polar`](coord/polar.qmd) interprets the primary position as the angular location relative to the center and the secondary position as the distance (radius) from the center, and this creates a circular coordinate system

doc/syntax/scale/aesthetic/0_position.qmd

@@ -2,22 +2,31 @@
 title: "Position"
 ---
 
-Position aesthetics relate data to placement in the coordinate system of the plot. All layers need at least one of each positional aesthetic mapped in order to show its data. However, the layer may compute positional aesthetics from the mapping. For example, a bar plot calculates the `y` aesthetic by counting the number of records in each group defined by the mapped `x` aesthetic.
+Position aesthetics relate data to placement in the coordinate system of the plot. 
+All layers need at least one of each position aesthetic mapped in order to show its data. 
+However, the layer may compute position aesthetics from the mapping. 
+For example, a bar plot calculates the `y` aesthetic by counting the number of records in each group defined by the mapped `x` aesthetic.
 
-In the above we use `x`and `y` as examples of position aesthetics but in reality the position aesthetic names are defined by the coordinate system in use. A Cartesian coordinate system recognizes `x` and `y` whereas a polar coordinate system recognizes `radius` and `angle`. You can implicitly choose the coordinate system by mapping to the aesthetics that it uses, i.e. if you map to `radius` and `angle` then a polar coordinate system will be chosen for you.
+In the above we use `x`and `y` as examples of position aesthetics, but in reality the position aesthetic names are defined by the coordinate system in use. 
+A Cartesian coordinate system recognizes `x` and `y` whereas a polar coordinate system recognizes `radius` and `angle`. 
+You can implicitly choose the coordinate system by mapping to the aesthetics that it uses, i.e. if you map to `radius` and `angle` then a polar coordinate system will be chosen for you.
 
 ## Literal values
-Scales for position aesthetics never use an output range and always relate to the input range. This is a practical decision by ggsql because different writers may treat the positional aesthetic in different ways. ^[In reality one could easily think of positional literal values as either normalized position along the x or y axis, or absolute units of distance from the bottom left corner of the coordinate system.]
+Scales for position aesthetics never use an output range and always relate to the input range. 
+This is a practical decision by ggsql because different writers may treat the position aesthetic in different ways. ^[In reality one could easily think of position literal values as either normalized position along the x or y axis, or absolute units of distance from the bottom left corner of the coordinate system.]
 
 ::: {.callout-note}
 The lack of true literal values in position means that it is currently hard to place data and annotation "in-between" breaks in a discrete position scale.
 :::
 
 ## Aesthetic families
-Positional aesthetics have variants defined by a suffix attached to the primary name (e.g. `x`). The recognized suffixes are:
+Position aesthetics have variants defined by a suffix attached to the primary name (e.g. `x`). 
+The recognized suffixes are:
 
 * `end`
 * `min`
 * `max`
 
-Which version of an aesthetic to use depends on the layer, but all aesthetics within a family is scaled by the same scale, which is named after its primary aesthetic. This means that even when rendering a layer that only uses `xmin` and `xmax`, you will still scale it by writing `SCALE x ...` and label it by writing `LABEL x => ...`
+Which version of an aesthetic to use depends on the layer. 
+All aesthetics within a family use the same scale, which is named after its primary aesthetic. 
+This means that even when rendering a layer that only uses `xmin` and `xmax`, you will still scale it by writing `SCALE x ...` and label it by writing `LABEL x => ...`

doc/syntax/scale/aesthetic/Z_faceting.qmd

@@ -23,7 +23,8 @@ SCALE x
   SETTING breaks => 'weeks'
 ```
 
-In order to show data where the facet variable is null, it is necessary to explicitly include `null` in the input range of a facet aesthetic scale. Just like discrete positional aesthetics. You can also use `RENAMING` on the scale to customize facet strip labels.
+In order to show data where the facet variable is null, it is necessary to explicitly include `null` in the input range of a facet aesthetic scale. 
+Just like discrete position aesthetics. You can also use `RENAMING` on the scale to customize facet strip labels.
 
 ```{ggsql}
 VISUALISE sex AS x FROM ggsql:penguins