diff --git a/README.md b/README.md index 74b6a0d..2b49753 100644 --- a/README.md +++ b/README.md @@ -299,7 +299,7 @@ _Substitution Keys_ can be considered or thought of in two ways. They are the ke The second way of thinking about substitution keys is that they are the starting values of keys in templates. So, they represent parameterized values of keys in templates. -As an example consider the following. In a template (which is a Clojure map) we might have a key `:field` with value `:X`. Here `:field` could correspond to a Vega-Lite field name, in this case "field". When we apply `hc/xform` to the template, `:field`'s value `:X` will be replaced by a new value, which comes from the current substitution map. In the default substitution map `hc/_defaults`, the key `:X` has the value of "x", so the resulting key/value pair will be `:field "x"`. +As an example consider the following. In a template (which is a Clojure map) we might have a key `:field` with value `:X` (cf. [xy-encoding template](https://github.com/jsa-aerial/hanami/blob/0dd9ac62e89ec5a5d0285cd0c0da5e2bc87b2ad0/src/cljc/aerial/hanami/templates.cljc#L84). Here `:field` corresponds to a Vega-Lite key, ["field"](https://vega.github.io/vega-lite/docs/field.html)). When we apply `hc/xform` to the template, `:field`'s value `:X` will be replaced by a new value, which comes from the current substitution map. In the default substitution map [`hc/_defaults`](https://github.com/jsa-aerial/hanami/blob/9cfa38118486fa0e139defeaa20ac3595690c8f9/src/cljc/aerial/hanami/common.cljc#L161), the key `:X` has the value of `"x"`, so the resulting key/value pair will be `:field "x"`. A more complex example would be the field and value `:encoding :ENCODING` in the predefined subcomponent `ht/view-base` which lays out the structure of a Vega-Lite _view_. As before `:ENCODING` will be replaced during transformation by the value of `:ENCODING` in the substitution map. However, the default value of `:ENCODING` is the predefined subcomponent `ht/xy-encoding`. This value is a map describing the structure of a view's `x-y` encodings and contains many fields with their own substitution keys. So, to produce a final value, `ht/xy-encoding` is recursively transformed so that the final value of `:encoding` is a fully realized `x-y` encoding for the view being processed. `ht/view-base` has several other such fields and is itself recursively transformed in the context of the current substitution map. And its final value will be the base of a chart, such as a line chart (`ht/line-chart`) or area chart (`ht/area-chart`), or some new plot/chart/layout/etc of your own for some domain specific application.