refactor documentation

docs/config-transformations.md

@@ -0,0 +1,100 @@
+# Transformations entry
+
+For examples of transformation uses, see:
+
+* [Handle compressed directories](howto/store-compressed-directories.md)
+* [Handle secrets](howto/sensitive-dotfiles.md)
+
+**Notes**:
+
+* Any transformation with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords, for example.
+* Make sure to quote your transformations to avoid bad surprises
+* Transformations are executed using the default shell (`$SHELL`)
+* To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
+
+There are two types of transformations available:
+
+* **Read transformations**: used to transform dotfiles before they are installed ([config](config-config.md) key `trans_read`)
+    * Used for commands `install` and `compare`
+    * They have two arguments:
+        * **{0}** will be replaced with the dotfile to process
+        * **{1}** will be replaced with a temporary file to store the result of the transformation
+    * This Happens **before** the dotfile is templated (see [templating](templating.md))
+
+* **Write transformations**: used to transform files before updating a dotfile ([config](config-config.md) key `trans_write`)
+    * Used for command `update`
+    * They have two arguments:
+        * **{0}** will be replaced with the file path to update the dotfile with
+        * **{1}** will be replaced with a temporary file to store the result of the transformation
+
+A typical use-case for transformations is when dotfiles need to be
+stored encrypted or compressed. For more, see [the howto](howto/howto.md).
+
+Note that transformations cannot be used if the dotfile is to be linked (when `link: link` or `link: link_children`).
+
+Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations themselves as well as their arguments can also be templated.
+
+For example:
+```yaml
+trans_read:
+  targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
+dotfiles:
+  f_abc:
+    dst: /tmp/abc
+    src: abc
+    trans_read: targ "{{@@ profile @@}}" lastarg
+profiles:
+  p1:
+    dotfiles:
+    - f_abc
+```
+
+will result in `abc; f_abc; p1; lastarg`.
+
+## trans_read entry
+
+The **trans_read** entry (optional) contains a transformations mapping (See [transformations](config-transformations.md)).
+
+```yaml
+trans_read:
+   <trans-key>: <command-to-execute>
+```
+
+## trans_write entry
+
+The **trans_write** entry (optional) contains a write transformations mapping (See [transformations](config-transformations.md)).
+
+```yaml
+trans_write:
+   <trans-key>: <command-to-execute>
+```
+
+## Dynamic transformations
+
+As for [dynamic actions](config-actions.md#dynamic-actions), transformations support
+the use of variables ([variables and dynvariables](config-file.md#variables)
+and [template variables](templating.md#template-variables)).
+
+A very dumb example:
+```yaml
+trans_read:
+  r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1}
+  r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1}
+trans_write:
+  w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1}
+  w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1}
+variables:
+  r_var: readvar
+  w_var: writevar
+dotfiles:
+  f_abc:
+    dst: ${tmpd}/abc
+    src: abc
+    trans_read: r_echo_abs_src
+    trans_write: w_echo_key
+  f_def:
+    dst: ${tmpd}/def
+    src: def
+    trans_read: r_echo_var
+    trans_write: w_echo_var
+```