From 348823eec71a5955bc6cc012d2cc5794fc797c09 Mon Sep 17 00:00:00 2001
From: deadc0de6 <info@deadc0de.ch>
Date: Thu, 25 Aug 2022 23:19:30 +0200
Subject: [PATCH] add meta profiles doc

---
 docs/config-profiles.md   |  5 ++--
 docs/howto/group-hosts.md | 58 +++++++++++++++++++++++++++++++++++++++
 mkdocs.yml                |  1 +
 3 files changed, 62 insertions(+), 2 deletions(-)
 create mode 100644 docs/howto/group-hosts.md

diff --git a/docs/config-profiles.md b/docs/config-profiles.md
index bf8a47a..c230b1f 100644
--- a/docs/config-profiles.md
+++ b/docs/config-profiles.md
@@ -6,7 +6,7 @@ Entry    | Description
 -------- | -------------
 `dotfiles` | The dotfiles associated with this profile
 `import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-profiles.md#profile-import-entry)).
-`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-profiles.md#profile-include-entry))
+`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))
@@ -39,7 +39,8 @@ 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).
+(actions, variables/dynvariables, etc). See also an example in
+[meta profiles](howto/group-hosts.md).
 
 For example:
 ```yaml
diff --git a/docs/howto/group-hosts.md b/docs/howto/group-hosts.md
new file mode 100644
index 0000000..da1aad5
--- /dev/null
+++ b/docs/howto/group-hosts.md
@@ -0,0 +1,58 @@
+# Group hosts in config and meta profiles
+
+Let's consider the situation where you have multiple hosts from different distros and you
+want an easy way to structure your config file nicely but also simplify the use
+of templates (since multiple hosts in the same distro would share the same configs parts -
+or if branch in templates).
+
+You define two types of profiles:
+
+* **Meta profiles**: for example for distros it would be something like `os_arch`, `os_debian` and so on.
+  These are never directly used for installing dotfiles but instead included by other profiles.
+* **Host profiles** (defaults to hostnames): the usual `home`, `office`, etc
+
+Each *Host profile* would include a *meta profile* and inherit all its dotfiles as well as
+it variables. For example in the *meta profile* you would define variables like `distro: debian`
+that you could use in your templates with `{%@@ if distro == "debian" @@%}` to target all
+profiles that inherit from the same *meta profile*.
+
+```yaml
+profiles:
+  meta_base:
+    dotfiles:
+    - f_zshrc
+    - f_zshrc
+  os_arch:
+    variables:
+      distro: arch
+    include:
+    - meta-base
+  os_debian:
+    variables:
+      distro: debian
+    include:
+    - meta-base
+  home:
+    include:
+    - os_arch
+    dotfiles:
+    - f_vimrc
+  office:
+    include:
+    - os_debian
+    dotfiles:
+    - f_something
+```
+
+You then have the opportunity in your templates to do the following
+that would select the if branch for all profiles inheriting from
+a specific *meta profile*.
+```
+# zsh-syntax-highlighting
+# https://github.com/zsh-users/zsh-syntax-highlighting
+{%@@ if distro == "arch" @@%}
+source /usr/share/zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
+{%@@ elif distro == "debian" @@%}
+source /usr/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
+{%@@ endif @@%}
+```
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 384eec1..cf0a440 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -28,6 +28,7 @@ nav:
   - 'HowTo':
     - 'Append text to a dotfile on install': 'howto/append.md'
     - 'Create files on install': 'howto/create-special-files.md'
+    - 'Group hosts and meta profiles': 'howto/group-hosts.md'
     - 'Handle compressed directories': 'howto/store-compressed-directories.md'
     - 'Handle secrets': 'howto/sensitive-dotfiles.md'
     - 'Handle special chars': 'howto/special-chars.md'