fix: mention to example files and wording

README.md

@@ -63,45 +63,44 @@ sudo qubesctl state.apply dotfiles.copy-dom0,dotfiles.copy-sh,dotfiles.copy-vim,
 
 #### Pillar
 
-With salt, each state execution can be opt out by topic via a corresponding
-pillar set to a non true value (eg: Setting qusal:dotfiles:dom0 to false will
-disable states specific to dom0, setting qusal:dotfiles:git to false will
-disable states specific to git).
+By default, all states are executed when applied.  This can be deactivated in
+full or in part by configuring the corresponding pillar data to a non true
+value.
 
 You will need a top file and a sls file in your pillar_roots, when following
 [the Qusal's installation instructions](https://github.com/ben-grande/qusal/blob/main/docs/INSTALL.md),
 `/srv/pillar/qusal` will be added to you pillar_roots.
 
-By default, the formulas assume that you opt-in for all dotfiles.
-
-Example: /srv/pillar/qusal/dotfiles.top:
+Example: `/srv/pillar/qusal/dotfiles.top`
 
 ```yaml
 base:
   '*':
     - qusal.dotfiles
 ```
 
-It will apply the qusal/dotfiles sls to all targets.
+It will apply the `qusal/dotfiles.sls` on all targets.
 
-Example: /srv/pillar/qusal/dotfiles.sls containing the data to pass to the
-targets:
+Example: `/srv/pillar/qusal/dotfiles.sls`:
 
 ```yaml
 qusal:
   dotfiles:
     dom0: false
 ```
 
-It will disable the dom0 dotfiles configuration.
+This will disable the dom0 dotfiles configuration.
+
+For a complete example of a pillar state and a listing of their corresponding
+formulas states, please refer to `pillar.sls.example`.
 
 Enable the pillar top above:
 
 ```sh
 sudo qubesctl top.enable qusal.dotfiles pillar=true
 ```
 
-Now subsequent calls to the states of this repository will skip copy-dom0.
+Now subsequent calls to the states of this repository will skip `copy-dom0.sls`.
 
 ### Script
 

pillar.sls.example

@@ -12,37 +12,28 @@ extension and referenced by a top file. See 'pillar.top.example' for an example
 and the README for instructions.
 
 Each entry in the pillar state is optional. You can disable the entire dotfile
-setup by keeping only 'qusal:dotfiles:all' to 'false', or selectively disable
-individual components by setting 'false' for the corresponding state entries.
+setup by keeping *only* 'qusal:dotfiles:all' to 'false', or selectively
+disabling individual components by setting 'false' for the corresponding state
+entries (eg: 'dom0' correspond to 'copy-dom0.sls').
+
+Alternatively you can keep 'qusal:dotfiles:all' to 'true' and selectively
+enabling individual components by setting 'true' for the corresponding state
+entries.
 
 #}
 
 qusal:
   dotfiles:
-    # Control whether or not applying the copy-all.sls or any other dotfiles states.
-    # Disabling it will disable all states, unless some are specifically whitelisted.
     all: true
-    # Control whether or not applying the copy-x11.sls state.
     dom0: true
-    # Control whether or not applying the copy-dom0.sls state.
     git: true
-    # Control whether or not applying the copy-git.sls state.
     gtk: true
-    # Control whether or not applying the copy-gtk.sls state.
     mutt: true
-    # Control whether or not applying the copy-mutt.sls state.
     net: true
-    # Control whether or not applying the copy-net.sls state.
     pgp: true
-    # Control whether or not applying the copy-pgp.sls state.
     sh: true
-    # Control whether or not applying the copy-sh.sls state.
     ssh: true
-    # Control whether or not applying the copy-ssh.sls state.
     tmux: true
-    # Control whether or not applying the copy-tmux.sls state.
     vim: true
-    # Control whether or not applying the copy-vim.sls state.
     x11: true
-    # Control whether or not applying the copy-x11.sls state.
     xfce: true

pillar.top.example

@@ -7,8 +7,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 Example of a pillar top structure for https://github.com/ben-grande/dotfiles
 
-This file need to be placed in your pillar_roots, renamed with a '.top'
-extension, to refer to a valid pillar state file and enabled with 'qubectl
+This file needs to be placed in your pillar_roots, renamed with a '.top'
+extension, to refer to a valid pillar state file and enabled with 'qubesctl
 top.enable'. See 'pillar.sls.example' for an example and the README for
 instructions.