document ordinal aspectRatio (#2255)

Author: mbostock

docs/features/plots.md

@@ -224,7 +224,7 @@ The default **width** is 640. On Observable, the width can be set to the [standa
 Plot does not adjust margins automatically to make room for long tick labels. If your *y* axis labels are too long, you can increase the **marginLeft** to make more room. Also consider using a different **tickFormat** for short labels (*e.g.*, `s` for SI prefix notation), or a scale **transform** (say to convert units to millions or billions).
 :::
 
-The **aspectRatio** option<a id="aspectRatio" href="#aspectRatio" aria-label="Permalink to &quot;aspectRatio&quot;"></a> <VersionBadge version="0.6.4" />, if not null, computes a default **height** such that a variation of one unit in the *x* dimension is represented by the corresponding number of pixels as a variation in the *y* dimension of one unit.
+The **aspectRatio** option<a id="aspectRatio" href="#aspectRatio" aria-label="Permalink to &quot;aspectRatio&quot;"></a> <VersionBadge version="0.6.4" />, if not null, computes a default **height** such that a variation of one unit in the *x* dimension is represented by the corresponding number of pixels as a variation in the *y* dimension of one unit. The **aspectRatio** option is recommended only when *x* and *y* domains share the same units, such as millimeters. When a position scale is [ordinal](./scales.md#discrete-scales) (*point* or *band*), consecutive domain values are treated as one unit length apart; for example, if both *x* and *y* are ordinal, then an aspect ratio of one produces a square grid.
 
 <p>
   <label class="label-input">

docs/features/scales.md

@@ -292,7 +292,7 @@ Plot.plot({
 ```
 :::
 
-Positions scales also have a **round** option which forces the scale to snap to integer pixels. This defaults to true for point and band scales, and false for quantitative scales. Use caution with high-cardinality ordinal domains (*i.e.*, a point or band scale used to encode many different values), as rounding can lead to “wasted” space or even zero-width bands.
+Position scales also have a **round** option which forces the scale to snap to integer pixels. This defaults to true for point and band scales, and false for quantitative scales. Use caution with high-cardinality ordinal domains (*i.e.*, a point or band scale used to encode many different values), as rounding can lead to “wasted” space or even zero-width bands.
 
 ## Color scales
 

src/plot.d.ts

@@ -30,8 +30,10 @@ export interface PlotOptions extends ScaleDefaults {
    * height. Given an aspect ratio of *dx* / *dy*, and assuming that the *x* and
    * *y* scales represent equivalent units (say, degrees Celsius or meters),
    * computes a default height such that *dx* pixels along *x* represents the
-   * same variation as *dy* pixels along *y*. Note: when faceting, set the *fx*
-   * and *fy* scales’ **round** option to false for an exact aspect ratio.
+   * same variation as *dy* pixels along *y*. When *x* or *y* is ordinal,
+   * consecutive domain values are treated as one unit length apart. Note: when
+   * faceting, set the *fx* and *fy* scales’ **round** option to false for an
+   * exact aspect ratio.
    */
   aspectRatio?: number | boolean | null;