Docs for palettes and aes (#108)

Author: thomasp85

doc/_quarto.yml

@@ -85,13 +85,14 @@ website:
           - section: Types
             contents:
               - auto: syntax/scale/type/*
-          - section: Palettes
+          - section: Aesthetics
             contents:
-              - auto: syntax/scale/palette/*
+              - auto: syntax/scale/aesthetic/*
 
 
 format:
   html:
+    lightbox: auto
     syntax-definitions:
       - ggsql.xml
     theme:

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

@@ -0,0 +1,25 @@
+---
+title: "Position"
+---
+
+Position aesthetics (`x` and `y`, plus all their variants) relate data to placement in the coordinate system of the plot. All layers need at least one of each positional aesthetic mapped in order to show its data. However, the layer may compute positional aesthetics from the mapping. For example, a bar plot calculates the `y` aesthetic by counting the number of records in each group.
+
+## Literal values
+Scales for position aesthetics never use an output range and always relate to the input range. This is a practical decision by ggsql because different writers may treat the positional aesthetic in different ways. ^[In reality one could easily think of positional literal values as either normalized position along the x or y axis, or absolute units of distance from the bottom left corner of the coordinate system.]
+
+::: {.callout-note}
+The lack of true literal values in position means that it is currently hard to place data and annotation "in-between" breaks in a discrete position scale.
+:::
+
+## Aesthetic families
+Positional aesthetics consist of two families: The `x` and `y` family. Each of these consist of their primary aesthetic along with a range of sub aesthetic defined by their suffix:
+
+* `2`
+* `end`
+* `min`
+* `max`
+
+Which version of aesthetic to use depends on the layer, but all aesthetics within a family is scaled by the same scale, which is named after its primary aesthetic. This means that even when rendering a layer that only uses `xmin` and `xmax`, you will still scale it by writing `SCALE x ...` and label it by writing `LABEL x => ...`
+
+## Coordinate system
+Another thing that makes positional aesthetics different from other aesthetic is that they are dependent on a coordinate system which takes position scales and defines how values should be converted to a location on a plane. The default Cartesian coordinate system does what is generally expected: it places points along two perpendicular axes in a 2D plane. Other systems such as polar coordinates may dramatically change the look of a layer, transforming both the straightness of lines and positional relation of data.

doc/syntax/scale/aesthetic/1_color.qmd

@@ -0,0 +1,19 @@
+---
+title: Opacity
+---
+
+The `opacity` aesthetic governs how opaque objects are (or, conversely, how transparent they are). Depending on the layer it controls the opacity of the fill *or* stroke (if a layer has a natural fill then that is what receives the opacity). Opacity goes from 0 (fully transparent) to 1 (fully opaque). 
+
+Color values (fill or stroke aesthetics) may contain opacity information embedded, e.g. by using hex values with an alpha channel. How such colors are merged with the opacity aesthetic is writer-dependent and can't be relied on. Even if the behavior was consistent, mixing the two is never a good idea because it leads to hard-to-decode graphics.
+
+## Literal values
+Opacity has no unit and goes from 0 (fully transparent) to 1 (fully opaque). You can set the opacity of points to a low value to combat overplotting like so:
+
+```ggsql
+DRAW point
+    SETTING opacity => 0.2
+```
+
+## Palettes
+Opacity can only be used for sequential data and has no named palettes. The default for continuous, binned, and ordinal scales is to use the range from 0.1 to 1 and interpolate between them. This can be overwritten by providing a manual output range specification like below where we use the complete range opacity
+