update doc

docs/config-details.md

@@ -10,7 +10,7 @@ Four types of actions can be defined:
 * [Profile actions](#profile-actions)
 * [Fake dotfiles and actions](#fake-dotfile-and-actions)
 
-### Dotfile actions
+#### Dotfile actions
 
 It is sometimes useful to execute some kind of action
 when deploying a dotfile.
@@ -119,7 +119,7 @@ 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
+#### Default actions
 
 Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (*pre* or *post*).
 
@@ -145,13 +145,13 @@ profiles:
     - f_vimrc
 ```
 
-### Profile actions
+#### 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 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
@@ -338,6 +338,9 @@ profiles:
     - "profile_{{@@ var1 @@}}"
 ```
 
+Note that profile cannot include other profiles defined above in
+the import tree (profile exists in another file and is imported using `import_configs` for example).
+
 ## Entry profile import
 
 Profile's dotfiles list can be loaded from external files

docs/config-format.md

@@ -2,6 +2,9 @@
 
 Dotdrop config file uses [yaml](https://yaml.org/) syntax.
 
+Here is a minimal config file to start with:
+[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
+
 ### config entry
 
 The **config** entry (mandatory) contains settings for the deployment

docs/config.md

@@ -26,6 +26,7 @@ parametrize following elements of the config:
   * `import_actions`
   * `import_configs`
   * profiles's `import`
+  * profiles's `include`
 
 `actions` and `transformations` also support the use of variables
 but those are resolved when the action/transformation is executed
@@ -40,7 +41,18 @@ Following variables are available in the config files:
 * 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#template-methods))
+As well as all [template methods](templating.md#template-methods) and [template filters](templating.md#template-filters).
+
+Note that all variables available in the config file will
+then be available during [templating](templating.md).
+
+Here are some rules on the use of variables in configs:
+
+* [interpreted variables](config-details.md#entry-dynvariables) are executed in their own file
+* [interpreted variables](config-details.md#entry-dynvariables) and
+  [variables](config-details.md#entry-variables) are templated before
+  [interpreted variables](config-details.md#entry-dynvariables) are executed
+* config files do not have access to variables defined above in the import tree
 
 ## Symlink dotfiles
 

docs/installation.md

@@ -96,6 +96,7 @@ Then follow the instructions under [Pypi package](#pypi-package).
 ## Aur packages
 
 Dotdrop is available on aur:
+
 * stable: <https://aur.archlinux.org/packages/dotdrop/>
 * git version: <https://aur.archlinux.org/packages/dotdrop-git/>
 

docs/usage.md

@@ -9,7 +9,7 @@ The basic use of dotdrop is
 * import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
 * install the dotfiles (will *copy/link* those from your `dotpath` to the filesystem): `dotdrop install`
 
-Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use `update` to mirror back those changes in the `dotpath` of dotdrop.
+Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use `update` to mirror back those changes in dotdrop.
 
 For more advanced uses:
 
@@ -56,7 +56,7 @@ filesystem. It will copy the dotfile and update the
 config file automatically.
 
 Note that dotdrop will dereference all symlinks
-when importing a file or directory (see [issue #184](https://github.com/deadc0de6/dotdrop/issues/184) for more)
+when importing a file or directory.
 
 For example to import `~/.xinitrc`
 ```bash
@@ -82,8 +82,9 @@ Importing `~/.mutt/colors` and then `~/.vim/colors` will result in
 * `d_mutt_colors` and `d_vim_colors` in the long format
 
 Dotfile can be imported as a different file with the use
-of the command line switch `--as`. It is however recommended
-to use the [[templating]] to avoid duplicates and optimize
+of the command line switch `--as` (effectively selecting the `src` part
+of the dotfile in the config). It is however recommended
+to use [templating](templating.md) to avoid duplicates and optimize
 dotfiles management.
 ```bash
 $ dotdrop import ~/.zshrc --as=~/.zshrc.test