doc update structure

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)).