doc update structure

docs/README.md

@@ -1,4 +1,4 @@
-# Dotdrop documentation
+# Dotdrop
 
 [Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways of managing your dotfiles.
 It is especially powerful when it comes to managing those across different hosts.

docs/config-details.md

@@ -0,0 +1,530 @@
+# Config details
+
+## Entry actions
+
+**Note**: any action 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.
+
+Four types of actions can be defined:
+
+* [Dotfiles actions](#dotfile-actions)
+* [Default actions](#default-actions)
+* [Profile actions](#profile-actions)
+* [Fake dotfiles and actions](#fake-dotfile-and-actions)
+
+### Dotfile actions
+
+It is sometimes useful to execute some kind of action
+when deploying a dotfile.
+
+Note that dotfile actions are only
+executed when the dotfile is installed.
+
+For example let's consider
+[Vundle](https://github.com/VundleVim/Vundle.vim) is used
+to manage vim's plugins, the following action could
+be set to update and install the plugins when `vimrc` is
+deployed:
+
+```yaml
+actions:
+  vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall
+config:
+  backup: true
+  create: true
+  dotpath: dotfiles
+dotfiles:
+  f_vimrc:
+    dst: ~/.vimrc
+    src: vimrc
+    actions:
+      - vundle
+profiles:
+  home:
+    dotfiles:
+    - f_vimrc
+```
+
+Thus when `f_vimrc` is installed, the command
+`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
+be executed.
+
+Sometimes, you may even want to execute some action prior to deploying a dotfile.
+Let's take another example with
+[vim-plug](https://github.com/junegunn/vim-plug):
+
+```yaml
+actions:
+  pre:
+    vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl
+      -fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim)
+  vim-plug: vim +PlugInstall +qall
+config:
+  backup: true
+  create: true
+  dotpath: dotfiles
+dotfiles:
+  f_vimrc:
+    dst: ~/.vimrc
+    src: vimrc
+    actions:
+       - vim-plug-install
+       - vim-plug
+profiles:
+  home:
+    dotfiles:
+    - f_vimrc
+```
+
+This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug)
+is installed prior to deploying the `~/.vimrc` dotfile.
+
+You can also define `post` actions like this:
+
+```yaml
+actions:
+  post:
+    some-action: echo "Hello, World!" >/tmp/log
+```
+
+If you don't specify neither `post` nor `pre`, the action will be executed
+after the dotfile deployment (which is equivalent to `post`).
+Actions cannot obviously be named `pre` or `post`.
+
+Actions can even be parameterized. For example:
+```yaml
+actions:
+  echoaction: echo '{0}' > {1}
+config:
+  backup: true
+  create: true
+  dotpath: dotfiles
+dotfiles:
+  f_vimrc:
+    dst: ~/.vimrc
+    src: vimrc
+    actions:
+      - echoaction "vim installed" /tmp/mydotdrop.log
+  f_xinitrc:
+    dst: ~/.xinitrc
+    src: xinitrc
+    actions:
+      - echoaction "xinitrc installed" /tmp/myotherlog.log
+profiles:
+  home:
+    dotfiles:
+    - f_vimrc
+    - f_xinitrc
+```
+
+The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when
+vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'`
+when xinitrc is installed.
+
+### Default actions
+
+Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (*pre* or *post*).
+
+For example, the below action will log each dotfile installation to a file.
+
+```yaml
+actions:
+  post:
+    loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}"
+config:
+  backup: true
+  create: true
+  dotpath: dotfiles
+  default_actions:
+  - loginstall "/tmp/dotdrop-installation.log"
+dotfiles:
+  f_vimrc:
+    dst: ~/.vimrc
+    src: vimrc
+profiles:
+  hostname:
+    dotfiles:
+    - f_vimrc
+```
+
+### Profile actions
+
+Profile can be either `pre` or `post` actions. Those are executed before
+any dotfile installation (for `pre`) and after all dotfiles installation (for `post`)
+only if at least one dotfile has been installed.
+
+### Fake dotfile and actions
+
+*Fake* dotfile can be created by specifying no `dst` and no `src` (see [config format](config-format.md)).
+By binding an action to such a *fake* dotfile, you make sure the action is always executed since
+*fake* dotfile are always considered installed.
+
+```yaml
+actions:
+  always_action: 'date > ~/.dotdrop.log'
+dotfiles:
+  fake:
+    src:
+    dst:
+    actions:
+    - always_action
+```
+
+## Entry transformations
+
+For examples of transformation uses, see
+
+* [Store compressed directories](howto/store-compressed-directories.md)
+* [Sensitive dotfiles](howto/sensitive-dotfiles.md)
+
+**Note**: 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.
+
+There are two types of transformations available:
+
+* **read transformations**: used to transform dotfiles before they are installed ([format](config-format.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
+    * Happens **before** the dotfile is templated with jinja2 (see [templating](templating.md))
+
+* **write transformations**: used to transform files before updating a dotfile ([format](config-format.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/README.md).
+
+Note that transformations cannot be used if the dotfiles 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 itself as well as its 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`
+
+## Entry variables
+
+Variables defined in the `variables` entry are made available within the config file.
+
+Config variables are recursively evaluated what means that
+a config like the below
+```yaml
+variables:
+  var1: "var1"
+  var2: "{{@@ var1 @@}} var2"
+  var3: "{{@@ var2 @@}} var3"
+  var4: "{{@@ dvar4 @@}}"
+dynvariables:
+  dvar1: "echo dvar1"
+  dvar2: "{{@@ dvar1 @@}} dvar2"
+  dvar3: "{{@@ dvar2 @@}} dvar3"
+  dvar4: "echo {{@@ var3 @@}}"
+```
+
+will result in the following available variables:
+
+* var1: `var1`
+* var2: `var1 var2`
+* var3: `var1 var2 var3`
+* var4: `echo var1 var2 var3`
+* dvar1: `dvar1`
+* dvar2: `dvar1 dvar2`
+* dvar3: `dvar1 dvar2 dvar3`
+* dvar4: `var1 var2 var3`
+
+## Entry dynvariables
+
+It is also possible to have *dynamic* variables in the sense that their
+content will be interpreted by the shell before being substituted.
+
+These need to be defined in the config file under the entry `dynvariables`.
+
+For example:
+```yaml
+dynvariables:
+  dvar1: head -1 /proc/meminfo
+  dvar2: "echo 'this is some test' | rev | tr ' ' ','"
+  dvar3: /tmp/my_shell_script.sh
+  user: "echo $USER"
+  config_file: test -f "{{@@ user_config @@}}" && echo "{{@@ user_config @@}}" || echo "{{@@ dfl_config @@}}"
+variables:
+  user_config: "profile_{{@@ user @@}}_uid.yaml"
+  dfl_config: "profile_default.yaml"
+```
+
+They have the same properties as [Variables](config.md#variables).
+
+## Entry profile variables
+
+Profile variables will take precedence over globally defined variables.
+This means that you could do something like this:
+```yaml
+variables:
+  git_email: home@email.com
+dotfiles:
+  f_gitconfig:
+    dst: ~/.gitconfig
+    src: gitconfig
+profiles:
+  work:
+    dotfiles:
+    - f_gitconfig
+    variables:
+      git_email: work@email.com
+  private:
+    dotfiles:
+    - f_gitconfig
+```
+
+## Entry profile include
+
+If one profile is using the entire set of another profile, one can use
+the `include` entry to avoid redundancy.
+
+Note that everything from the included profile is made available
+(actions, variables/dynvariables, etc).
+
+For example:
+```yaml
+profiles:
+  host1:
+    dotfiles:
+      - f_xinitrc
+    include:
+      - host2
+  host2:
+    dotfiles:
+      - f_vimrc
+```
+Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
+
+For more advanced use-cases variables
+([variables](config.md#variables) and [dynvariables](#entry-dynvariables))
+can be used to specify the profile to include in a profile
+
+For example:
+```yaml
+variables:
+  var1: "john"
+dynvariables:
+  d_user: "echo $USER"
+profiles:
+  profile_john:
+    dotfiles:
+    - f_john_dotfile
+  profile_bill:
+    dotfiles:
+    - f_bill_dotfile
+  p1:
+    include:
+    - "profile_{{@@ d_user @@}}"
+  p2:
+    include:
+    - "profile_{{@@ var1 @@}}"
+```
+
+## Entry profile import
+
+Profile's dotfiles list can be loaded from external files
+by specifying their paths in the config entry `import` under the specific profile.
+
+The paths can be absolute or relative to the config file location.
+
+`config.yaml`
+```yaml
+dotfiles:
+  f_abc:
+    dst: ~/.abc
+    src: abc
+  f_def:
+    dst: ~/.def
+    src: def
+  f_xyz:
+    dst: ~/.xyz
+    src: xyz
+profiles:
+  p1:
+    dotfiles:
+    - f_abc
+    import:
+    - somedotfiles.yaml
+```
+
+`somedotfiles.yaml`
+```
+dotfiles:
+  - f_def
+  - f_xyz
+```
+
+Variables can be used in `import` and would allow to do something like
+```yaml
+import:
+- profiles.d/{{@@ profile @@}}.yaml
+```
+
+## Entry import_variables
+
+It is possible to load variables/dynvariables from external files by providing their
+paths in the config entry `import_variables`.
+
+The paths can be absolute or relative to the config file location.
+
+`config.yaml`
+```yaml
+config:
+  backup: true
+  create: true
+  dotpath: dotfiles
+  import_variables:
+  - variables.d/myvars.yaml
+```
+
+`variables.d/myvars.yaml`
+```yaml
+variables:
+  var1: "extvar1"
+dynvariables:
+  dvar1: "echo extdvar1"
+```
+
+Dotdrop will fail if an imported path points to a non-existing file.
+It is possible to make non-existing paths not fatal by appending the path with `:optional`
+```yaml
+import_variables:
+- variables.d/myvars.yaml:optional
+```
+
+## Entry import_actions
+
+It is possible to load actions from external files by providing their
+paths in the config entry `import_actions`.
+
+The paths can be absolute or relative to the config file location.
+
+`config.yaml`
+```yaml
+config:
+  backup: true
+  create: true
+  dotpath: dotfiles
+  import_actions:
+  - actions.d/myactions.yaml
+dotfiles:
+  f_abc:
+    dst: ~/.abc
+    src: abc
+    actions:
+      - dateme
+```
+
+`actions.d/myactions.yaml`
+```yaml
+actions:
+  dateme: date > /tmp/timestamp
+```
+
+External variables will take precedence over variables defined within
+the source config file.
+
+Dotdrop will fail if an imported path points to a non-existing file.
+It is possible to make non-existing paths not fatal by appending the path with `:optional`
+```yaml
+import_actions:
+- actions.d/myactions.yaml:optional
+```
+
+## Entry import_configs
+
+Entire config files can be imported using the `import_configs` entry.
+This means making the following available from the imported config file in the original config file:
+
+* dotfiles
+* profiles
+* actions
+* read/write transformations
+* variables/dynvariables
+
+Paths to import can be absolute or relative to the importing config file
+location.
+
+`config.yaml`
+```yaml
+config:
+  backup: true
+  create: true
+  dotpath: dotfiles
+  import_configs:
+  - other-config.yaml
+dotfiles:
+  f_abc:
+    dst: ~/.abc
+    src: abc
+    actions:
+    - show
+profiles:
+  my-host:
+    dotfiles:
+    - f_abc
+    - f_def
+  my-haskell:
+    include:
+    - other-host
+```
+
+`other-config.yaml`
+```yaml
+config:
+  backup: true
+  create: true
+  dotpath: dotfiles-other
+  import_actions:
+  - actions.yaml
+dotfiles:
+  f_def:
+    dst: ~/.def
+    src: def
+  f_ghci:
+    dst: ~/.ghci
+    src: ghci
+profiles:
+  other-host:
+    dotfiles:
+    - f_gchi
+```
+
+`actions.yaml`
+```yaml
+actions:
+  post:
+    show: less
+```
+
+In this example `config.yaml` imports `other-config.yaml`. The dotfile `f_def`
+used in the profile `my-host` is defined in `other-config.yaml`, and so is the
+profile `other-host` included from `my-haskell`. The action `show` is defined
+in `actions.yaml`, which is in turn imported by `other-config.yaml`.
+
+Dotdrop will fail if an imported path points to a non-existing file.
+It is possible to make non-existing paths not fatal by appending the path with `:optional`
+```yaml
+import_configs:
+- other-config.yaml:optional
+```

docs/config-format.md

@@ -0,0 +1,153 @@
+## Format
+
+Dotdrop config file uses [yaml](https://yaml.org/) syntax.
+
+### config entry
+
+The **config** entry (mandatory) contains settings for the deployment
+
+Entry    | Description | Default
+-------- | ------------- | ------------
+`backup` | create a backup of the dotfile in case it differs from the one that will be installed by dotdrop  | true
+`banner` | display the banner  | true
+`cmpignore` | list of patterns to ignore when comparing, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
+`create` | create directory hierarchy when installing dotfiles if it doesn't exist | true
+`default_actions` | list of action's keys to execute for all installed dotfile (see [actions](config-details.md#entry-actions)) | -
+`diff_command` | the diff command to use for diffing files | `diff -r -u {0} {1}`
+`dotpath` | path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles`
+`filter_file` | list of paths to load templating filters from (see [Templating available filters](templating.md#template-filters)) | -
+`func_file` | list of paths to load templating functions from (see [Templating available methods](templating.md#template-methods)) | -
+`ignoreempty` | do not deploy template if empty | false
+`import_actions` | list of paths to load actions from (absolute path or relative to the config file location, see [Import actions from file](config-details.md#entry-import_actions)) | -
+`import_configs` | list of config file paths to be imported in the current config (absolute path or relative to the current config file location, see [Import config files](config-details.md#entry-import_configs)) | -
+`import_variables` | list of paths to load variables from (absolute path or relative to the config file location see [Import variables from file](config-details.md#entry-import_variables)) | -
+`instignore` | list of patterns to ignore when installing, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
+`keepdot` | preserve leading dot when importing hidden file in the `dotpath` | false
+`link_dotfile_default` | set dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-dotfiles)) | `nolink`
+`link_on_import` | set dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-dotfiles)) | `nolink`
+`longkey` | use long keys for dotfiles when importing (see [Import dotfiles](usage.md#import-dotfiles)) | false
+`minversion` | (*for internal use, do not modify*) provides the minimal dotdrop version to use | -
+`showdiff` | on install show a diff before asking to overwrite (see `--showdiff`) | false
+`upignore` | list of patterns to ignore when updating, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
+`workdir` | path to the directory where templates are installed before being symlinked when using `link:link` or `link:link_children` (absolute path or relative to the config file location) | `~/.config/dotdrop`
+<s>link_by_default</s> | when importing a dotfile set `link` to that value per default | false
+
+### dotfiles entry
+
+The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdrop
+
+Entry    | Description
+-------- | -------------
+`dst` | where this dotfile needs to be deployed (dotfile with empty `dst` are ignored and considered installed, can use `variables` and `dynvariables`, make sure to quote)
+`src` | dotfile path within the `dotpath` (dotfile with empty `src` are ignored and considered installed, can use `variables` and `dynvariables`, make sure to quote)
+`link` | define how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-dotfiles)) (defaults to value of `link_dotfile_default`)
+`actions` | list of action keys that need to be defined in the **actions** entry below (see [actions](config-details.md#entry-actions))
+`cmpignore` | list of patterns to ignore when comparing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
+`ignoreempty` | if true empty template will not be deployed (defaults to value of `ignoreempty`)
+`instignore` | list of patterns to ignore when installing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
+`trans_read` | transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below, see [transformations](config-details.md#entry-transformations))
+`trans_write` | transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below, see [transformations](config-details.md#entry-transformations))
+`upignore` | list of patterns to ignore when updating (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
+<s>link_children</s> | replaced by `link: link_children`
+<s>trans</s> | replaced by `trans_read`
+
+```yaml
+<dotfile-key-name>:
+  dst: <where-this-file-is-deployed>
+  src: <filename-within-the-dotpath>
+  ## Optional
+  link: (nolink|link|link_children)
+  ignoreempty: (true|false)
+  cmpignore:
+    - "<ignore-pattern>"
+  upignore:
+    - "<ignore-pattern>"
+  instignore:
+    - "<ignore-pattern>"
+  actions:
+    - <action-key>
+  trans_read: <transformation-key>
+  trans_write: <transformation-key>
+```
+
+### profiles entry
+
+The **profiles** entry (mandatory) contains a list of profiles with the different dotfiles that
+  need to be managed
+
+Entry    | Description
+-------- | -------------
+`dotfiles` | the dotfiles associated to this profile
+`import` | list of paths containing dotfiles keys for this profile (absolute path or relative to the config file location, see [Import profile dotfiles from file](config-details.md#entry-profile-import)).
+`include` | include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (see [Include dotfiles from another profile](config-details.md#entry-profile-include))
+`variables` | profile specific variables (see [Variables](config.md#variables))
+`dynvariables` | profile specific interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables))
+`actions` | list of action keys that need to be defined in the **actions** entry below (see [actions](config-details.md#entry-actions))
+
+```yaml
+<some-profile-name-usually-the-hostname>:
+  dotfiles:
+  - <some-dotfile-key-name-defined-above>
+  - <some-other-dotfile-key-name>
+  - ...
+  ## Optional
+  include:
+  - <some-other-profile>
+  - ...
+  variables:
+    <name>: <value>
+  dynvariables:
+    <name>: <value>
+  actions:
+  - <some-action>
+  - ...
+  import:
+  - <some-path>
+  - ...
+```
+
+### actions entry
+
+The **actions** entry (optional) contains a list of actions (see [actions](config-details.md#entry-actions))
+
+```yaml
+actions:
+  <action-key>: <command-to-execute>
+```
+
+### trans_read entry
+
+The **trans_read** entry (optional) contains a list of transformations (see [transformations](config-details.md#entry-transformations))
+
+```yaml
+trans_read:
+   <trans-key>: <command-to-execute>
+```
+
+### trans_write entry
+
+The **trans_write** entry (optional) contains a list of write transformations (see [transformations](config-details.md#entry-transformations))
+
+```yaml
+trans_write:
+   <trans-key>: <command-to-execute>
+```
+
+### variables entry
+
+The **variables** entry (optional) contains a list of variables (see [variables](config.md#variables))
+
+```yaml
+variables:
+  <variable-name>: <variable-content>
+```
+
+### dynvariables entry
+
+The **dynvariables** entry (optional) contains a list of interpreted variables
+(see [Interpreted variables](config-details.md#entry-dynvariables))
+
+```yaml
+dynvariables:
+  <variable-name>: <shell-oneliner>
+```

docs/config.md

@@ -17,194 +17,6 @@ and use the first one found
 You can force dotdrop to use a different file either by using the `-c --cfg` cli switch
 or by defining the `DOTDROP_CONFIG` environment variable.
 
-## Format
-
-Dotdrop config file uses [yaml](https://yaml.org/) syntax.
-
-### config entry
-
-The **config** entry (mandatory) contains settings for the deployment
-
-* `backup`: create a backup of the dotfile in case it differs from the
-  one that will be installed by dotdrop (default *true*)
-* `banner`: display the banner (default *true*)
-* `cmpignore`: list of patterns to ignore when comparing, apply to all dotfiles
-  (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns))
-* `create`: create directory hierarchy when installing dotfiles if
-  it doesn't exist (default *true*)
-* `default_actions`: list of action's keys to execute for all installed dotfile
-  (see [actions](#entry-actions))
-* `diff_command`: the diff command to use for diffing files (default `diff -r -u {0} {1}`)
-* `dotpath`: path to the directory containing the dotfiles to be managed (default `dotfiles`)
-  by dotdrop (absolute path or relative to the config file location)
-* `filter_file`: list of paths to load templating filters from
-  (see [Templating available filters](templating.md#available-filters))
-* `func_file`: list of paths to load templating functions from
-   (see [Templating available methods](templating.md#available-methods))
-* `ignoreempty`: do not deploy template if empty (default *false*)
-* `import_actions`: list of paths to load actions from
-  (absolute path or relative to the config file location,
-  see [Import actions from file](#entry-import_actions))
-* `import_configs`: list of config file paths to be imported in
-  the current config (absolute path or relative to the current config file location,
-  see [Import config files](#entry-import_configs))
-* `import_variables`: list of paths to load variables from
-  (absolute path or relative to the config file location,
-  see [Import variables from file](#entry-import_variables))
-* `instignore`: list of patterns to ignore when installing, apply to all dotfiles
-  (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns))
-* `keepdot`: preserve leading dot when importing hidden file in the `dotpath` (default *false*)
-* `link_dotfile_default`: set dotfile's `link` attribute to this value when undefined.
-  Possible values: *nolink*, *link*, *link_children* (default: *nolink*,
-  see [Symlinking dotfiles](#symlink-dotfiles))
-* `link_on_import`: set dotfile's `link` attribute to this value when importing.
-  Possible values: *nolink*, *link*, *link_children* (default: *nolink*,
-  see [Symlinking dotfiles](#symlink-dotfiles))
-* `longkey`: use long keys for dotfiles when importing (default *false*,
-  see [Import dotfiles](usage.md#import-dotfiles))
-* `minversion`: (*for internal use, do not modify*) provides the minimal dotdrop version to use
-* `showdiff`: on install show a diff before asking to overwrite (see `--showdiff`) (default *false*)
-* `upignore`: list of patterns to ignore when updating, apply to all dotfiles
-  (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns))
-* `workdir`: path to the directory where templates are installed before being symlinked
-  when using `link:link` or `link:link_children`
-  (absolute path or relative to the config file location, defaults to *~/.config/dotdrop*)
-* *DEPRECATED* `link_by_default`: when importing a dotfile set `link` to that value per default (default *false*)
-
-### dotfiles entry
-
-The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdrop
-
-* `dst`: where this dotfile needs to be deployed
-  (dotfile with empty `dst` are ignored and considered installed,
-  can use `variables` and `dynvariables`, make sure to quote)
-* `src`: dotfile path within the `dotpath`
-  (dotfile with empty `src` are ignored and considered installed,
-  can use `variables` and `dynvariables`, make sure to quote)
-* `link`: define how this dotfile is installed.
-  Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`,
-  see [Symlinking dotfiles](#symlink-dotfiles))
-* `actions`: list of action keys that need to be defined in the **actions** entry below
-  (see [actions](#entry-actions))
-* `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards,
-  see [ignore patterns](#ignore-patterns))
-* `ignoreempty`: if true empty template will not be deployed (defaults to the value of `ignoreempty` above)
-* `instignore`: list of patterns to ignore when installing (enclose in quotes when using wildcards,
-  see [ignore patterns](#ignore-patterns))
-* `trans_read`: transformation key to apply when installing this dotfile
-  (must be defined in the **trans_read** entry below, see [transformations](#entry-transformations))
-* `trans_write`: transformation key to apply when updating this dotfile
-  (must be defined in the **trans_write** entry below, see [transformations](#entry-transformations))
-* `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards,
-  see [ignore patterns](#ignore-patterns))
-* *DEPRECATED* `link_children`: replaced by `link: link_children`
-* *DEPRECATED* `trans`: replaced by `trans_read`
-
-```yaml
-<dotfile-key-name>:
-  dst: <where-this-file-is-deployed>
-  src: <filename-within-the-dotpath>
-  ## Optional
-  link: (nolink|link|link_children)
-  ignoreempty: (true|false)
-  cmpignore:
-    - "<ignore-pattern>"
-  upignore:
-    - "<ignore-pattern>"
-  instignore:
-    - "<ignore-pattern>"
-  actions:
-    - <action-key>
-  trans_read: <transformation-key>
-  trans_write: <transformation-key>
-```
-
-### profiles entry
-
-The **profiles** entry (mandatory) contains a list of profiles with the different dotfiles that
-  need to be managed
-
-* `dotfiles`: the dotfiles associated to this profile
-* `import`: list of paths containing dotfiles keys for this profile
-  (absolute path or relative to the config file location,
-  see [Import profile dotfiles from file](#entry-profile-import)).
-* `include`: include all elements (dotfiles, actions, (dyn)variables, etc) from another profile
-  (see [Include dotfiles from another profile](#entry-profile-include))
-* `variables`: profile specific variables
-  (see [Variables](#variables))
-* `dynvariables`: profile specific interpreted variables
-  (see [Interpreted variables](#entry-dynvariables))
-* `actions`: list of action keys that need to be defined in the **actions** entry below
-  (see [actions](#entry-actions))
-
-```yaml
-<some-profile-name-usually-the-hostname>:
-  dotfiles:
-  - <some-dotfile-key-name-defined-above>
-  - <some-other-dotfile-key-name>
-  - ...
-  ## Optional
-  include:
-  - <some-other-profile>
-  - ...
-  variables:
-    <name>: <value>
-  dynvariables:
-    <name>: <value>
-  actions:
-  - <some-action>
-  - ...
-  import:
-  - <some-path>
-  - ...
-```
-
-### actions entry
-
-The **actions** entry (optional) contains a list of actions (see [actions](#entry-actions))
-
-```yaml
-actions:
-  <action-key>: <command-to-execute>
-```
-
-### trans_read entry
-
-The **trans_read** entry (optional) contains a list of transformations (see [transformations](#entry-transformations))
-
-```yaml
-trans_read:
-   <trans-key>: <command-to-execute>
-```
-
-### trans_write entry
-
-The **trans_write** entry (optional) contains a list of write transformations (see [transformations](#entry-transformations))
-
-```yaml
-trans_write:
-   <trans-key>: <command-to-execute>
-```
-
-### variables entry
-
-The **variables** entry (optional) contains a list of variables (see [variables](#variables))
-
-```yaml
-variables:
-  <variable-name>: <variable-content>
-```
-
-### dynvariables entry
-
-The **dynvariables** entry (optional) contains a list of interpreted variables
-(see [Interpreted variables](#entry-dynvariables))
-
-```yaml
-dynvariables:
-  <variable-name>: <shell-oneliner>
-```
-
 ## Variables
 
 Multiple variables can be used within the config file to
@@ -224,13 +36,13 @@ but those are resolved when the action/transformation is executed
 
 Following variables are available in the config files:
 
-* [variables defined in the config](#entry-variables)
+* [variables defined in the config](config-details.md#entry-variables)
-* [interpreted variables defined in the config](#entry-dynvariables)
+* [interpreted variables defined in the config](config-details.md#entry-dynvariables)
-* [profile variables defined in the config](#profile-variables)
+* [profile variables defined in the config](config-details.md#entry-profile-variables)
 * environment variables: `{{@@ env['MY_VAR'] @@}}`
 * dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header))
 
-As well as all template methods (see [Available methods](templating.md#available-methods))
+As well as all template methods (see [Available methods](templating.md#template-methods))
 
 ## Symlink dotfiles
 
@@ -243,528 +55,6 @@ which are controlled by the `link` config attribute of each dotfile:
 
 For more see [this how-to](howto/symlink-dotfiles.md)
 
-## Entry actions
-
-**Note**: any action 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.
-
-### Dotfile actions
-
-It is sometimes useful to execute some kind of action
-when deploying a dotfile.
-
-Note that dotfile actions are only
-executed when the dotfile is installed.
-
-For example let's consider
-[Vundle](https://github.com/VundleVim/Vundle.vim) is used
-to manage vim's plugins, the following action could
-be set to update and install the plugins when `vimrc` is
-deployed:
-
-```yaml
-actions:
-  vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall
-config:
-  backup: true
-  create: true
-  dotpath: dotfiles
-dotfiles:
-  f_vimrc:
-    dst: ~/.vimrc
-    src: vimrc
-    actions:
-      - vundle
-profiles:
-  home:
-    dotfiles:
-    - f_vimrc
-```
-
-Thus when `f_vimrc` is installed, the command
-`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
-be executed.
-
-Sometimes, you may even want to execute some action prior to deploying a dotfile.
-Let's take another example with
-[vim-plug](https://github.com/junegunn/vim-plug):
-
-```yaml
-actions:
-  pre:
-    vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl
-      -fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim)
-  vim-plug: vim +PlugInstall +qall
-config:
-  backup: true
-  create: true
-  dotpath: dotfiles
-dotfiles:
-  f_vimrc:
-    dst: ~/.vimrc
-    src: vimrc
-    actions:
-       - vim-plug-install
-       - vim-plug
-profiles:
-  home:
-    dotfiles:
-    - f_vimrc
-```
-
-This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug)
-is installed prior to deploying the `~/.vimrc` dotfile.
-
-You can also define `post` actions like this:
-
-```yaml
-actions:
-  post:
-    some-action: echo "Hello, World!" >/tmp/log
-```
-
-If you don't specify neither `post` nor `pre`, the action will be executed
-after the dotfile deployment (which is equivalent to `post`).
-Actions cannot obviously be named `pre` or `post`.
-
-Actions can even be parameterized. For example:
-```yaml
-actions:
-  echoaction: echo '{0}' > {1}
-config:
-  backup: true
-  create: true
-  dotpath: dotfiles
-dotfiles:
-  f_vimrc:
-    dst: ~/.vimrc
-    src: vimrc
-    actions:
-      - echoaction "vim installed" /tmp/mydotdrop.log
-  f_xinitrc:
-    dst: ~/.xinitrc
-    src: xinitrc
-    actions:
-      - echoaction "xinitrc installed" /tmp/myotherlog.log
-profiles:
-  home:
-    dotfiles:
-    - f_vimrc
-    - f_xinitrc
-```
-
-The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when
-vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'`
-when xinitrc is installed.
-
-### Default actions
-
-Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (*pre* or *post*).
-
-For example, the below action will log each dotfile installation to a file.
-
-```yaml
-actions:
-  post:
-    loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}"
-config:
-  backup: true
-  create: true
-  dotpath: dotfiles
-  default_actions:
-  - loginstall "/tmp/dotdrop-installation.log"
-dotfiles:
-  f_vimrc:
-    dst: ~/.vimrc
-    src: vimrc
-profiles:
-  hostname:
-    dotfiles:
-    - f_vimrc
-```
-
-### Profile actions
-
-Profile can be either `pre` or `post` actions. Those are executed before
-any dotfile installation (for `pre`) and after all dotfiles installation (for `post`)
-only if at least one dotfile has been installed.
-
-### Fake dotfile and actions
-
-*Fake* dotfile can be created by specifying no `dst` and no `src` (see [config format](#format)).
-By binding an action to such a *fake* dotfile, you make sure the action is always executed since
-*fake* dotfile are always considered installed.
-
-```yaml
-actions:
-  always_action: 'date > ~/.dotdrop.log'
-dotfiles:
-  fake:
-    src:
-    dst:
-    actions:
-    - always_action
-```
-
-## Entry transformations
-
-For examples of transformation uses, see
-
-* [Store compressed directories](howto/store-compressed-directories.md)
-* [Sensitive dotfiles](howto/sensitive-dotfiles.md)
-
-**Note**: 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.
-
-There are two types of transformations available:
-
-* **read transformations**: used to transform dotfiles before they are installed ([format](#format) 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
-    * Happens **before** the dotfile is templated with jinja2 (see [templating](templating.md))
-
-* **write transformations**: used to transform files before updating a dotfile ([format](#format) 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/README.md).
-
-Note that transformations cannot be used if the dotfiles 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 itself as well as its 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`
-
-## Entry variables
-
-Variables defined in the `variables` entry are made available within the config file.
-
-Config variables are recursively evaluated what means that
-a config like the below
-```yaml
-variables:
-  var1: "var1"
-  var2: "{{@@ var1 @@}} var2"
-  var3: "{{@@ var2 @@}} var3"
-  var4: "{{@@ dvar4 @@}}"
-dynvariables:
-  dvar1: "echo dvar1"
-  dvar2: "{{@@ dvar1 @@}} dvar2"
-  dvar3: "{{@@ dvar2 @@}} dvar3"
-  dvar4: "echo {{@@ var3 @@}}"
-```
-
-will result in the following available variables:
-
-* var1: `var1`
-* var2: `var1 var2`
-* var3: `var1 var2 var3`
-* var4: `echo var1 var2 var3`
-* dvar1: `dvar1`
-* dvar2: `dvar1 dvar2`
-* dvar3: `dvar1 dvar2 dvar3`
-* dvar4: `var1 var2 var3`
-
-### Profile variables
-
-Profile variables will take precedence over globally defined variables.
-This means that you could do something like this:
-```yaml
-variables:
-  git_email: home@email.com
-dotfiles:
-  f_gitconfig:
-    dst: ~/.gitconfig
-    src: gitconfig
-profiles:
-  work:
-    dotfiles:
-    - f_gitconfig
-    variables:
-      git_email: work@email.com
-  private:
-    dotfiles:
-    - f_gitconfig
-```
-
-## Entry dynvariables
-
-It is also possible to have *dynamic* variables in the sense that their
-content will be interpreted by the shell before being substituted.
-
-These need to be defined in the config file under the entry `dynvariables`.
-
-For example:
-```yaml
-dynvariables:
-  dvar1: head -1 /proc/meminfo
-  dvar2: "echo 'this is some test' | rev | tr ' ' ','"
-  dvar3: /tmp/my_shell_script.sh
-  user: "echo $USER"
-  config_file: test -f "{{@@ user_config @@}}" && echo "{{@@ user_config @@}}" || echo "{{@@ dfl_config @@}}"
-variables:
-  user_config: "profile_{{@@ user @@}}_uid.yaml"
-  dfl_config: "profile_default.yaml"
-```
-
-They have the same properties as [Variables](#variables).
-
-## Entry profile include
-
-If one profile is using the entire set of another profile, one can use
-the `include` entry to avoid redundancy.
-
-Note that everything from the included profile is made available
-(actions, variables/dynvariables, etc).
-
-For example:
-```yaml
-profiles:
-  host1:
-    dotfiles:
-      - f_xinitrc
-    include:
-      - host2
-  host2:
-    dotfiles:
-      - f_vimrc
-```
-Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
-
-For more advanced use-cases variables
-([variables](#variables) and [dynvariables](#entry-dynvariables))
-can be used to specify the profile to include in a profile
-
-For example:
-```yaml
-variables:
-  var1: "john"
-dynvariables:
-  d_user: "echo $USER"
-profiles:
-  profile_john:
-    dotfiles:
-    - f_john_dotfile
-  profile_bill:
-    dotfiles:
-    - f_bill_dotfile
-  p1:
-    include:
-    - "profile_{{@@ d_user @@}}"
-  p2:
-    include:
-    - "profile_{{@@ var1 @@}}"
-```
-
-## Entry profile import
-
-Profile's dotfiles list can be loaded from external files
-by specifying their paths in the config entry `import` under the specific profile.
-
-The paths can be absolute or relative to the config file location.
-
-`config.yaml`
-```yaml
-dotfiles:
-  f_abc:
-    dst: ~/.abc
-    src: abc
-  f_def:
-    dst: ~/.def
-    src: def
-  f_xyz:
-    dst: ~/.xyz
-    src: xyz
-profiles:
-  p1:
-    dotfiles:
-    - f_abc
-    import:
-    - somedotfiles.yaml
-```
-
-`somedotfiles.yaml`
-```
-dotfiles:
-  - f_def
-  - f_xyz
-```
-
-Variables can be used in `import` and would allow to do something like
-```yaml
-import:
-- profiles.d/{{@@ profile @@}}.yaml
-```
-
-## Entry import_variables
-
-It is possible to load variables/dynvariables from external files by providing their
-paths in the config entry `import_variables`.
-
-The paths can be absolute or relative to the config file location.
-
-`config.yaml`
-```yaml
-config:
-  backup: true
-  create: true
-  dotpath: dotfiles
-  import_variables:
-  - variables.d/myvars.yaml
-```
-
-`variables.d/myvars.yaml`
-```yaml
-variables:
-  var1: "extvar1"
-dynvariables:
-  dvar1: "echo extdvar1"
-```
-
-Dotdrop will fail if an imported path points to a non-existing file.
-It is possible to make non-existing paths not fatal by appending the path with `:optional`
-```yaml
-import_variables:
-- variables.d/myvars.yaml:optional
-```
-
-## Entry import_actions
-
-It is possible to load actions from external files by providing their
-paths in the config entry `import_actions`.
-
-The paths can be absolute or relative to the config file location.
-
-`config.yaml`
-```yaml
-config:
-  backup: true
-  create: true
-  dotpath: dotfiles
-  import_actions:
-  - actions.d/myactions.yaml
-dotfiles:
-  f_abc:
-    dst: ~/.abc
-    src: abc
-    actions:
-      - dateme
-```
-
-`actions.d/myactions.yaml`
-```yaml
-actions:
-  dateme: date > /tmp/timestamp
-```
-
-External variables will take precedence over variables defined within
-the source config file.
-
-Dotdrop will fail if an imported path points to a non-existing file.
-It is possible to make non-existing paths not fatal by appending the path with `:optional`
-```yaml
-import_actions:
-- actions.d/myactions.yaml:optional
-```
-
-## Entry import_configs
-
-Entire config files can be imported using the `import_configs` entry.
-This means making the following available from the imported config file in the original config file:
-
-* dotfiles
-* profiles
-* actions
-* read/write transformations
-* variables/dynvariables
-
-Paths to import can be absolute or relative to the importing config file
-location.
-
-`config.yaml`
-```yaml
-config:
-  backup: true
-  create: true
-  dotpath: dotfiles
-  import_configs:
-  - other-config.yaml
-dotfiles:
-  f_abc:
-    dst: ~/.abc
-    src: abc
-    actions:
-    - show
-profiles:
-  my-host:
-    dotfiles:
-    - f_abc
-    - f_def
-  my-haskell:
-    include:
-    - other-host
-```
-
-`other-config.yaml`
-```yaml
-config:
-  backup: true
-  create: true
-  dotpath: dotfiles-other
-  import_actions:
-  - actions.yaml
-dotfiles:
-  f_def:
-    dst: ~/.def
-    src: def
-  f_ghci:
-    dst: ~/.ghci
-    src: ghci
-profiles:
-  other-host:
-    dotfiles:
-    - f_gchi
-```
-
-`actions.yaml`
-```yaml
-actions:
-  post:
-    show: less
-```
-
-In this example `config.yaml` imports `other-config.yaml`. The dotfile `f_def`
-used in the profile `my-host` is defined in `other-config.yaml`, and so is the
-profile `other-host` included from `my-haskell`. The action `show` is defined
-in `actions.yaml`, which is in turn imported by `other-config.yaml`.
-
-Dotdrop will fail if an imported path points to a non-existing file.
-It is possible to make non-existing paths not fatal by appending the path with `:optional`
-```yaml
-import_configs:
-- other-config.yaml:optional
-```
-
 ## Dynamic dotfile paths
 
 Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using

docs/contributing.md

@@ -1 +0,0 @@
-see [the dedicated doc](https://github.com/deadc0de6/dotdrop/blob/master/CONTRIBUTING.md)

docs/howto/README.md

@@ -1,12 +1,20 @@
 # HowTo
 
-## Append to a dotfile
+## Append text to a dotfile on install
 
-[Append to a dotfile](append.md)
+[Append text to a dotfile on install](append.md)
 
-## Create special files
+## Create files on install
 
-[Create special files](create-special-files.md)
+[Create files on install](create-special-files.md)
+
+## Handle compressed directories
+
+[Store compressed directories](store-compressed-directories.md)
+
+## Handle secrets
+
+[Handle secrets](sensitive-dotfiles.md)
 
 ## Handle special chars
 
@@ -16,6 +24,14 @@
 
 [Improve git integration](improve-git-integration.md)
 
+## Include file or template in template
+
+[Include file or template in template](include-in-template.md)
+
+## Manage system dotfiles
+
+[Manage system dotfiles](global-config-files.md)
+
 ## Merge files on install
 
 [Merge files on install](merge-files-when-installing.md)
@@ -24,14 +40,6 @@
 
 [Share content across dotfiles](sharing-content.md)
 
-## Store compressed directories
-
-[Store compressed directories](store-compressed-directories.md)
-
-## Store secrets
-
-[Store secrets](sensitive-dotfiles.md)
-
 ## Symlink dotfiles
 
-[Symlink dotfiles](symlink-dotfiles.md)
+[Symlink dotfiles](symlink-dotfiles.md)

docs/howto/append.md

@@ -1,6 +1,8 @@
+# Append text on install
+
 Sometimes it might be useful to be able to append some text to a
 file. Dotdrop is able to do that with the help of
-[actions](../config.md#entry-actions) and a temporary file.
+[actions](../config-details.md#entry-actions) and a temporary file.
 
 Below is a config example to append to a file:
 ```yaml

docs/howto/create-special-files.md

@@ -1,5 +1,7 @@
+# Create files on install
+
 One way for creating symlinks (or any other special files) is to use a combination of
-[actions](../config.md#entry-actions) and a *fake* dotfile.
+[actions](../config-details.md#entry-actions) and a *fake* dotfile.
 
 Let's say for example you have a list of directories you want to link
 from under `~/.original` to `~/symlinks`.

docs/howto/global-config-files.md

@@ -1,4 +1,4 @@
-# How to manage system wide config files with dotdrop
+# Manage system dotfiles
 
 Dotdrop doesn't allow to handle file rights and permissions (at least not directly). Every operations (`mkdir`, `cp`, `mv`, `ln`, file creation) are executed with the rights of the user calling dotdrop. The rights of the stored dotfile are mirrored on the deployed dotfile (`chmod` like). It works well for local/user dotfiles but doesn't allow to manage global/system config files (`/etc` or `/var` for example) directly.
 

docs/howto/include-in-template.md

@@ -0,0 +1,14 @@
+# Include file or template in template
+
+[Jinja2](http://jinja.pocoo.org/docs/2.10/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related doc](http://jinja.pocoo.org/docs/2.10/templates/#include) for more. The path must be relative to the `dotpath`.
+
+For example:
+```yaml
+{%@@ include 'colors/black.colors' @@%}
+```
+
+Of course, paths could be also dynamically generated using variables.
+For example:
+```yaml
+{%@@ include colors_path + '/black.colors' @@%}
+```

docs/howto/merge-files-when-installing.md

@@ -1,3 +1,5 @@
+# Merge files on install
+
 Dotdrop allows to merge multiple files into one using the jinja2's `include` directive.
 
 For example let's consider you want to keep your `vimrc` split into multiple parts in dotdrop
@@ -43,15 +45,15 @@ The `include` path parameter needs to be relative to your `dotpath`.
 
 Dotdrop will then automagically include the files into your vimrc when handling `f_vimrc`.
 
-# Merge all files in a directory
+## Merge all files in a directory
 
 To include all files in a directory, a combination of
-[dynvariables](../config.md#entry-dynvariables)
+[dynvariables](../config-details.md#entry-dynvariables)
 and [jinja2 directives](http://jinja.pocoo.org/docs/2.10/) have to be used.
 
 Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
 
-First define a [dynvariables](../config.md#entry-dynvariables)
+First define a [dynvariables](../config-details.md#entry-dynvariables)
 in the config file which will look for files to include in the above directory:
 ```yaml
 dynvariables:

docs/howto/sensitive-dotfiles.md

@@ -1,4 +1,4 @@
-# Sensitive dotfiles
+# Handle secrets
 
 Two solutions exist, the first one using an unversioned file (see [Environment variables](../templating.md#environment-variables))
 and the second using transformations (see [Store encrypted dotfiles](#store-encrypted-dotfiles)).
@@ -6,7 +6,7 @@ and the second using transformations (see [Store encrypted dotfiles](#store-encr
 * [Store encrypted dotfiles](#store-encrypted-dotfiles)
 * [Load passphrase from file](#load-passphrase-from-file)
 
-# Store encrypted dotfiles
+## Store encrypted dotfiles
 
 Here's an example of part of a config file to use gpg encrypted dotfiles:
 ```yaml
@@ -47,7 +47,7 @@ $ cp <encrypted-version-of-secret> dotfiles/secret
 
 * commit and push the changes
 
-# Load passphrase from file
+## Load passphrase from file
 
 Passphrase is retrieved using a script:
 ```yaml

docs/howto/sharing-content.md

@@ -1,3 +1,5 @@
+# Share content across dotfiles
+
 There are cases in which two or more dotfiles are very similar. For example,
 two files exporting environment variables for two projects built with the same
 technology (eg. two node.js web servers deployed on AWS). In these cases it's
@@ -9,7 +11,7 @@ are a few suggestions about how to achieve this.
 * [Profile variables](#profile-variables)
 * [Jinja macros](#jinja-macros)
 
-# Brute force templating
+## Brute force templating
 
 The first approach is sheer use of templating and variables
 In order to do this, we need to:
@@ -59,12 +61,12 @@ export DB_HOST='super-duper.host'
 export DB_PORT='4521'
 ```
 
-# Profile variables
+## Profile variables
 
 Albeit flexible, the previous method is a bit cumbersome for some use cases.
 For example, when the dotfiles belong to different profiles, the cleanest
 solution consists in using
-[profile variables](../config.md#profile-variables). This is achieved by:
+[profile variables](../config-details.md#entry-profile-variables). This is achieved by:
 
 1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
 2. Adding some variables in the merged dotfile via templating.
@@ -122,7 +124,7 @@ export DB_HOST='cheaper.host'
 export DB_PORT='9632'
 ```
 
-# Jinja macros
+## Jinja macros
 
 Even though it has cleaner dotfiles, the profile-variable-based procedure can't
 be used in two scenarios: when the dotfiles belong to the same profile, and

docs/howto/special-chars.md

@@ -1,10 +1,12 @@
+# Handle special chars
+
 * [Detect encoding](#detect-encoding)
 * [Special chars](#special-chars)
 * [Re-encode](#re-encode)
 
 ---
 
-# Detect encoding
+## Detect encoding
 
 Text file encoding can be identified using for example `file -b <file-path>` or in vim
 with `:set fileencoding`
@@ -21,9 +23,9 @@ $ file -b <some-file>
 ISO-8859 text, with escape sequences
 ```
 
-# Special chars
+## Special chars
 
-## CRLF
+### CRLF
 
 The use of dotfiles with DOS/Windows line ending (CRLF, `\r\n`) will result in
 the comparison (`compare`) returning a difference while there is none.
@@ -33,7 +35,7 @@ One solution is to use `dos2unix` to re-format the dotfiles before adding them
 
 See <https://github.com/deadc0de6/dotdrop/issues/42>.
 
-## Non-unicode chars
+### Non-unicode chars
 
 Jinja2 is not able to process non-unicode chars (<http://jinja.pocoo.org/docs/2.10/api/>). This means that dotfiles using non-unicode chars can still be fully managed by dotdrop however when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none.
 
@@ -41,6 +43,6 @@ Either replace the non-unicode chars (see below [Re-encode](#re-encode)) or acce
 
 See <https://github.com/deadc0de6/dotdrop/issues/42>.
 
-# Re-encode
+## Re-encode
 
 To change an existing file's encoding, you can use `recode UTF-8 <filename>` (see [recode](https://linux.die.net/man/1/recode)) or in vim `:set fileencoding=utf-8`.

docs/howto/store-compressed-directories.md

@@ -1,4 +1,4 @@
-# Store compressed directories
+# Handle compressed directories
 
 This is an example on how to use transformations (`trans_read` and `trans_write`) to store
 compressed directories and deploy them with dotdrop.

docs/howto/symlink-dotfiles.md

@@ -13,7 +13,7 @@ Note that if the dotfile is using template directives, it will be symlinked into
 `~/.config/dotdrop` instead of directly into your *dotpath*
 (see [Templating symlinked dotfiles](#templating-symlinked-dotfiles))
 
-# Link children
+## Link children
 
 This feature can be very useful for dotfiles when you don't want the entire
 directory to be symlink but still want to keep a clean config files (with a
@@ -77,7 +77,7 @@ $ tree -L 1 ~/.vim
 └── vimrc -> ~/.dotfiles/vim/vimrc
 ```
 
-# Templating symlinked dotfiles
+## Templating symlinked dotfiles
 
 For dotfiles not using any templating directives, those are directly linked
 to dotdrop's `dotpath` directory (see [Config](../config.md)).

docs/installation.md

@@ -4,7 +4,7 @@ Installing dotdrop [as a submodule](#as-a-submodule) is the recommended way.
 
 If you want to keep your python environment clean, use the virtualenv installation instructions
 (see [As a submodule in a virtualenv](#as-a-submodule-in-a-virtualenv) and
-[With pypi in a virtualenv](#with-pypi-in-a-virtualenv)).
+[Pypi package in a virtualenv](#pypi-package-in-a-virtualenv)).
 In that case, the virtualenv environment might need to be loaded before any attempt to use dotdrop.
 
 ## As a submodule
@@ -66,16 +66,16 @@ $ ./dotdrop.sh --help
 
 Then follow the instructions under [As a submodule](#as-a-submodule).
 
-## With pypi
+## Pypi package
 
 Install dotdrop
 ```bash
 $ pip3 install dotdrop --user
 ```
 
-and then [setup your repository](#setup-your-repository).
+and then [setup your repository](repository-setup.md).
 
-## With pypi in a virtualenv
+## Pypi package in a virtualenv
 
 Install dotdrop in a virtualenv from pypi
 ```bash
@@ -91,7 +91,7 @@ $ source env/bin/activate
 $ dotdrop --help
 ```
 
-Then follow the instructions under [With pypi](#with-pypi).
+Then follow the instructions under [Pypi package](#pypi-package).
 
 ## Aur packages
 
@@ -99,7 +99,7 @@ Dotdrop is available on aur:
 * stable: <https://aur.archlinux.org/packages/dotdrop/>
 * git version: <https://aur.archlinux.org/packages/dotdrop-git/>
 
-Then follow the [doc to setup your repository](#setup-your-repository).
+Then follow the [doc to setup your repository](repository-setup.md).
 
 ## Snap package
 
@@ -110,7 +110,7 @@ Install it with
 snap install dotdrop
 ```
 
-Then follow the [doc to setup your repository](#setup-your-repository).
+Then follow the [doc to setup your repository](repository-setup.md).
 
 ## Dependencies
 
@@ -150,49 +150,6 @@ Or if installed through pypi:
 $ pip3 install dotdrop --upgrade --user
 ```
 
-## Setup your repository
-
-Either create a repository on your prefered platform and clone it or create one locally.
-This repository will contain two main elements, dotdrop's config file (`config.yaml`)
-and a directory containing all your dotfiles managed by dotdrop.
-```bash
-## clone your repository (my-dotfiles)
-$ git clone <some-url>/my-dotfiles
-$ cd my-dotfiles
-
-## within the repository create a directory to store your dotfiles
-## (refered by "dotpath" in the config, which defaults to "dotfiles")
-$ mkdir dotfiles
-```
-
-Then add a config file. You can get a
-[minimal config file](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml)
-from dotdrop's repository with
-```bash
-$ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml
-```
-It is recommended to store your config file directly within your repository
-(*my-dotfiles* in the example above) but you could save it in different places if you wish,
-see [config location](config.md#location) for more.
-
-```bash
-$ tree my-dotfiles
-my-dotfiles
-├── config.yaml
-└── dotfiles
-```
-
-If your config file is in an exotic location, you can add an alias
-in your preferred shell to call dotdrop with the config file path argument.
-```
-alias dotdrop='dotdrop --cfg=<path-to-your-config.yaml>'
-```
-
-For more info on the config file format, see [the config doc](config.md).
-
-Finally start using dotdrop with `dotdrop --help`. See the [usage doc](usage.md)
-and [the example](https://github.com/deadc0de6/dotdrop/blob/master/README.md#getting-started).
-
 ## Shell completion
 
 Completion scripts exist for `bash`, `zsh` and `fish`,

docs/repository-setup.md

@@ -0,0 +1,42 @@
+# Repository setup
+
+Either create a repository on your prefered platform and clone it or create one locally.
+This repository will contain two main elements, dotdrop's config file (`config.yaml`)
+and a directory containing all your dotfiles managed by dotdrop.
+```bash
+## clone your repository (my-dotfiles)
+$ git clone <some-url>/my-dotfiles
+$ cd my-dotfiles
+
+## within the repository create a directory to store your dotfiles
+## (refered by "dotpath" in the config, which defaults to "dotfiles")
+$ mkdir dotfiles
+```
+
+Then add a config file. You can get a
+[minimal config file](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml)
+from dotdrop's repository with
+```bash
+$ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml
+```
+It is recommended to store your config file directly within your repository
+(*my-dotfiles* in the example above) but you could save it in different places if you wish,
+see [config location](config.md#location) for more.
+
+```bash
+$ tree my-dotfiles
+my-dotfiles
+├── config.yaml
+└── dotfiles
+```
+
+If your config file is in an exotic location, you can add an alias
+in your preferred shell to call dotdrop with the config file path argument.
+```
+alias dotdrop='dotdrop --cfg=<path-to-your-config.yaml>'
+```
+
+For more info on the config file format, see [the config doc](config.md).
+
+Finally start using dotdrop with `dotdrop --help`. See the [usage doc](usage.md)
+and [the example](https://github.com/deadc0de6/dotdrop/blob/master/README.md#getting-started).

docs/templating.md

@@ -30,7 +30,7 @@ Following variables are available in templates:
 * `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config.md) absolute path.
 * dotfile specific variables (see [Dotfile variables](#dotfile-variables))
 * config variables (see [Variables](config.md#variables)).
-* config interpreted variables (see [Interpreted variables](config.md#entry-dynvariables)).
+* config interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables)).
 
 ## Dotfile variables
 
@@ -83,28 +83,7 @@ alias dotdrop='eval $(grep -v "^#" ~/dotfiles/.env) /usr/bin/dotdrop --cfg=~/dot
 The above aliases load all the variables from `~/dotfiles/.env`
 (while omitting lines starting with `#`) before calling dotdrop.
 
-## Dotdrop header
+## Template methods
-
-Dotdrop is able to insert a header in the generated dotfiles. This allows
-to remind anyone opening the file for editing that this file is managed by dotdrop.
-
-Here's what it looks like:
-```
-This dotfile is managed using dotdrop
-```
-
-The header can be automatically added with:
-```
-{{@@ header() @@}}
-```
-
-Properly commenting the header in templates is the responsibility of the user
-as [jinja2](http://jinja.pocoo.org/) has no way of knowing what is the proper char(s) used for comments.
-Either prepend the directive with the commenting char(s) used in the dotfile
-(for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`.
-The result is equivalent.
-
-## Available methods
 
 Beside [jinja2 global functions](http://jinja.pocoo.org/docs/2.10/templates/#list-of-global-functions)
 the following methods can be used within the templates:
@@ -159,7 +138,7 @@ this should exist
 {%@@ endif @@%}
 ```
 
-## Available filters
+## Template filters
 
 Beside [jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.10.x/templates/#builtin-filters)
 custom user-defined filter functions can be loaded using the config entry `filter_file`:
@@ -195,28 +174,26 @@ Macros must be imported `with context` in order to have access to the variables:
 
 For more see the [dedicated jinja2 doc](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
 
-## Ignore empty template
+## Dotdrop header
 
-It is possible to avoid having an empty rendered template being
+Dotdrop is able to insert a header in the generated dotfiles. This allows
-deployed by setting the `ignoreempty` entry to *true*. This can be set
+to remind anyone opening the file for editing that this file is managed by dotdrop.
-globally for all dotfiles or only for specific dotfiles.
 
-For more see the [Config](config.md).
+Here's what it looks like:
-
+```
-## Include file or template in template
+This dotfile is managed using dotdrop
-
-[Jinja2](http://jinja.pocoo.org/docs/2.10/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related doc](http://jinja.pocoo.org/docs/2.10/templates/#include) for more. The path must be relative to the `dotpath`.
-
-For example:
-```yaml
-{%@@ include 'colors/black.colors' @@%}
 ```
 
-Of course, paths could be also dynamically generated using variables.
+The header can be automatically added with:
-For example:
-```yaml
-{%@@ include colors_path + '/black.colors' @@%}
 ```
+{{@@ header() @@}}
+```
+
+Properly commenting the header in templates is the responsibility of the user
+as [jinja2](http://jinja.pocoo.org/) has no way of knowing what is the proper char(s) used for comments.
+Either prepend the directive with the commenting char(s) used in the dotfile
+(for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`.
+The result is equivalent.
 
 ## Debug templates
 

mkdocs.yml

@@ -9,13 +9,14 @@ theme:
     collapse_navigation: false
 use_directory_urls: true
 nav:
-  - Home: 'README.md'
   - Installation: 'installation.md'
+  - 'Repository setup': 'repository-setup.md'
   - Usage: 'usage.md'
   - Config: 'config.md'
+  - 'Config format': 'config-format.md'
+  - 'Config details': 'config-details.md'
   - Templating: 'templating.md'
   - HowTo: 'howto/README.md'
-  - Contributing: 'contributing.md'
 markdown_extensions:
   - meta
   - tables