(Non)Position aesthetics name formatting

CLAUDE.md

@@ -1470,7 +1470,7 @@ PROJECT [<aesthetic>, ...] TO <coord_type> [SETTING <properties>]
 
 **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.
@@ -1511,7 +1511,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/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. 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**: `theta` (angular position)

doc/syntax/index.qmd

@@ -62,7 +62,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,17 +2,21 @@
 title: "Position"
 ---
 
-Position aesthetics (`x` and `y`, plus all their variants) 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.
+Position aesthetics (`x` and `y`, plus all their variants) 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.
 
 ## 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 consist of two families: The `x` and `y` family. Each of these consist of their primary aesthetic along with a range of sub aesthetic defined by their suffix:
+Position aesthetics consist of two families: The `x` and `y` family. 
+Each of these consist of their primary aesthetic along with a range of sub aesthetic defined by their suffix:
 
 * `2`
 * `end`
@@ -22,4 +26,6 @@ Positional aesthetics consist of two families: The `x` and `y` family. Each of t
 Which version of 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 => ...`
 
 ## Coordinate system
-Another thing that makes positional aesthetics different from other aesthetic is that they are dependent on a coordinate system which takes position scales and defines how values should be converted to a location on a plane. The default Cartesian coordinate system does what is generally expected: it places points along two perpendicular axes in a 2D plane. Other systems such as polar coordinates may dramatically change the look of a layer, transforming both the straightness of lines and positional relation of data.
+Another thing that makes position aesthetics different from material aesthetics is that they are dependent on a coordinate system which takes position scales and defines how values should be converted to a location on a plane. 
+The default Cartesian coordinate system does what is generally expected: it places points along two perpendicular axes in a 2D plane. 
+Other systems such as polar coordinates may dramatically change the look of a layer, transforming both the straightness of lines and position relation of data.

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

doc/syntax/scale/type/binned.qmd

@@ -11,7 +11,8 @@ The binned scale is never chosen automatically so it must be selected explicitly
 ## Input range
 The input range for binned scales are defined by their minimum and maximum values. These can be given explicitly or deduced from the mapped data. If `FROM` is omitted then the range will be given as the minimum and maximum break values, whether provided directly or calculated. If provided as an array of length 2 then the first element will set the minimum and the second element will set the maximum. If either of these elements are `null` then that part of the range will be deduced from the data. As an example `SCALE BINNED x FROM [0, null]` will set the minimum part of the range to 0 and the maximum part to the maximal value of the mapped data. However, if neither input range nor explicit breaks are provided then the input range will be modified so that the calculated bins are even sized and include all data. This means that the range in most cases will expand past the minimum and maximum data values.
 
-Positional aesthetics (`x` and `y`) will have their range expanded based on the `expand` setting. If values in the mapped data falls outside of the input domain the values will be changed based on the `oob` setting.
+Position aesthetics (`x` and `y`) will have their range expanded based on the `expand` setting. 
+If values in the mapped data falls outside of the input domain the values will be changed based on the `oob` setting.
 
 The input range is converted to the type defined by the transform. This means that a time range can both be given as a `%H:%M:%S` string or as a numeric giving the number of nanoseconds since midnight.
 

doc/syntax/scale/type/continuous.qmd

@@ -9,7 +9,8 @@ The continuous scale type maps various continuous data types into a continuous o
 ## Input range
 The input range for continuous scales are defined by their minimum and maximum values. These can be given explicitly or deduced from the mapped data. If `FROM` is omitted then the range of the mapped data is used. If provided as an array of length 2 then the first element will set the minimum and the second element will set the maximum. If either of these elements are `null` then that part of the range will be deduced from the data. As an example `SCALE x FROM [0, null]` will set the minimum part of the range to 0 and the maximum part to the maximal value of the mapped data.
 
-Positional aesthetics (`x` and `y`) will have their range expanded based on the `expand` setting. If values in the mapped data falls outside of the input domain the values will be changed based on the `oob` setting.
+Position aesthetics (`x` and `y`) will have their range expanded based on the `expand` setting. 
+If values in the mapped data falls outside of the input domain the values will be changed based on the `oob` setting.
 
 The input range is converted to the type defined by the transform. This means that a time range can both be given as a `%H:%M:%S` string or as a numeric giving the number of nanoseconds since midnight.