From 2f95fca1c4f96195b243ea66baaf35b8b3e750b9 Mon Sep 17 00:00:00 2001
From: Tim Byrne <sultan@locehilios.com>
Date: Tue, 31 Jan 2017 17:29:45 -0600
Subject: [PATCH] Update web documentation for alternates

---
 _docs/040_alternates.md | 55 +++++++++++++++++++++++++++++++++--------
 1 file changed, 45 insertions(+), 10 deletions(-)

diff --git a/_docs/040_alternates.md b/_docs/040_alternates.md
index 589d47e..29d57dd 100644
--- a/_docs/040_alternates.md
+++ b/_docs/040_alternates.md
@@ -15,10 +15,14 @@ feature which will automatically create a symbolic link to the appropriate
 version of a file, as long as you follow a specific naming convention. **yadm** can
 detect files with names ending in:
 
-| `##`                 | Default file linked             |
-| `##OS`               | Matching OS                     |
-| `##OS.HOSTNAME`      | Matching OS & Hostname          |
-| `##OS.HOSTNAME.USER` | Matching OS, Hostname, and User |
+| `##`                       | Default file linked                  |
+| `##CLASS`                  | Matching Class                       |
+| `##CLASS.OS`               | Matching Class & OS                  |
+| `##CLASS.OS.HOSTNAME`      | Matching Class, OS & Hostname        |
+| `##CLASS.OS.HOSTNAME.USER` | Matching Class, OS, Hostname, & User |
+| `##OS`                     | Matching OS                          |
+| `##OS.HOSTNAME`            | Matching OS & Hostname               |
+| `##OS.HOSTNAME.USER`       | Matching OS, Hostname, & User        |
 
 If there are any files managed by **yadm**'s repository, or listed in
 `$HOME/.yadm/encrypt`, which match this naming convention, symbolic links will
@@ -26,6 +30,7 @@ be created for the most appropriate version. This may best be demonstrated by
 example. Assume the following files are managed by **yadm**'s repository:
 
     $HOME/path/example.txt##
+    $HOME/path/example.txt##Work
     $HOME/path/example.txt##Darwin
     $HOME/path/example.txt##Darwin.host1
     $HOME/path/example.txt##Darwin.host2
@@ -43,7 +48,7 @@ which looks like this:
 
 `$HOME/path/example.txt` → `$HOME/path/example.txt##Darwin`
 
-Since the hostname doesn't match any of the  managed  files,  the  more generic
+Since the host name doesn't match any of the  managed  files,  the  more generic
 version is chosen.
 
 If running on a Linux server named `host4`, the link will be:
@@ -54,13 +59,43 @@ If running on a Solaris server, the link use the default `##` version:
 
 `$HOME/path/example.txt` → `$HOME/path/example.txt##`
 
-If no `##` version exists and no files match the current OS/HOST- NAME/USER,
+If running on a system, with `CLASS` set to "Work" ([see below](alternates#class-and-overrides)), the link will be:
+
+`$HOME/path/example.txt` → `$HOME/path/example.txt##Work`
+
+If no `##` version exists and no files match the current CLASS/OS/HOSTNAME/USER,
 then no link will be created.
 
-| OS is determined by running `uname -s`, HOSTNAME by running `hostname -s`, and
-USER by running `id -u -n`. **yadm** will automatically create these links by
-default. This can be disabled using the `yadm.auto-alt` configuration. Even if
-disabled, links can be manually created by running **yadm** alt.
+| **CLASS** must be manually set using `yadm config local.class <class>`.
+| **OS** is determined by running `uname -s`.
+| **HOSTNAME** by running `hostname` and removing any domain.
+| **USER** by running `id -u -n`.
+
+**yadm** will automatically create these links by default. This can be disabled using the `yadm.auto-alt` configuration. Even if disabled, links can be manually created by running **yadm** alt.
+
+## Wildcards
+
+It is possible to use `%` as a "wildcard" in place of `CLASS`, `OS`, `HOSTNAME`,
+or `USER`. For example, The following file could be linked for *any host* when the
+user is "harvey".
+
+```
+$HOME/path/example.txt##%.%.harvey
+```
+
+## Class and Overrides
+
+Class is a special value which is stored locally on each host (inside the local
+repository). To use alternate symlinks using `CLASS`, you must set the value of
+class using the configuration `local.class`. This is set like any other **yadm**
+configuration—with the `yadm config` command. The following sets the `CLASS` to
+be "Work".
+
+    yadm config local.class Work
+
+Similarly, the values of `OS`, `HOSTNAME`, and `USER` can be manually
+overridden using the configuration options `local.os`, `local.hostname`, and
+`local.user`.
 
 ## Strategies for alternate files on different systems