Merged upstream/main into website-polish

Author: thomasp85

CLAUDE.md

@@ -1480,7 +1480,7 @@ PROJECT [<aesthetic>, ...] TO <coord_type> [SETTING <properties>]
 | Coord Type | Default Aesthetics | Description |
 |------------|-------------------|-------------|
 | `cartesian` | `x`, `y` | Standard x/y Cartesian coordinates |
-| `polar` | `theta`, `radius` | Polar coordinates (for pie charts, rose plots) |
+| `polar` | `angle`, `radius` | Polar coordinates (for pie charts, rose plots) |
 
 **Flipping Axes**:
 
@@ -1505,7 +1505,7 @@ Note: For axis limits, use `SCALE x FROM [min, max]` or `SCALE y FROM [min, max]
 
 **Polar**:
 
-- `theta => <aesthetic>` - Which aesthetic maps to angle (defaults to `y`)
+- No special properties (angle/radius aesthetics are used directly)
 
 **Important Notes**:
 
@@ -1534,10 +1534,10 @@ PROJECT y, x TO cartesian
 -- Custom aesthetic names
 PROJECT myX, myY TO cartesian
 
--- Polar for pie chart (using default theta/radius aesthetics)
+-- Polar for pie chart (using default angle/radius aesthetics)
 PROJECT TO polar
 
--- Polar with y/x aesthetics (y becomes theta, x becomes radius)
+-- Polar with y/x aesthetics (y becomes angle, x becomes radius)
 PROJECT y, x TO polar
 
 -- Polar with start angle offset (3 o'clock position)

doc/ggsql.xml

@@ -242,7 +242,7 @@
       <item>xlim</item>
       <item>ylim</item>
       <item>ratio</item>
-      <item>theta</item>
+      <item>angle</item>
       <item>clip</item>
     </list>
 

doc/syntax/clause/facet.qmd

@@ -34,7 +34,7 @@ This clause behaves much like the `SETTINGS` clause in `DRAW`, in that it allows
   * `'y'`: Shared x-axis scale, independent y-axis scale
   * `['x', 'y']`: Independent scales for both axes
 * `missing`: Determines how layers behave when the faceting column is missing. It can take two values: `'repeat'` (default), and `'null'`. If `'repeat'` is set, then the layer data is repeated in each panel. If `'null'`, then such layers are only displayed if a null panel is shown, as controlled by the facet scale.
-* `ncol`/`nrow`: The dimensions of the layout when faceting by a single variable. Only one of these can be given, as the other is derived based on the number of panels to draw. Default is 3 columns when fewer than 6 categories are present, 4 columns when fewer than 12 categories are present and otherwise 5 columns. When the `BY`-clause is used to set a second faceting variable, the `ncol` and `nrow` setting are not allowed.
+* `ncol`/`nrow`: The dimensions of the layout when faceting by a single variable (whole number >= 1). Only one of these can be given, as the other is derived based on the number of panels to draw. Default is 3 columns when fewer than 6 categories are present, 4 columns when fewer than 12 categories are present and otherwise 5 columns. When the `BY`-clause is used to set a second faceting variable, the `ncol` and `nrow` setting are not allowed.
 
 ### Facet variables as aesthetics
 When you apply faceting to a plot you are creating new aesthetics you can control. For 1-dimensional faceting (no `BY` clause) the aesthetic is called `panel` and for 2-dimensional faceting the aesthetics are called `row` and `column`. You can read more about these aesthetics in [their documentation](../scale/aesthetic/Z_faceting.qmd)

doc/syntax/clause/project.qmd

@@ -32,6 +32,6 @@ This clause behaves much like the `SETTINGS` clause in `DRAW`, in that it allows
 If you do not provide a `PROJECT` clause then the coordinate system will be picked for you based on the mappings in your query. The logic is as follows
 
 * If `x`, `y` or any of their variants are mapped to, a Cartesian coordinate system is used
-* If `theta`, `radius` or any of their variants are mapped to, a polar coordinate system is used
+* If `angle`, `radius` or any of their variants are mapped to, a polar coordinate system is used
 * If none of the above applies, the plot defaults to a Cartesian coordinate system
-* If multiple applies (e.g. mapping to both x and theta) an error is thrown
+* If multiple applies (e.g. mapping to both x and angle) an error is thrown

doc/syntax/coord/cartesian.qmd

@@ -20,7 +20,7 @@ assuming they do not try to use a name that is already being used by any facet o
 
 ## 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)
+* `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
 

doc/syntax/coord/polar.qmd

@@ -8,32 +8,32 @@ The polar coordinate system interprets its primary aesthetic as the angular posi
 The polar coordinate system has the following default positional aesthetics which will be used if no others have been provided:
 
 * **Primary**: `radius` (distance from center)
-* **Secondary**: `theta` (angular position)
+* **Secondary**: `angle` (angular position)
 
 Users can provide their own aesthetic names if needed. For example, if using `x` and `y` aesthetics:
 
 ```ggsql
 PROJECT y, x TO polar
 ```
 
-This maps `y` to radius and `x` to theta (angle). This is useful when converting from a cartesian coordinate system without editing all the mappings.
+This maps `y` to radius and `x` to angle. This is useful when converting from a cartesian coordinate system without editing all the mappings.
 
 ## Settings
 * `clip`: Should data be removed if it appears outside the bounds of the coordinate system. Defaults to `true`
-* `start`: The starting angle in degrees for the theta scale. Controls where "0" on the angular axis begins. Defaults to `0` (12 o'clock position).
+* `start`: The starting angle in degrees for the theta scale (-360 to 360). Controls where "0" on the angular axis begins. Defaults to `0` (12 o'clock position).
   - `0` = 12 o'clock position (top)
   - `90` = 3 o'clock position (right)
   - `-90` or `270` = 9 o'clock position (left)
   - `180` = 6 o'clock position (bottom)
-* `end`: The ending angle in degrees for the theta scale. Defaults to `start + 360` (a full circle). Use this with `start` to create partial polar plots like gauge charts or half-circle visualizations.
+* `end`: The ending angle in degrees for the theta scale (-360 to 360). Defaults to `start + 360` (a full circle). Use this with `start` to create partial polar plots like gauge charts or half-circle visualizations.
 * `inner`: The inner radius as a proportion (0 to 1) of the outer radius. Defaults to `0` (no hole). Setting this creates a donut chart where the inner portion is empty.
   - `0` = full pie (no hole)
   - `0.3` = donut with 30% hole
   - `0.5` = donut with 50% hole
 
 ## Examples
 
-### Pie chart using theta/radius aesthetics
+### Pie chart using angle/radius aesthetics
 ```{ggsql}
 VISUALISE species AS fill FROM ggsql:penguins
 DRAW bar

doc/syntax/layer/position/dodge.qmd

@@ -12,7 +12,7 @@ Dodge doesn't have specific requirements to the scale type of the plot, but will
 ## Settings
 Apart from the settings of the layer type, setting `position => 'dodge'` will allow these additional settings:
 
-* `width`: The total width the dodging will occupy as a proportion of the space available on the scale. Defaults to 0.9 but any defaults from the layer will take precedence.
+* `width`: The total width the dodging will occupy as a proportion of the space available on the scale (0 to 1). Defaults to 0.9 but any defaults from the layer will take precedence.
 
 ## Examples
 

doc/syntax/layer/position/jitter.qmd

@@ -12,17 +12,17 @@ Jitter requires at least one axis to be discrete as it only jitters along discre
 ## Settings
 Apart from the settings of the layer type, setting `position => 'jitter'` will allow these additional settings:
 
-* `width`: The total width the jittering will occupy as a proportion of the space available on the scale. Defaults to 0.9
+* `width`: The total width the jittering will occupy as a proportion of the space available on the scale (0 to 1). Defaults to 0.4
 * `dodge`: Should dodging be applied before jittering. The dodging behavior follows the [dodge position](dodge.qmd) behavior? Default to `true`
 * `distribution`: Which kind of distribution should the jittering follow? One of:
   - `'uniform'` (default): Jittering is sampled from a uniform distribution between `-width/2` and `width/2`
   - `'normal'`: Jittering is sampled from a normal distribution with σ as `width/4` resulting in 95% of the points falling inside the given width
   - `'density'`: Jittering follows the density distribution within the group so that the jitter occupies the same area as an equivalent [violin plot](../type/violin.qmd) with density remapped to offset
   - `'intensity'`: Jittering follows the intensity distribution within the group so that the jitter occupies the same area as an equivalent [violin plot](../type/violin.qmd) with intensity remapped to offset
-  
+
   If `distribution` is either `'density'` or `'intensity'` then one of the axes must be continuous
-* `bandwidth`: A numerical value setting the smoothing bandwidth to use for the `'density'` and `'intensity'` distributions. If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
-* `adjust`: A numerical value as multiplier for the `bandwidth` setting, with 1 as default.
+* `bandwidth`: Smoothing bandwidth for the `'density'` and `'intensity'` distributions (must be > 0). If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
+* `adjust`: Multiplier for the `bandwidth` setting (must be > 0). Defaults to 1.
 
 ## Examples
 When plotting points on a discrete axis they are all placed in the middle

doc/syntax/layer/position/stack.qmd

@@ -13,7 +13,7 @@ Stack requires a continuous scale with a range mapping (e.g. either `y` + `yend`
 Apart from the settings of the layer type, setting `position => 'stack'` will allow these additional settings:
 
 * `center`: Should the full stack be centered around 0. Can be used in conjunction with area layers to create steamgraphs. Default to `false`
-* `total`: Sets a total value to which each stack height is normalised. Setting this value leads to 'fill' behaviour. Defaults to `null` (no normalisation)
+* `total`: Sets a total value to which each stack height is normalised (must be > 0 if specified). Setting this value leads to 'fill' behaviour. Defaults to `null` (no normalisation)
 
 ## Examples
 

doc/syntax/layer/type/area.qmd

@@ -21,8 +21,8 @@ The following aesthetics are recognised by the area layer.
 * `linewidth`: The width of the contour lines.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'stack'`)
-* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following: 
+* `position`: Position adjustment. One of `'identity'`, `'stack'` (default), `'dodge'`, or `'jitter'`
+* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following:
     * `'aligned'` to align the layer's primary axis with the coordinate system's first axis.
     * `'transposed'` to align the layer's primary axis with the coordinate system's second axis.