refactor doc for #469

CONTRIBUTING.md

@@ -4,7 +4,6 @@ Contents
 * [Config parsing](#config-parsing)
   * [Lower layer](#lower-layer)
   * [Higher layer](#higher-layer)
-  * [Precedence](#precedence)
   * [Variable resolution](#variable-resolution)
   * [Rules](#rules)
   * [Ignore pattern](#ignore-pattern)
@@ -96,21 +95,9 @@ example) won't be *seen* by the higher layer until the config is reloaded. Consi
 `dirty` flag as a sign the file needs to be written and its representation in higher
 levels in not accurate anymore.
 
-## Precedence
-
-* `dynvariables` > `variables`
-* Profile `(dyn)variables` > any other `(dyn)variables`
-* Profile `(dyn)variables` > profile's included `(dyn)variables`
-* Imported `variables`/`dynvariables` > `(dyn)variables`
-
-When `import_configs` importing config's elements except the `(dyn)variables`
-will take precedence in case of name clash
-(see <https://github.com/deadc0de6/dotdrop/issues/443>).
-
 ## Variable resolution
 
-How variables are resolved (through Jinja2's
-templating) in the config file.
+How variables are resolved (through Jinja2's templating) in the config file.
 
 * Resolve main config file variables
   * Merge `variables` and `dynvariables` (allowing cyclic references)

docs/config/config-profiles.md

@@ -1,6 +1,8 @@
 # Profiles entry
 
-The **profiles** entry (mandatory) contains a YAML object with sub-objects for the profiles for the different dotfiles that need to be managed.  The entries in the sub-objects are as follows:
+The mandatory `profiles` entry contains a YAML object with sub-objects defining
+each profile and its related dotfiles, variables, actions, and other configurations.
+The entries in the sub-objects are as follows:
 
 Entry    | Description
 -------- | -------------
@@ -9,7 +11,7 @@ Entry    | Description
 `include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-profiles.md#profile-include-entry) and [meta profiles](../howto/group-hosts.md))
 `variables` | Profile-specific variables (See [Variables](config-file.md#variables))
 `dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-dynvars.md))
-`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-actions.md))
+`actions` | List of action keys defined in the [actions](config-actions.md) entry (See [actions](config-actions.md))
 
 ```yaml
 <some-profile-name-usually-the-hostname>:

docs/config/config-variables.md

@@ -1,13 +1,14 @@
 # Variables entry
 
-The **variables** entry (optional) contains a variables mapping (See [variables](config-file.md#variables)).
+The optional **variables** entry contains a variables mapping (See [variables](config-file.md#variables)).
 
 ```yaml
 variables:
   <variable-name>: <variable-content>
 ```
 
-Variables defined in the `variables` entry are made available within the config file.
+Variables defined in the `variables` entry are made available
+within the config file and to the [templates](../template/templating.md).
 
 For example
 ```yaml
@@ -53,4 +54,54 @@ variables:
 ```
 
 Where the above would be referenced using `{{@@ rofi.background_color @@}}`
-and `{{@@ polybar.background_color @@}}`.
+and `{{@@ polybar.background_color @@}}`.
+
+## Variables precedence
+
+* `dynvariables` > `variables`
+* Profile `(dyn)variables` > any other `(dyn)variables`
+* Profile `(dyn)variables` > profile's included `(dyn)variables`
+* Imported `(dyn)variables` > `(dyn)variables` (except for `import_configs`)
+
+When including profiles with `include`, the value of a variable present in multiple
+included profiles will come from the last profile graph in the order of the include list.
+
+In the below example, the variable value is `1`:
+```yaml
+  top:
+    variables:
+      foo: 1
+    include:
+      - left
+      - right
+  left:
+    variables:
+      foo: 2
+  right:
+    variables:
+      foo: 3
+    include:
+      - bottom
+  bottom:
+    variables:
+      foo: 4
+```
+
+In this example, its value is `4`
+```yaml
+  top:
+    include:
+      - left
+      - right
+  left:
+    variables:
+      foo: 2
+  right:
+    include:
+      - bottom
+  bottom:
+    variables:
+      foo: 4
+```
+
+See also [CONTRIBUTING doc](/CONTRIBUTING.md)

docs/howto/sharing-content.md

@@ -72,7 +72,7 @@ solution consists of using
 2. Adding some variables in the merged dotfile via templating.
 3. Overriding them with different values in each profile via profile variables.
 4. Typically, making the dotfile `dst` dynamic, as different profiles need
-    usually to deploy the dotfiles in different locations.
+    usually to deploy their dotfiles to different locations.
 
 **NOTE**: This technique does *not* require two different `dotfiles` entry in
 `config.yaml`.