update Readme

Readme.md

@@ -1,6 +1,53 @@
 # Personal dotfiles (eg .config)
 
-The files here are structured for compatibility with stow.
+The files here are structured for compatibility with stow to keep things as
+simple as possible and reduce reliance on custom logic.
+
+The config for each program is stored in a single subdirectory (a
+[package](#packages)).
+
+I've added the notion of package [targets](#targets) to handle config for
+programs that do not store all config in a single location.
+
+# Packages
+
+All config files for a specific program are kept together in a package.
+
+* Each subdirectory of this repo represents a different dotfiles package.
+* The directory structure is compatible with GNU stow.
+
+There is a custom wrapper bash script (uses GNU Stow) that you can use to easily
+install a config package:
+
+*Example* Install the config for the `vim` package:
+```bash
+./dot apply vim
+```
+
+Or, if the `vim` package has no other [targets](#targets), you can use GNU Stow directly:
+```
+stow -t "$HOME" vim
+```
+
+Multiple [targets](#targets) are supported in the case a given package has a mix of user config and system config.
+
+*Example* Install only system config for the `ssh` package:
+```bash
+./dot apply ssh system
+```
+
+*Example* Install all config for the `ssh` package:
+```bash
+./dot apply ssh
+```
+
+You can still use GNU Stow directly, with just a minor tweak to the stow options to support the multi-target directory structure:
+```
+stow -d ssh -t "/" system
+stow -d ssh -t "$HOME" user
+```
+NOTE: the package name is now passed to stow as the stow directory and the
+package target is passed as the package name.
 
 # Targets
 
@@ -28,7 +75,6 @@ Therefore, each package may have a subdirectory containing any of:
     └── .vimrc
 ```
 
-
 In the case no target subdirectories are present for a given package, then the target is assumed to be the `user` target.
 
 More targets may be added in the future:
@@ -41,11 +87,11 @@ More targets may be added in the future:
 
 For now, to ensure maximum compatibility, it's more flexable to require each package to supply the specific heirarchy.
 
-## User
+## User Target
 
 All directories under the user target are relative to `$HOME`.
 
-*Example* Stow all `vim` config at `/home/acme/`:
+*Example* Stow the `.vimrc` at `$HOME`:
 ```bash
 ./dot apply vim
 ```
@@ -56,11 +102,11 @@ On GNU compatible system this is equivalent to:
 stow -d "$DOTFILES_DIR" -t "/home/$USER" vim
 ```
 
-## System
+## System Target
 
 All directories under the system targt are relative to `/`.
 
-*Example* Stow system/user `ssh` config at `/home/acme/` and `/` respectively:
+*Example* Stow system/user `ssh` config at `$HOME` and `/` respectively:
 ```bash
 ./dot apply ssh
 ```