plot-io 0.6.0__tar.gz → 0.7.0__tar.gz

{plot_io-0.6.0 → plot_io-0.7.0}/API.md

@@ -17,8 +17,8 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
 
 ## 1. Conventions
 
-* **Model.** A `Figure` holds plots (and colorbars) in a grid; a `Plot` holds series, two
-  axes, a title, a legend and colorbars; a series holds data and style. Nothing is
+* **Model.** A `Figure` holds plots (and colorbars) in a grid, and titles; a `Plot` holds
+  series, two axes, titles, a legend and colorbars; a series holds data and style. Nothing is
   computed until the figure is drawn (`save`, `to_bytes`, `draw`), so settings can change
   in any order.
 * **Settings.** Every object takes its settings as keywords when created and in
@@ -52,7 +52,7 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `"calc(1.4 * inherit)"`, a fill's opacity `"calc(0.3 * inherit)"`). `"XAxis.name"` and
   `"YAxis.name"` give one axis its own default.
 * **`"auto"`.** A setting whose default is `"auto"` documents its rule. Rules that follow
-  from the model (a colorbar's orientation from its position, a legend's inner pad from
+  from the model (a colorbar's orientation from its side, a legend's inner pad from
   its frame, a genome track's gap) are resolved with the setting: `resolve()` returns the
   result and `get()` `"auto"`. Rules that need the data or the layout (axis limits,
   padding, tick count and rotation, number formats, legend placement) are resolved when
@@ -86,8 +86,8 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `Swarm` `width`) are `"80%"` of the slot or `"0.8d"` in data units. Positions along an
   axis (a decoration's `min`/`max`) take bare numbers as data values. See
   [values](#values).
-  Images are `dpi` pixels per inch: `dpi=96` gives one image pixel per px, the default 192
-  two. A dpi up to 16 is a multiple of 96: `dpi=2` is 192. PDF pages are sized in pt (× 0.75).
+  Images are `dpi` pixels per inch: `dpi=96` gives one image pixel per px, the default 384
+  four. A dpi up to 16 is a multiple of 96: `dpi=2` is 192. PDF pages are sized in pt (× 0.75).
 * **Data.** Sequences (`None` = missing), `array.array`, or any buffer (numpy arrays are
   read without importing numpy). NaN or `None` values are missing: scatter skips them,
   line and fill break there, box ignores them, heatmap cells take `nan_color`.
@@ -95,7 +95,15 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   ([tables](#tables-data)); dates make time axes ([dates](#dates-and-times)).
 * **Text.** Titles, axis labels and legend entries are strings or rich content: a list of
   strings and `pl.Span` (vec_io's), e.g. `["Area (m", pl.Span("2",
-  baseline_shift="super", font_scale=0.7), ")"]`.
+  baseline_shift="super", font_scale=0.7), ")"]`. Strings take markup:
+  `"Growth of <i>E. coli</i> at <b>37 °C</b>"`, `"Area (m<sup>2</sup>)"`. Tags: `<i>`/`<em>`
+  italic, `<b>`/`<strong>` bold, `<u>` underline, `<s>`/`<del>` strikethrough, `<sup>` and
+  `<sub>` (0.7 of the size, raised 0.33 em or lowered 0.2 em), in either case, nested,
+  each closed by its own end tag; an unclosed or crossed tag is an error. Styles add to the text's own (`<b>`
+  in a bold title stays bold). Any other `<` is text (`x < 5`, `<0.05`); `&lt;`, `&gt;` and
+  `&amp;` write `<`, `>` and `&`. Strings inside rich content are read too; tick labels
+  take no markup. `markup=False` (inherited: on the figure, a plot or a text element) keeps
+  strings literal; `get()` returns the string as given.
 * **Named colors.** `"blue"`, `"blue 0.45"`, `"blue 45%"`: 28 scales (`red`, `orange`,
   `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`,
   `violet`, `purple`, `fuchsia`, `pink`, `rose`, `slate`, `gray`/`grey`, `zinc`, `neutral`,
@@ -125,9 +133,13 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   not installed tries its metric aliases first: Helvetica and Arial → Liberation Sans,
   Arimo, …), then a generic family's list (`sans-serif`: Arial, Helvetica, Liberation
   Sans, DejaVu Sans, Noto Sans, …), then any font with the character. The default
-  `"SF Pro, Inter, Helvetica, Arial, sans-serif"` is SF Pro where installed, else Inter,
-  else Helvetica or Arial (or an alias of theirs), else the system's sans-serif. With no
-  outline font at all, output raises `NoFontError` (a `ValueError`, from vec_io).
+  `"Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo"` is Helvetica where
+  installed, else the first of the others installed (all have Helvetica's widths); with
+  none installed, vec_io downloads Nimbus Sans (URW's base 35 fonts). With no outline
+  font at all, output raises
+  `NoFontError` (a `ValueError`, from vec_io). A line of text is `line_height` tall (a
+  multiple of the font size; default 1), the glyphs centered in it, so the gaps around
+  text do not change with the font; `"normal"` takes the font's ascent and descent.
 * **Names.** `pl.` holds the figure and plot classes, the plot types, the value types
   (`ColorAxis`, `SizeAxis`, `ColorMap`, `SizeMap`, `Palette`, `Density`, `ErrorBars`,
   `Span`), `facet`, the registries (`register_layer`, `register_marker`,
@@ -201,7 +213,8 @@ What `%` of a length can be of, besides another setting (the tables name it per
 | `axes_length` | the axes length along the axis |
 | `data_range` | the axis range |
 | `bar_across` | the axes side across the colorbar |
-| `bar_along` | the axes side along the colorbar |
+| `bar_thickness` | the span along a key, the axes side across a bar |
+| `bar_along` | the span along the colorbar (the axes side of an attached one) |
 | `figure` | the figure width (across) or height (down) |
 | `slot` | the slot: one category, or the smallest gap between positions |
 | `slot_part` | each series' part of a shared slot |
@@ -223,12 +236,14 @@ contours, genome signals and intervals); `"Marker.fill"` every marker fill.
 | `Font` | `font_stretch` | `{p}font_stretch` | inherited |
 | `Font` | `font_variations` | `{p}font_variations` | inherited |
 | `Font` | `font_optical_sizing` | `{p}font_optical_sizing` | inherited |
+| `Font` | `line_height` | `{p}line_height` | inherited |
+| `Font` | `markup` | `{p}markup` | inherited |
 | `TextStyle` | `font_size` | `{p}font_size` | '1em' |
 | `TextStyle` | `font_weight` | `{p}weight` | 'normal' |
 | `TextStyle` | `font_style` | `{p}style` | 'normal' |
 | `TextStyle` | `color` | `{p}color` | 'var(text_color)' |
 | `Stroke` | `color` | `{p}color` | — |
-| `Stroke` | `line_width` | `{p}width` | 0.75 |
+| `Stroke` | `line_width` | `{p}width` | 0.5 |
 | `Stroke` | `line_style` | `{p}style` | 'solid' |
 | `Stroke` | `cap` | `{p}cap` | 'butt' |
 | `Stroke` | `join` | `{p}join` | 'round' |
@@ -236,7 +251,7 @@ contours, genome signals and intervals); `"Marker.fill"` every marker fill.
 | `Marker` | `size` | `{p}size` | 4.5 |
 | `Marker` | `color` | `{p}color` | — |
 | `Marker` | `edge_color` | `{p}edge_color` | 'auto' |
-| `Marker` | `edge_width` | `{p}edge_width` | 0.75 |
+| `Marker` | `edge_width` | `{p}edge_width` | 0.5 |
 | `Marker` | `fill` | `{p}fill` | True |
 | `Marker` | `size_basis` | `size_basis (never prefixed)` | 'area' |
 | `FillStyle` | `fill` | `{p}fill` | — |
@@ -262,7 +277,10 @@ pl.Figure(**settings)
 fig.plot(id=None, **settings)            # the plot with id (created if needed), or the next one
 fig.scatter(x, y, **settings)            # any plot type: a new plot holding it
 fig.title(text, **settings)              # figure title
+fig.add_title(text, plots=None, side="top", **settings)   # another, over plots
+fig.add_legend(plots=None, side="right", **settings)      # a legend of plots' entries
 fig.x_axis(**settings)                   # settings of every plot's x axis (fig.y_axis: y)
+fig.add_colorbar(source=None, plots=None, side="bottom", **settings)  # beside plots
 fig.colorbar(source, id=None, **settings)    # the guide of a color axis, in its own area
 fig.color_axis(**settings)               # a shared color axis (fig.size_axis: size)
 fig.size_legend(source, id=None, values=None, title=None)
@@ -271,6 +289,7 @@ fig.vline(x, rows=None, **settings)      # through plots and the gaps between th
 fig.vspan(x0, x1=None, rows=None, **settings)
 fig.group(first, last=None, label=None, letter=None)
 fig.plots                                # plots in creation order
+fig.titles, fig.legends, fig.colorbars   # figure titles (main first), legends, colorbars
 ```
 
 A plot type called on the figure (`fig.scatter(…)`, `fig.hist(…)`, `fig.bigwig(…)`) makes
@@ -326,8 +345,8 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 | `"axes"` | each cell's axes are `width` | the widest plot box of a column (axes plus the column's largest margins) is `width`; the axes are what is left | the figure is `width`; the axes share what the gutters leave |
 | `"borders"` | a column's box is `width` plus the largest margins in it, so every axes rectangle is at least `width` | each cell's box is `width` | the figure is `width`; the boxes share what the gaps leave |
 
-* Columns (rows) holding only vertical (horizontal) colorbars are as wide as the bar,
-  unless `widths` (`heights`) is given.
+* Columns (rows) holding only vertical (horizontal) colorbars are as wide as the bar (a
+  key: as wide as it is), unless `widths` (`heights`) is given.
 * Margins come from the real text metrics of tick labels, axis labels, titles, outside
   legends and attached colorbars ([layout](#layout)).
 
@@ -335,21 +354,24 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 
 * **Bands.** A plot is its axes rectangle with four stacks of bands around it, from the
   axes outward: tick marks, tick labels, the ×10ᵏ offset (above the y axis), the axis
-  label, twin axes, an outside legend, attached colorbars, the plot title (top) and the
-  plot's `space_above`; outermost on the left, the row label and group bands, as wide as the
-  widest of the plot's grid column. Each band has a thickness and an overhang along its
+  label, twin axes, an outside legend, attached colorbars, the plot's titles and (on top)
+  the plot's `space_above`; outermost on the left, the row label band and the band of
+  [group](#rows) letters, as wide as the widest of the plot's grid column. Each band has a thickness and an overhang along its
   side (tick labels past the ends of the axis, a wide title). A side's margin is its
   bands' thicknesses, at least the overhangs of the bands across it. Bands stack: each
-  starts past the ones before it (mirrored ticks included), the title past everything on
-  top; only twin axes are drawn at the axes edge.
+  starts past the ones before it (mirrored ticks included), the titles past everything on
+  their side; only twin axes are drawn at the axes edge.
 * **Grid.** Each line between cells takes the largest margin of the plots there
   (`align="axes"`), or each plot's axes are what its margins leave of its box
   (`"borders"`). Colorbars and size legends in their own areas are cells of the grid; the
-  figure title is a band at the top of the figure.
+  figure title is a band at the top of the figure, and the other figure titles, the
+  figure legends and colorbars and the groups' labels sit in lanes in the lines between
+  cells ([figure title](#figure-title)).
 * **Rounds.** Only what is circular is repeated: an axis' length sets its ticks, whose
   labels set the margins, which (with `reference="plot"` or `"figure"`) set the length;
   `data_ratio`; stats binned at the axes' resolution ([hexbin](#hexbin), genome
-  [bins](#9-genome-tracks)); the figure title's band in a figure of fixed height. A round
+  [bins](#9-genome-tracks)); the figure title's band in a figure of fixed height; the
+  lanes of figure titles that wrap to the width of the plots they cover. A round
   measures every plot for its axes size and solves the grid. Rounds stop when no axes size
   moves by more than 1/3 px; after 5, a layout still moving (between two tick sets) keeps
   the last. With `reference="axes"` one round suffices. `position="auto"` legends are
@@ -357,10 +379,13 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 * **Geometry.** The layout ends in a frozen geometry: every axes rectangle, tick mark,
   text run, legend entry and colorbar in px. Drawing reads it and measures nothing: a text
   run holds its shaped line (shaped once per content and font, memoized in the font
-  database), which is what is drawn; the figure title is laid out once as paragraphs.
+  database), which is what is drawn; figure titles on top and bottom are laid out once as
+  paragraphs.
 * **One plot.** `p.save()` lays out the whole figure and keeps the plot at its size in it:
   its axes (`align="axes"`), or its box (`"borders"`: the axes are what its own margins
-  leave), with its outer tick labels and its own row label band.
+  leave), with its outer tick labels, its own row label band, its own titles and its
+  whole legend and its attached colorbars (figure titles, legends and colorbars are left
+  out).
 
 ### Figure title
 
@@ -368,32 +393,84 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 fig.title(text, **settings)        # None removes it
 ```
 
-A band at the top of the figure: the title's height (all lines, wrapped within its
-width) plus `pad`. The figure grows by the band, except with `reference="figure"`, where
-the plots shrink by it. `over="axes"` aligns it within the leftmost to
-rightmost axes (a left-aligned title starts at the first y axis line), `"figure"` within
-the figure minus `margin`. Rich content styles a second line (`["Title\n",
-pl.Span("subtitle", font_size=7, font_weight="normal")]`). It is drawn last and is not
-part of `Plot.save`. `title=` given to `pl.Plot` sets the plot title. The figure's
-`title_rule_color` draws a rule `title_rule_width` thick above the title, across its
-width.
+```python
+fig.add_title("Treated", plots=[a, b], side="top", **settings)   # returns it
+fig.titles                         # the main title first
+```
+
+The main title is a band at the top of the figure: the title's height (all lines,
+wrapped within its width) plus `pad`. The figure grows by the band, except with
+`reference="figure"`, where the plots shrink by it. `over="axes"` aligns it within the
+leftmost to rightmost axes (a start-aligned title starts at the first y axis line),
+`"plot"` within their boxes, `"figure"` within the figure minus `margin`. Rich content
+styles a second line (`["Title\n", pl.Span("subtitle", font_size=7,
+font_weight="normal")]`). It is drawn last and is not part of `Plot.save`. `title=` given
+to `pl.Plot` sets the plot title. `rule` draws a line `rule_width` thick across its width:
+`"outside"` above the title (The Economist's red bar, in the `economist` style), `True`
+between the title and the plots.
+
+`fig.add_title` makes a title over a set of plots (plots or their series, as
+`fig.group` takes them; default every plot), which covers the grid rectangle of their
+cells: a plot inside that rectangle but not given is an error naming it. Figure titles
+share the settings of plot titles ([title](#title)).
+
+```python
+fig.add_title("Sites", plots=[a, b, c])
+fig.add_title("Treated", plots=[a, b])              # nested: under "Sites"
+fig.add_title("Control", plots=[d, e], rule=True)   # beside another span: same lane
+fig.add_title("Batch 1", plots=[a, d], side="left")
+```
+
+* **Lanes.** A figure title sits in the line between cells beside the plots it covers: a
+  top title above its topmost row, a bottom one below its bottommost, a left or right one
+  beside its first or last column. The titles of one side of a line stack outward from
+  the plots: a title whose plots are a subset of another's is nearer, titles over
+  disjoint spans share a lane, overlapping ones take lanes in creation order; `order`
+  overrides (lower nearer; unset counts as the lane the rules give): a title sits past
+  every lane of a lower order, and titles of one order share a lane where their spans
+  are disjoint. A lane is as thick
+  as its thickest title: `pad`, the text, and `rule_width + rule_gap` with a rule. Plot
+  titles are inside the plots' boxes, nearer than any figure title. Figure legends and
+  colorbars take lanes too ([figure legends](#figure-legends), [colorbars](#colorbars));
+  over the same plots, from the plots outward: legend, colorbar, title.
+* **Gaps.** The gap at a line between rows (columns) is `spacing` plus its lanes, along
+  the whole line, so the titles in it line up. On the figure's edge, the lanes come between
+  two `margin`s, one at the edge and one between them and the plots, as the main title's
+  band does. With `reference="figure"` the plots shrink by the lanes; otherwise the
+  figure grows.
+* **Text.** Titles on top and bottom wrap to their span (`over`); titles on the left and
+  right do not (`\n` starts a line) and read upward on the left, downward on the right.
+* A [group](#rows)'s `label` is a left figure title over its plots.
+* The main title is the outermost lane of the top, over every plot. On another side,
+  rotated, or with an `order`, it is laid out in the lanes as the others are.
+  Style keys `"MainTitle.name"` apply to it alone, `"FigureTitle.name"` to every figure
+  title.
+* `p.save()` (one plot alone) leaves out the figure titles, legends and colorbars.
 
 <!-- settings:FigureTitle -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `text` | — | Title text: a string or rich content; `\n` starts a line. |
+| `side` | 'top' | `top`, `bottom`, `left` or `right`. |
+| `align` | 'center' | Alignment along the side: `start`, `center`, `end` (`left` and `right`: `start` and `end`); along the left and right sides, `start` is where rotated text begins (the bottom at 90, the top at −90 and 0). |
+| `over` | 'axes' | Span it is aligned and wrapped within: from the first to the last axes of its plots, their boxes, or the whole figure. |
+| `rotation` | 'auto' | `auto`: 0 on top and bottom, 90 on the left (reads upward), −90 on the right (reads downward); or 0, 90, −90. |
+| `pad` | '0.5em' | Gap between the title and the plots. Length. |
+| `order` | — | Place in its side's lanes: lower is nearer the plots; unset: a title nested in another nearer, then creation order. |
+| `rule` | False | A line along the span: `True` or `"inside"` between the title and what it covers, `"outside"` beyond the title, `False` none. |
+| `rule_color` | 'var(color)' | Color of the rule. |
+| `rule_width` | 'var(line_width)' | Thickness of the rule. Length. |
+| `rule_gap` | '0.5em' | Gap between the rule and the title. Length; `%`: of the font size. |
 | `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
 | `font_weight` | 'bold' | `normal`, `bold` or a weight 1–1000. |
 | `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
-| `align` | 'center' | Alignment. |
-| `over` | 'axes' | Width it is aligned and wrapped within: from the leftmost to the rightmost axes, or the whole figure. |
-| `pad` | '0.5em' | Gap between the title and the plots; default half the font size. Length. |
 | `color` | 'var(text_color)' | Text color. |
-| `rule_gap` | '0.5em' | Gap between the title and the figure's `title_rule_color`. Length; `%`: of the font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `TextStyle`, `Font`.
 <!-- /settings -->
@@ -411,7 +488,8 @@ the same column span) or `"row"` (the same row span). `share` sets both; `"grid"
 per column and y per row. A plot's own `share_x`, `share_y` or `share` (another plot)
 overrides the figure's groups for it; groups chain. Colorbars and plots without axes are
 never in a group. `share_color` and `share_size` group plots the same way for their
-series' color and size axes ([color and size axes](#6-color-and-size-axes)).
+series' color and size axes ([color and size axes](#6-color-and-size-axes)), and
+`share_legend` for one legend of their entries ([figure legends](#figure-legends)).
 
 Within a group the scale (which must be equal), the limits (from all members' series,
 then padding, `include_zero` and `snap`; one explicit `limits` applies to the group, two
@@ -451,9 +529,15 @@ fig.vspan(-1, 1)                                 # under every plot
   label: beside its axis or in the band. Tracks put theirs in the band. A plot's
   `space_above` adds space above it.
 * **Groups.** `fig.group(first, last=None, **settings)`: plots `first` to `last` (plots
-  or their series, in creation order) with a rotated `label` and a bold panel `letter` in a
-  band left of the row labels. With a shared x axis and `label_outer`, the group's last
-  plot shows the tick labels too (the axis title stays under the bottom plot).
+  or their series, in creation order). Its `label` is a left [figure title](#figure-title)
+  over them, reading upward, centered on their axes, in the group's font settings
+  (`font_size`, `font_family`, `text_color`, `markup`; normal weight) and `pad` from the
+  plots; it is made at each layout, in the group's creation order, and is not in
+  `fig.titles`. The plots must fill the grid rectangle they span. A bold panel `letter`
+  sits in a band left of the row labels, level with the top of the first plot's axes.
+  With a shared x axis and `label_outer`, the group's last plot shows the tick labels too
+  (the axis title stays under the bottom plot). `p.save()` leaves out the label, as other
+  figure titles.
 * **Lines and bands.** `fig.vline(x, rows=None)` and `fig.vspan(x0, x1, rows=None)` run
   from the top of the first of the plots `rows` (a plot, a series, or a list; all by
   default) to the bottom of the last one, gaps included, in each grid column; `x` is in
@@ -467,7 +551,7 @@ FigureVLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'dashed' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
 | `alpha` | 1.0 | Opacity. |
 
@@ -488,16 +572,17 @@ FigureGroup:
 <!-- settings:FigureGroup -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `label` | — | Group label, rotated, left of the plots' row labels. |
-| `letter` | — | Panel letter at the group's top left. |
+| `label` | — | Group label: a left figure title over the group's plots, reading upward, centered on their axes. |
+| `letter` | — | Panel letter at the group's top left, left of the row labels. |
 | `font_size` | '1em' | Font size of the label. Length; `%`: of the parent's font size. |
 | `letter_font_size` | '1.4em' | Font size of the letter. Length; `%`: of the font size. |
 | `letter_weight` | 'bold' | Weight of the letter. |
-| `pad` | '0.5em' | Gap right of the group band. Length; `%`: of the font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `pad` | '0.5em' | Gap right of the letter, and the label's `pad` (its gap to the plots). Length; `%`: of the font size. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
-Groups: `TextStyle` (`letter_`).
+Groups: `TextStyle` (`letter_`), `Font`.
 <!-- /settings -->
 
 ### Facets
@@ -526,9 +611,10 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
   column, y per row, outer labels only), `share_color` (default `"all"`: the panels'
   color axes train as one; a `color_map`, `color_limits` or `color_scale` given to the
   call goes to each series alike) and `share_size` (default `"all"`: one size axis, so
-  one size key, in the top-right panel's legend).
+  one size key) and `share_legend` (default `"all"`: one legend for the panels' entries,
+  on the right, [figure legends](#figure-legends)).
 * **Colorbar.** `colorbar="right"`, `"left"`, `"top"` or `"bottom"` adds a column (or a
-  row, with a horizontal bar) to the grid, holding the colorbar of the first call that maps
+  row, with a horizontal colorbar) to the grid, holding the colorbar of the first call that maps
   colors (`panels.colorbar`): the guide of the panels' shared color axis.
 * `panels.panels` maps facet keys (a value, or `(row value, col value)`) to plots;
   `panels.plot(key)` returns one; iterating the set gives the plots; `panels.subsets()`
@@ -553,26 +639,27 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
 | `spacing` | 13.0 | Minimum gap between neighbouring plots. Length; `%`: of the figure width (across) or height (down). |
 | `margin` | 5.0 | Space around the figure. Length; `%`: of the figure width (across) or height (down). |
 | `background` | 'white' | Figure background, default white; `None` or `"none"`: transparent (white in JPEG, which has no transparency). |
-| `dpi` | 192.0 | Resolution of PNG, JPEG, JPEG XL and AVIF output: `96` gives one image pixel per px, the default `192` two; up to 16, a multiple of 96 (`2` is 192). |
+| `dpi` | 384.0 | Resolution of PNG, JPEG, JPEG XL and AVIF output: `96` gives one image pixel per px, the default `384` four; up to 16, a multiple of 96 (`2` is 192). |
 | `quality` | 'auto' | Quality (1–100), as vec_io's: of PNG output (a lossy palette of at most 256 colors), JPEG, JPEG XL and AVIF output, and of rasterized content in PDFs (stored as JPEG); `"lossless"` (not JPEG); `"auto"`: 90 for PNG and JPEG, lossless for JPEG XL, AVIF and PDF content. |
-| `title_rule_color` | — | Color of a rule above the figure title, across its width (The Economist's red bar); default none. |
-| `title_rule_width` | 4.0 | Thickness of the title rule. Length. |
 | `share_x` | — | Plots sharing their x axis: `False`, `True`/`"all"`, `"col"` (same column span) or `"row"` (same row span). |
 | `share_y` | — | Plots sharing their y axis, as `share_x`. |
 | `share` | — | Both axes at once: as `share_x`, or `"grid"` (x per column, y per row); `share_x`/`share_y` override it. |
 | `share_color` | False | Plots whose series' own color axes are one (limits over all their values), as `share_x`. |
 | `share_size` | False | Plots whose series' own size axes are one (limits over all their values, one size key), as `share_x`. |
+| `share_legend` | False | Legends shared by plots, made by the figure: `False`, `True`/`"all"` (one on the right of the figure), `"row"` (one on the right of each row), `"col"` (one at the bottom of each column). |
 | `label_outer` | — | Tick labels and axis titles of shared axes only on the outer plots (bottom of each column, left of each row); default `True` for groups from the figure's settings, `False` for plots paired with `share_x=plot`. |
 | `style` | — | A style name (`"ggplot2"`, …) or a dict of settings with an optional `"base"`; default: the session style (`set_style`, `use_style`), else `"default"`. |
 | `vars` | — | Custom variables, read by `var(--name)` in any setting here and below: `{"accent": "#c00"}`. |
 | `scaling` | 1.0 | Multiplies every font size, line width, marker size, tick length and pad of the style; default 1. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `text_color` | inherited ('black') | Text color. |
-| `line_width` | inherited (0.75) | Default line width. Length. |
+| `line_width` | inherited (0.5) | Default line width. Length. |
 | `palette` | inherited ('tab10_custom') | Colors of series without one. |
 | `alpha` | inherited (1.0) | Default opacity of series. |
 | `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
@@ -586,7 +673,7 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
 
-Groups: `Stroke` (`title_rule_`), `Font`, `NumberFormat`.
+Groups: `Font`, `NumberFormat`.
 <!-- /settings -->
 
 ## 3. Plots
@@ -596,7 +683,8 @@ pl.Plot(figure=None, id=None, **settings)   # title="…", x_axis={…}, y_axis=
 p.scatter(x, y, **s)   p.line(x, y=None, **s)   p.fill(x, y1, y2=0, **s)
 p.box(values, **s)     p.heatmap(values, **s)   p.colorbar(source=None, **s)
 p.title(text, **s)     p.x_axis(label, **s)     p.y_axis(label, **s)    p.legend(position, **s)
-p.series   p.colorbars   p.figure   p.id
+p.add_title(text, side="top", **s)              # another title, returned
+p.series   p.titles   p.colorbars   p.figure   p.id
 ```
 
 `p.title`, `p.x_axis`, `p.y_axis` and `p.legend` are objects; calling one sets its
@@ -612,7 +700,7 @@ axes clip.
 | `data_ratio` | — | Data aspect ratio: 1 makes one unit as long on both axes. |
 | `background` | — | Background color of the axes area. |
 | `border_color` | — | Color of a frame around the axes area (drawn under the axis lines); default none. |
-| `border_width` | 0.75 | Width of the frame. Length. |
+| `border_width` | 0.5 | Width of the frame. Length. |
 | `clip` | True | Clip series to the axes area. |
 | `axes` | True | Draw axes; `False` hides both axes, drops padding and fixes the aspect to 1 (set by pie charts). |
 | `share_x` | — | Another plot of the figure whose x axis this plot shares (groups chain); overrides the figure's `share_x`. |
@@ -621,12 +709,14 @@ axes clip.
 | `share` | — | Another plot whose x and y axes this plot shares. |
 | `space_above` | 0.0 | Space above the plot, beyond the figure's `spacing`. Length; `%`: of the font size. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `text_color` | inherited ('black') | Text color. |
-| `line_width` | inherited (0.75) | Default line width. Length. |
+| `line_width` | inherited (0.5) | Default line width. Length. |
 | `palette` | inherited ('tab10_custom') | Colors of series without one. |
 | `alpha` | inherited (1.0) | Default opacity of series. |
 | `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
@@ -645,21 +735,49 @@ Groups: `Stroke` (`border_`), `Font`, `NumberFormat`.
 
 ### Title
 
+```python
+p.title("Yield")                                 # the main title
+p.add_title("Subtitle", order=-1)                # between the main title and the axes
+p.add_title("n = 120", side="bottom", align="start")
+p.add_title("Batch 1", side="left", rule=True)
+```
+
+A plot has a main title (`p.title`) and any number of others (`p.add_title`, which
+returns the title; `p.titles` lists them, main first), each on a `side` of the plot.
+The titles of one side stack outward from the axes, outermost of the side's bands (past
+the axis, twin axes, an outside legend and attached colorbars): the main title nearest,
+then the others in creation order; `order` places a title elsewhere, lower nearer
+(`order=-1`: a subtitle between the main title and the axes). Each takes a band of its
+`pad`, its text across the side and, with a `rule`, `rule_width + rule_gap`; the rule runs
+along its span (`over`). `\n` starts a line, `line_height` apart; the last line is
+nearest the axes on top and on the left and right, the first at the bottom. Left titles
+read upward, right titles downward (`rotation="auto"`); `rotation=0` sets them
+horizontal, beside the axes.
+
 <!-- settings:Title -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `text` | — | Title text: a string or rich content. |
+| `text` | — | Title text: a string or rich content; `\n` starts a line. |
+| `side` | 'top' | `top`, `bottom`, `left` or `right`. |
+| `align` | 'center' | Alignment along the side: `start`, `center`, `end` (`left` and `right`: `start` and `end`); along the left and right sides, `start` is where rotated text begins (the bottom at 90, the top at −90 and 0). |
+| `over` | 'axes' | Span the title is aligned within: the axes, or the axes and the axis labels beside them (the y axis' on top and bottom, the x axis' on the left and right). |
+| `rotation` | 'auto' | `auto`: 0 on top and bottom, 90 on the left (reads upward), −90 on the right (reads downward); or 0, 90, −90. |
+| `pad` | 5.0 | Gap between the title and what it covers. Length; `%`: of the axes height. |
+| `order` | — | Place in its side's stack: lower is nearer; unset: the main title nearest, then the others in creation order. |
+| `rule` | False | A line along the span: `True` or `"inside"` between the title and what it covers, `"outside"` beyond the title, `False` none. |
+| `rule_color` | 'var(color)' | Color of the rule. |
+| `rule_width` | 'var(line_width)' | Thickness of the rule. Length. |
+| `rule_gap` | '0.5em' | Gap between the rule and the title. Length; `%`: of the font size. |
 | `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
 | `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
 | `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
 | `color` | 'var(text_color)' | Text color. |
-| `align` | 'center' | Alignment over the axes. |
-| `pad` | 5.0 | Gap above the axes. Length; `%`: of the axes height. |
-| `over` | 'axes' | Width the title is aligned within: the axes, or the axes and the y axis labels. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `TextStyle`, `Font`.
 <!-- /settings -->
@@ -720,14 +838,67 @@ candidate covers more than 2 % marked cells; else the candidate covering the few
 | `column_gap` | '1em' | Gap between columns. Length; `%`: of the font size. |
 | `title_gap` | '0.3em' | Gap below the title. Length; `%`: of the font size. |
 | `inner_pad` | 'auto' | Space inside the box; `"auto"`: 0.5em with a frame, 0.15em without. Length; `%`: of the font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `TextStyle`, `Stroke` (`frame_`), `Font`.
 <!-- /settings -->
 
+#### Figure legends
+
+```python
+fig.add_legend(plots=[a, b], side="right", **settings)   # returns it
+fig.add_legend()                                        # every plot, on the right
+fig.legends
+fig = pl.Figure(cols=2, share_legend="row")              # one legend per row
+```
+
+A figure legend shows the entries of a set of plots (plots or their series; default every
+plot) in one legend, in the lanes beside them as [figure titles](#figure-title) are: its
+plots' cells must fill the grid rectangle they span (a plot inside it but not given is an
+error naming it).
+
+* **Entries.** Its plots' entries, in plot order (row by row), then in series order.
+  Entries with the same label and the same symbol (what the legend draws for them: kind,
+  colors, marker, line style and width) are one entry; the same label with another
+  symbol keeps both. A size key whose series' plots the legend all covers goes into it
+  (the first such legend), one key per shared size axis as in a plot legend.
+* **Plot legends.** Its plots' legends lose those entries, and a plot left without
+  entries shows no legend. A plot whose `legend.position` is set keeps its legend whole
+  (the figure legend shows its entries too).
+* **Place.** `side` (`top`, `bottom`, `left`, `right`) and `align` along the side
+  (`start`, `center`, `end`) within the axes of its plots, kept within the figure; the
+  figure grows when the legend is longer than its content. On top and bottom, entries
+  are side by side in rows as wide as the span (unless `columns` is set); on the left and
+  right, in a column (`columns`).
+* **Lanes.** Legends and figure titles share the lanes and their rules (nesting, then
+  shared lanes for disjoint spans, then creation order; `order` overrides); over the same
+  plots, a legend is nearer the plots than a title. A legend without entries takes no
+  lane.
+* **`share_legend`** (`False`, `True`/`"all"`, `"row"`, `"col"`) makes figure legends for
+  the groups `share_color` would make (two plots or more): one on the right of the
+  figure (`"all"`), of each row (`"row"`), one at the bottom of each column (`"col"`).
+  A group with a plot an `add_legend` legend covers gets none. They take the
+  `FigureLegend` (and `Legend`) keys of the style, but their `side`.
+* `p.save()` (one plot alone) leaves out figure legends: the plot's legend shows all its
+  entries.
+
+Figure legends have the settings of plot legends but `position`, `orientation`, and:
+
+<!-- settings:FigureLegend -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `side` | 'right' | `top`, `bottom`, `left` or `right` of its plots. |
+| `align` | 'center' | Alignment along the side: `start` (left, or top), `center`, `end` (right, or bottom). |
+| `order` | — | Place in its side's lanes, as figure titles' `order`: lower is nearer the plots. |
+| `pad` | 5.0 | Gap between the legend and the plots. Length. |
+| `title` | 'auto' | Legend title; `"auto"`: the `group` column name of its plots' series, if any. |
+<!-- /settings -->
+
 ### Decorations
 
 Reference lines, bands, text and annotations. They take no palette color, are in the
@@ -755,7 +926,7 @@ HLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
 | `min` | '0%' | Start: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
 | `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
@@ -774,7 +945,7 @@ AxLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | 1.0 | Opacity. |
@@ -815,10 +986,12 @@ Text:
 | `coords` | 'data' | `data`, `axes` (0–1) or `figure` (0–1). |
 | `color` | 'var(text_color)' | Text color; default `text_color`. |
 | `font_size` | inherited (11.0) | Font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
 | `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
 | `text_color` | inherited ('black') | Text color. |
@@ -842,7 +1015,7 @@ Annotate:
 | `arrow` | True | Draw an arrow from the text to `xy`. |
 | `arrow_style` | '->' | `->` (open head), `-\|>` (filled head) or `-` (no head). |
 | `arrow_color` | 'var(color)' | Arrow color; default the text color. |
-| `arrow_width` | 0.75 | Arrow line width. Length. |
+| `arrow_width` | 0.5 | Arrow line width. Length. |
 | `head_length` | 7.0 | Arrowhead length. Length. |
 | `shrink` | 3.0 | Gap left at both ends of the arrow. Length. |
 
@@ -944,9 +1117,6 @@ grid only when its axis asks). `p.save` includes its twins.
 * `tick_format` takes any [number format](#number-formats); the default `"auto"` is the
   rule above.
 
-Category axes of heatmaps draw labels only (no axis line or ticks) unless `tick_length`
-or the plot's `spines` is set.
-
 * **Grid lines:** `grid` at the major ticks, `minor_grid` at the minor ticks (or halfway
   between major ticks on linear axes without minor ticks), and `zero_line` at 0 (when 0
   is within the limits), under the series.
@@ -990,19 +1160,19 @@ or the plot's `spines` is set.
 | `category_label_spacing` | ('1.6em', '1.3em') | Distance between category labels: rotated (horizontal axes) and stacked (vertical axes); labels closer than it are thinned out. Length; `em` and `%`: of `tick_label_font_size`. |
 | `auto_max_ticks` | (10, 8) | Most automatic ticks on numeric and time axes. |
 | `sci_limits` | (-4, 5) | Exponents beyond which labels become mantissas × 10ᵏ. |
-| `tick_length` | 5.0 | Tick length. Length; `%`: of the axes side across the axis. |
+| `tick_length` | 6.0 | Tick length. Length; `%`: of the axes side across the axis. |
 | `minor_tick_length` | '60%' | Minor tick length; default 0.6 × `tick_length`. Length; `%`: of `tick_length`. |
 | `tick_direction` | 'out' | `out`, `in` or `both`. |
 | `tick_color` | 'var(color)' | Tick color. |
-| `tick_width` | 0.75 | Tick line width. Length. |
+| `tick_width` | 0.5 | Tick line width. Length. |
 | `tick_label_font_size` | '1em' | Font size of tick labels. Length; `%`: of the font size. |
 | `tick_label_weight` | 'normal' | Tick label weight: `normal`, `bold` or 1–1000. |
 | `tick_label_color` | 'var(color)' | Tick label color. |
-| `tick_pad` | 3.0 | Gap between ticks and labels. Length; `%`: of the axes side across the axis. |
-| `label_pad` | 4.0 | Gap between tick labels and the label. Length; `%`: of the axes side across the axis. |
+| `tick_pad` | 5.0 | Gap between ticks and labels. Length; `%`: of the axes side across the axis. |
+| `label_pad` | 5.0 | Gap between tick labels and the label. Length; `%`: of the axes side across the axis. |
 | `color` | 'var(text_color)' | Color of the axis line, ticks and labels (the default of `line_color`, `tick_color`, `tick_label_color`, `label_color`). |
 | `line_color` | 'var(color)' | Axis line color. |
-| `line_width` | 0.75 | Axis line width. Length. |
+| `line_width` | 0.5 | Axis line width. Length. |
 | `side` | x: 'bottom' / y: 'left' | Where the ticks, labels and axis line go: `bottom` or `top` (x axis), `left` or `right` (y axis). |
 | `mirror` | False | Ticks also on the opposite side of the axes. |
 | `spine_offset` | 0.0 | Distance the axis line (with its ticks and labels) is moved away from the axes. Length; `%`: of the axes side across the axis. |
@@ -1022,10 +1192,12 @@ or the plot's `spines` is set.
 | `minor_grid_style` | 'var(grid_style)' | Minor grid style; default `grid_style`. Length. |
 | `visible` | True | Draw the axis (ticks, labels). |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `text_color` | inherited ('black') | Text color. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
@@ -1160,7 +1332,7 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | `size` | 4.5 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `edge_width` | 0.5 | Outline width; 0: no outline. Length. |
 | `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
@@ -1184,10 +1356,12 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Marker`, `Font`.
 <!-- /settings -->
@@ -1219,7 +1393,7 @@ gradient's middle color.
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Line color; default: the next palette color. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list; named styles scale with the width. Length. |
 | `cap` | 'butt' | Line cap. |
 | `join` | 'round' | Line join. |
@@ -1229,7 +1403,7 @@ gradient's middle color.
 | `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `marker_edge_width` | 0.5 | Outline width; 0: no outline. Length. |
 | `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
@@ -1247,10 +1421,12 @@ gradient's middle color.
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
@@ -1284,10 +1460,12 @@ each side in its color).
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
@@ -1315,7 +1493,7 @@ category.
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `edge_color` | 'series' | Box outline, whiskers, caps and median: a color, `"series"` (each box's own color) or `"auto"` (a grey 0.6 × as light as the series' lightest color, as seaborn). |
-| `edge_width` | 0.75 | Outline width. Length. |
+| `edge_width` | 0.5 | Outline width. Length. |
 | `whisker_color` | — | Whisker and cap color; default `edge_color`. |
 | `whisker_width` | 'var(edge_width)' | Whisker and cap width; default `edge_width`. Length. |
 | `whisker_style` | 'solid' | Whisker line style: `solid`, `dashed`, `dotted`, `dashdot` or a dash list (caps stay solid). Length. |
@@ -1349,10 +1527,12 @@ category.
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `Stroke` (`whisker_`), `Stroke` (`median_`), `FillStyle`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
@@ -1393,10 +1573,12 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1437,7 +1619,7 @@ pl.Bar(x, height=None, plot=None, **settings)
 | `saturation` | 1.0 | Saturation of the fills (seaborn: 0.75). |
 | `error` | — | Error bars at the bar ends: a value, a sequence, `(low, high)` or `ErrorBars`. |
 | `error_color` | '#333333' | Error bar color. |
-| `error_width` | 0.75 | Error bar line width. Length. |
+| `error_width` | 0.5 | Error bar line width. Length. |
 | `value_labels` | False | Value labels: `True`/`"outside"`, `"inside"`, `"center"`. Outside labels widen automatic limits so they fit in the axes; a label too large for its bar goes outside, or is left out on a stacked bar. |
 | `value_label_format` | 'auto' | Number format of the value labels. |
 | `name` | — | Legend entry; unset: not in the legend. |
@@ -1447,10 +1629,12 @@ pl.Bar(x, height=None, plot=None, **settings)
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1486,7 +1670,7 @@ pl.Hist(values, plot=None, **settings)
 | `edge_color` | — | Bar outline color; default none. |
 | `edge_width` | 0.0 | Bar outline width. Length. |
 | `line_color` | — | Step and outline color; default each set's color. |
-| `line_width` | inherited (0.75) | Step line width. Length. |
+| `line_width` | inherited (0.5) | Step line width. Length. |
 | `outline` | True | `bar` and `stepfilled` kinds: the outer outline of each set, in `line_color` (dodged bars: each bar's outline). |
 | `alpha` | 'auto' | Opacity; `"auto"`: 0.5 for overlaid sets, else the plot's. |
 | `saturation` | 1.0 | Saturation of the fills. |
@@ -1498,10 +1682,12 @@ pl.Hist(values, plot=None, **settings)
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1534,7 +1720,7 @@ A Gaussian kernel density of each set on a common grid of `points` points, exten
 | `orientation` | 'vertical' | `vertical` (values along x) or `horizontal`. |
 | `stack` | False | Stack the sets (seaborn's `multiple="stack"`). |
 | `color` | — | Color, or one per set; default palette colors. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | Line style. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
@@ -1543,10 +1729,12 @@ A Gaussian kernel density of each set on a common grid of `points` points, exten
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `FillStyle`, `Stroke`, `Font`.
 <!-- /settings -->
@@ -1596,7 +1784,7 @@ A step line through the sorted values of each set: `stat` `proportion`, `count`
 | `complementary` | False | Plot 1 − F (survival). |
 | `orientation` | 'vertical' | `vertical`: values along x; `horizontal`: along y. |
 | `color` | — | Line color, or one per set; default palette colors. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | Line style. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
@@ -1605,10 +1793,12 @@ A step line through the sorted values of each set: `stat` `proportion`, `count`
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke`, `Font`.
 <!-- /settings -->
@@ -1630,7 +1820,7 @@ pl.Violin(values, positions=None, plot=None, **settings)
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `edge_color` | 'series' | Outline and inner color: a color or `"series"` (each violin's own color, at `alpha`). |
-| `edge_width` | 0.75 | Outline width. Length. |
+| `edge_width` | 0.5 | Outline width. Length. |
 | `saturation` | 1.0 | Saturation of the fills. |
 | `alpha` | 1.0 | Opacity of the violins. |
 | `fill` | 0.25 | Fill: an opacity of each violin's color, times `alpha` (outlines keep `alpha`); `True` (opaque), a color, or `False`. |
@@ -1653,10 +1843,12 @@ pl.Violin(values, positions=None, plot=None, **settings)
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `FillStyle`, `Font`.
 <!-- /settings -->
@@ -1677,7 +1869,7 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `size` | 4.5 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `edge_width` | 0.5 | Outline width; 0: no outline. Length. |
 | `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
@@ -1706,10 +1898,12 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Marker`, `Font`.
 <!-- /settings -->
@@ -1740,10 +1934,12 @@ Layers (rows of `ys`, or a dict `{name: values}`, one legend entry each) stacked
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
@@ -1763,7 +1959,7 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 | `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `marker_edge_width` | 0.5 | Outline width; 0: no outline. Length. |
 | `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
@@ -1771,7 +1967,7 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `color` | — | Bar color; default: the next palette color. |
-| `line_width` | inherited (0.75) | Bar width. Length. |
+| `line_width` | inherited (0.5) | Bar width. Length. |
 | `cap_length` | 4.0 | Cap width (`data`: in data units across the bar); 0: no caps. Length; `d`: data units. |
 | `x_error` | — | Horizontal errors. |
 | `y_error` | — | Vertical errors. |
@@ -1785,10 +1981,12 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Marker` (`marker_`), `Font`.
 <!-- /settings -->
@@ -1816,10 +2014,10 @@ Stems from `baseline` to each value with a marker (lollipops), and a baseline li
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `color` | — | Stem and marker color; default: the next palette color. |
-| `line_width` | inherited (0.75) | Stem width. Length. |
+| `line_width` | inherited (0.5) | Stem width. Length. |
 | `baseline` | 0.0 | Value the stems start from. |
 | `baseline_color` | '#4d4d4d' | Baseline color; `none`: no baseline. |
-| `baseline_width` | 0.75 | Baseline width. Length. |
+| `baseline_width` | 0.5 | Baseline width. Length. |
 | `orientation` | 'vertical' | `vertical` stems (values on y) or `horizontal`. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
@@ -1828,10 +2026,12 @@ Stems from `baseline` to each value with a marker (lollipops), and a baseline li
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Marker` (`marker_`), `Stroke` (`baseline_`), `Font`.
 <!-- /settings -->
@@ -1863,7 +2063,7 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `marker_edge_width` | 0.5 | Outline width; 0: no outline. Length. |
 | `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
@@ -1878,10 +2078,12 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
@@ -1938,10 +2140,12 @@ the axes are not counted. Colored by `cmap`; a colorbar source.
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
@@ -1979,10 +2183,12 @@ Iso-lines (`lines`) and filled bands (`fill`) of a grid at nodes `x`/`y`. `level
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -2026,10 +2232,12 @@ Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a pl
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -2081,7 +2289,7 @@ fig = pl.Figure(cols=3, share_size="all")           # one size axis, one size ke
 * **`share_size`** does the same for the own size axes: limits over all the group's
   values, one `size_limits` (or `size_scale`) for the group, and one size key for the
   group ([legend](#legend)). Each series keeps its `size_map`. Facet figures share size
-  too (`"all"`).
+  too (`"all"`). A figure legend covering every plot of a key takes the key.
 * **Training.** Before the layout, each axis is resolved from the values it maps, by the
   code of x and y axes: the scale's domain, `limits` and quantiles, `include_zero`, no
   padding (unless `padding` is set). Values past the limits take the gradient's
@@ -2106,37 +2314,103 @@ Color and size axes have the settings of [axes](#4-axes); these differ:
 ### Colorbars
 
 ```python
-p.colorbar(source=None, **settings)          # attached to a side of the plot
-fig.colorbar(source, id=None, **settings)    # in its own grid area
-cb.axis                                      # the color axis shown
+p.colorbar(source=None, side="bottom", **settings)       # attached to a side of the plot
+fig.add_colorbar(source=None, plots=None, side="bottom", **settings)   # beside plots
+fig.colorbar(source, id=None, **settings)                # in its own grid area
+fig.colorbars                                            # those of add_colorbar
+cb.axis                                                  # the color axis shown
 ```
 
-`source` is a mapped series (its color axis; default: the plot's last mapped series) or
-a color axis. The bar draws the axis' gradient between its trained limits, with the
-axis' ticks, number format and fonts, and a label: `label`, else the axis' `label`, else
-the name of the color column or density. Attached bars take margin on their side, so axes
-stay aligned. A bar in its own area runs along the neighbouring axes (`align="axes"`) or
-boxes (`"borders"`). Axis settings given to a bar go to its axis:
+`source` is a mapped series (its color axis; default: the plot's last mapped series, or
+that of the first covered plot with one) or a color axis. A colorbar draws the axis'
+gradient between its trained limits, with a label: `label`, else the axis' `label`, else
+the name of the color column or density.
+
+* **Key** (`style="key"`, the default): one line of the low limit, a short bar with round
+  ends filled with the gradient (`thickness` 4 px, `length` 40 px), the high limit, then
+  the label; `value_gap` (0.6em) between a limit and the bar, `label_gap` (1.2em) before
+  the label. The texts are centered on the bar's middle line, in the axis' tick label font
+  (the label in its label font); `em` is the axis' tick label font size. When the limits
+  clip the data (`extend`), a dot as wide as the bar, in the gradient's under or over
+  color, sits half the thickness past that end (`extend_shape`: `dot`, `block`,
+  `triangle`). `frame` outlines the bar and the dots, following their shapes.
+* **Values.** `values="limits"`: the axis' limits in its `tick_format` (`"auto"`: rounded
+  to two digits of their range); `"ticks"`: the axis' ticks along the bar instead, under
+  it (right of a vertical one); `"signs"`: a bold − (always U+2212, whatever `minus`) and
+  a bold +; or a pair of texts with markup, `("Low", "High")`, `None` keeping that end's
+  number: `(None, "max")`.
+* **Vertical** (on the left and right): the high limit above the bar, the low limit below
+  it, the label above everything, horizontal, all centered on the bar.
+  `label_position`: `end` (after the high end; above a vertical key), `start` (before
+  the low end; below a vertical key), `top` (above the key), `side` (under a horizontal
+  key; beside a vertical one, reading upward).
+* **Bar** (`style="bar"`): a long bar (`length` `100%`, `thickness` 13 px) with the axis'
+  ticks, tick labels and label beside it, for many ticks (log scales, diverging maps).
+  `values`, the gaps and `label_position` are a key's.
+* **Attached.** A band of the plot's box on its `side` (default `bottom`;
+  `orientation="auto"`: horizontal on top and bottom, vertical on the left and right),
+  placed along the side by `align` (`"auto"`: the end on top and bottom, the center on
+  the left and right). On one side, from the axes outward: an outside legend, the
+  colorbars (by `order`, else in creation order), the titles. A key longer than its axes
+  side passes its ends, and the margins there grow.
+* **Lanes.** `fig.add_colorbar` puts a colorbar beside a set of plots (plots or their
+  series; default every plot) in the lanes of [figure titles](#figure-title) and
+  [legends](#figure-legends), with their rules (the plots' grid rectangle, nesting, shared
+  lanes for disjoint spans, creation order, `order`); over the same plots, a legend is
+  nearer the plots, then a colorbar, then a title. `align` (default `center`) places it
+  within the axes of its plots. A `%` `length` is of that span, and a key then fills
+  that part of it (`length="100%"`: the bar takes what the texts leave of the span). The
+  covered plots' attached colorbars of the same axis are left out.
+* **Shared color axes.** When plots sharing a color axis have attached colorbars of it,
+  one colorbar in the lanes replaces them: per group of `share_color`, on the right of a
+  row or of the figure, at the bottom of a column; then per axis that the attached
+  colorbars of two plots or more show (`fig.color_axis()`), at the bottom of a column,
+  else on the right. It takes the settings of the first one but its place. An attached
+  colorbar whose `side` is set stays, as do those of plots that are not a grid
+  rectangle.
+* **Own area.** `fig.colorbar(source, id=…)` is vertical in its grid area (`orientation`):
+  a key placed along it by `align`, a bar running along the neighbouring axes
+  (`align="axes"`) or boxes (`"borders"`).
+* `p.save()` (one plot alone) leaves out figure colorbars: the plot's attached colorbars
+  show again.
+
+Axis settings given to a colorbar go to its axis:
 `p.colorbar(h, label="z", tick_format="{:.0%}")` sets `h.color_axis`'s tick format.
 
 <!-- settings:Colorbar -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `position` | 'right' | Side of the plot an attached bar takes. |
-| `orientation` | 'auto' | Bar direction; `"auto"`: vertical, or horizontal for bars attached at the top or bottom. |
-| `thickness` | 13.0 | Bar thickness (`%` of the attached axes side across it). Length; `%`: of the axes side across the colorbar. |
-| `length` | '100%' | Bar length as a fraction of the axes side (attached bars). Length; `%`: of the axes side along the colorbar. |
-| `pad` | 11.0 | Gap between the axes and an attached bar. Length; `%`: of the axes side across the colorbar. |
-| `label` | — | Bar label: a string or rich content; default: the axis' `label`, else the name of the color column or density. |
+| `side` | 'bottom' | Side of the plot (or of the plots) it sits on. |
+| `align` | 'center' | Place along its side: `start` (left, or top), `center`, `end` (right, or bottom). |
+| `order` | — | Place among the colorbars of its side: lower is nearer the axes; unset: creation order. |
+| `style` | 'key' | `key`: one line of the limits around a short bar with round ends, then the label; `bar`: a long bar with the axis' ticks. |
+| `orientation` | 'auto' | Direction; `"auto"`: horizontal on top and bottom, vertical on the left and right and in an area of its own. |
+| `thickness` | 'auto' | Bar thickness; `"auto"`: 4 px on a key, 13 px on a bar. Length; `%`: of the span along a key, the axes side across a bar. |
+| `length` | 'auto' | Bar length; `"auto"`: 40 px on a key, `100%` on a bar. A key given in `%` fills that part of the span with its texts and bar. Length; `%`: of the span along the colorbar (the axes side of an attached one). |
+| `values` | 'limits' | A key's end texts: `limits` (the axis' limits in its `tick_format`), `ticks` (the axis' ticks along the bar, lengthened to show at least two), `signs` (a bold − and +) or a pair of texts (`None`: that end's number). |
+| `value_gap` | '0.6em' | Gap between a key's end texts and its bar (and above or below a label on top or under it). Length; `%`: of the font size. |
+| `label_gap` | '1.2em' | Gap between a key's texts and its label, along the key. Length; `%`: of the font size. |
+| `label_position` | 'end' | A key's label: after the high end (`end`; above a vertical key), before the low end (`start`; below a vertical key), beside the bar (`side`: under a horizontal key, rotated right of a vertical one) or above the key (`top`). |
+| `pad` | 'auto' | Gap between the axes and an attached colorbar; `"auto"`: 0.8em on a key, 11 px on a bar. Length; `%`: of the axes side across the colorbar. |
+| `label` | — | Label: a string or rich content; default: the axis' `label`, else the name of the color column or density. |
 | `extend` | 'auto' | Ends in the under/over colors: `auto` shows them when the limits clip the data. |
-| `extend_shape` | 'block' | `block`: a separate block at the end of the bar, within its length; `triangle`: a triangle past the bar's end. |
-| `frame` | False | Outline the bar. |
+| `extend_shape` | 'auto' | `dot`: a dot past the key's end; `block`: a separate block at the end (within a bar's length); `triangle`: a triangle past the end; `"auto"`: `dot` on a key, `block` on a bar. |
+| `frame` | False | Outline the bar (and its ends), following its shape. |
 | `frame_color` | '#666666' | Outline color. |
 | `frame_width` | 0.5 | Outline width. Length. |
 
 Groups: `Stroke` (`frame_`).
 <!-- /settings -->
 
+Figure colorbars (`fig.add_colorbar`) have the settings of colorbars, and:
+
+<!-- settings:FigureColorbar -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `order` | — | Place in its side's lanes, as figure titles' `order`: lower is nearer the plots. |
+| `pad` | 'auto' | Gap between the colorbar and the plots; `"auto"`: 0.8em on a key, 11 px on a bar. Length. |
+<!-- /settings -->
+
 ## 7. Colors, maps and markers
 
 ### Colors and palette
@@ -2360,7 +2634,7 @@ for vec_io's `draw_markers`; `plot_io.markers.marker_area(name)` its area.
 ## 8. Output
 
 ```python
-fig.save(path, **options)          # .pdf, .png, .jpg/.jpeg, .jxl, .avif
+fig.save(path, **options)          # .pdf, .eps, .png, .jpg/.jpeg, .jxl, .avif
 fig.to_bytes(format="pdf", **options)
 fig.draw(canvas, x=0, y=0)         # on any vec_io canvas (its document's fonts); returns (width, height) in px
 fig.size()                         # (width, height) in px
@@ -2374,13 +2648,18 @@ it with its own options:
 |---|---|
 | `title`, `author`, `subject`, `keywords`, `creator`, `creation_date`, `pdf_a`, `color_mode`, `ink_limit`, `icc_profile`, `base_dir` | the document (vec_io `Document`) |
 | `font_dirs`, `system_fonts` | the fonts text is shaped and embedded with ([fonts](#1-conventions)) |
+| `text_as_paths` | text drawn as the outlines of its glyphs: no font embedded, text not selectable (default `False`) |
 | `quality` | the figure's `quality` when not given: 1–100, `"lossless"` (not JPEG) or `"auto"`, the default: PNG 90, a palette of at most 256 colors; JPEG 90; JPEG XL, AVIF and rasterized content in a PDF lossless |
 | `compression` | `"fast"`, `"balanced"` (default), `"best"`: the encoder's effort (PDF streams and images, PNG, JPEG, JPEG XL, AVIF) |
 | `simplify` | the output's `simplify` for content without its own (series have theirs, below) |
-| `compress`, `font_hinting` | PDF: compressed streams (default) or a readable file; TrueType hinting kept in embedded subsets (default: left out) |
-| `dpi`, `background` | images: resolution (default 192: two image pixels per px); a color under the figure (default the figure's, white; `None` is transparent, white in JPEG) |
-
-JPEG XL output (`.jxl`) needs libjxl, AVIF output (`.avif`) libavif 1.x. Images inside a
+| `compress`, `font_hinting` | PDF and EPS: compressed streams (default) or a readable file; TrueType hinting kept in embedded subsets (default: left out) |
+| `flatten_transparency`, `flatten_fallback`, `flatten_dpi`, `flatten_budget`, `flatten_cell` | PDF: translucent content drawn as opaque vectors (default off), and what cannot be (vec_io's transparency flattening: an image by default); EPS: always flattened, the others tune it |
+| `dpi`, `background` | images: resolution (default 384: four image pixels per px); a color under the figure (default the figure's, white; `None` is transparent, white in JPEG) |
+
+EPS output (`.eps`) is vec_io's: one page of PostScript Level 3, its transparency (the
+`alpha` of bands, markers, …) flattened into opaque shapes, with an image where it cannot
+be (dense translucent scatters), and its fonts embedded (Type 42 or CFF). JPEG XL output
+(`.jxl`) needs libjxl, AVIF output (`.avif`) libavif 1.x. Images inside a
 PDF (rasterized series, heatmaps) are stored losslessly or as JPEG (`quality`), never as
 JPEG XL, so every PDF reader shows them. Fonts are embedded subsets without hinting: a
 typical figure's text adds a few KB per face. A plot
@@ -2534,8 +2813,8 @@ readers, recognised by their `type` attribute (`"bigwig"`, `"bigbed"`, `"bed"`,
 | Data | Methods called |
 |---|---|
 | signal (bigWig; the coverage of bigBed, BED and peaks readers) | `read_values([(chr, start, end)], bin_count=n, bin_mode=…, def_value=…, zoom="auto")`, or with `bin_size=b, snap_to_grid="expand"` and the row's bounds from `resolve_regions([(chr, start, end)], bin_size=b, snap_to_grid="expand")` (without it, `snap_to_grid=False, full_bin=True`): one row of values |
-| intervals (bigBed, BED, peaks) | `read_entries([(chr, start, end)], as_cols=True, col_count=…)`: a dict (or a list of one dict) of columns; `col_count` from `auto_sql` when the reader has it |
-| annotation (GTF, GFF3) | `read_transcripts([(chr, start, end)], as_cols=True, gene_type=…, transcript_type=…)`: a dict (or a list of one dict) of transcript columns: `start`, `end`, `strand`, `transcript_id`, `transcript_name`, `gene_id`, `gene_name`, `cds_start`, `cds_end` (−1 when non-coding), `exon_starts`, `exon_ends`, `exon_offsets` |
+| intervals (bigBed, BED, peaks) | `read_entries([(chr, start, end)], columns=…)`: a table, a dict of columns; `columns` from `auto_sql` when the reader has it |
+| annotation (GTF, GFF3) | `read_entries([(chr, start, end)], model="transcript", gene_type=…, transcript_type=…)`: a table of transcripts: `start`, `end`, `strand`, `transcript_id`, `transcript_name`, `gene_id`, `gene_name`, `cds_start`, `cds_end` (−1 when non-coding); their exons are the table `nested["exons"]` (`start`, `end`), transcript `i`'s at rows `groups[i]:groups[i + 1]`. A reader is told for one by its `tss` method |
 | contacts (Hi-C) | `bin_sizes`, `normalizations`, `read_values((chr, start, end), bin_size=b, snap_to_grid="expand", normalization=…, matrix_type=…, max_distance=…)` (or `bin_count=n` instead of the first two): a square matrix; bounds from `resolve_regions((chr, start, end), bin_size=b, snap_to_grid="expand")["rows"]` |
 
 Results are read as buffers (numpy arrays included) without importing numpy. A path
@@ -2585,13 +2864,15 @@ t.bigwig(pax7_reader, name="Pax7", color="rose")
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `FillStyle`, `Font`.
 <!-- /settings -->
@@ -2643,13 +2924,15 @@ every feature has the same lightness.
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `FillStyle`, `TextStyle` (`name_`), `Font`.
 <!-- /settings -->
@@ -2734,10 +3017,12 @@ to quantiles of the cells drawn (`color_limits="q:0.01/q:0.99"`), on a log scale
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Font`.
 <!-- /settings -->
@@ -2777,9 +3062,11 @@ pl.styles.settings("house")            # the resolved dict (base theme included)
 ```
 
 * **Keys.** Names of inherited settings (`"font_size"`, `"palette"`), `"Class.name"` for
-  any setting of a class and its subclasses (`Figure`, `FigureTitle`, `Plot`, `Title`,
-  `Legend`, `Axis` (plot, color and size axes), `Colorbar`, every series class, `Series` for
-  all of them, every decoration class, `Decoration` for all of them, the genome classes),
+  any setting of a class and its subclasses (`Figure`, `FigureTitle`, `MainTitle`, `Plot`, `Title`,
+  `Legend`, `FigureLegend`, `Axis` (plot, color and size axes), `Colorbar`,
+  `FigureColorbar`, every series class, `Series` for all of them, every decoration class,
+  `Decoration` for all of them, `FigureVLine`, `FigureVSpan`, `FigureGroup`, the genome
+  classes),
   or `"Group.member"` for every embedding of a group member (`"Marker.size"`,
   `"Stroke.line_width"`, `"TextStyle.font_weight"`).
   `"Colorbar.<axis setting>"` (`"Colorbar.tick_direction"`, `"Colorbar.tick_color"`, …)
@@ -2843,7 +3130,7 @@ documented default properties. What cannot be expressed: legend titles naming a
 `use_style`), `plot_io.genome` (`parse_region`, `Region`), `plot_io.markers`
 (`marker_path`, `marker_area`), `plot_io.color.palettes` (`PALETTE`), and the modules of
 the types calls return: `plot_io.facets` (`FacetSet`, `LayerSet`), `plot_io.tables`
-(`SeriesGroup`), `plot_io.colorbar` (`Colorbar`). The others are internal: their names
+(`SeriesGroup`), `plot_io.colorbar` (`Colorbar`, `FigureColorbar`). The others are internal: their names
 may change in any release.
 
 | Module | Role |
@@ -2853,7 +3140,8 @@ may change in any release.
 | `defaults.py`, `units.py` | `DEFAULTS`; units, `var()`/`calc()`/`inherit`, `%` referents, `explain` traces |
 | `spec.py` | a render's specs (the model resolved once, frozen), layout boxes, palette colors and trained color and size axes |
 | `figure.py`, `plot.py` | `Figure` (arrangement, tracks layout, figure axes, sizes, output), `Plot`, `Title`, `Legend` |
-| `rows.py` | row labels in a band left of the plots, groups of rows (`FigureGroup`), lines and bands through rows (`FigureVLine`, `FigureVSpan`) |
+| `titles.py`, `markup.py` | the settings plot and figure titles share (`TitleBase`) and a title's text block; markup in strings read into spans |
+| `rows.py` | row labels in a band left of the plots, groups of rows (`FigureGroup`: letters, labels as figure titles), lines and bands through rows (`FigureVLine`, `FigureVSpan`) |
 | `axis.py`, `scales.py`, `limits.py`, `ticks.py` | axes, scale functions, limits syntax, tick choice and labels |
 | `states.py` | the render's state of each plot: calls, palette, axes and their limits, legend, colorbars |
 | `layout.py`, `geometry.py` | the box model: bands measured around each plot's axes, the grid solved in rounds, the frozen geometry (`layout.layout(fig, fonts)`: text shaped with a font database, no canvas) |