README cleanup, fixes #17

README.md

@@ -9,17 +9,12 @@ hss
 
 SSH helper that uses regex and fancy expansion to dynamically manage SSH shortcuts
 
-## Usage
-
-1. Install as per the Installation section below
-2. Set your configuration yaml up as desired (See Configuration below)
-3. Run `hss help` for a list of available commands
-4. Run `hss $command` to do that thing
-
 ## Installation
 
-    gem install hss
-    ln -s /path/to/your/config.yml ~/.hss.yml
+```
+gem install hss
+ln -s /path/to/your/config.yml ~/.hss.yml
+```
 
 ## Configuration
 
@@ -31,26 +26,50 @@ SSH helper that uses regex and fancy expansion to dynamically manage SSH shortcu
     * Use matching to collect things you want to use in the expanded form
   * long: Expanded form of this shortcut ("root@#$1.example.org")
     * This will be evaluated using Ruby's string interpolation, so you can use "#{var}", "#$1", "#{function()}", etc.
-3. Other helpers are available for use in long forms
-  * expand(x): Uses the "expansions" section of the config. Format for this section is a hash of lists, as such
-    expansions:
-        expanded_form:
-            - short_form1
-            - short_form2
-            - shrtfrm3
+3. Helpers are available for use in long forms
+  * expand(x): Uses the "expansions" section of the config. Format for this section is a hash of lists, as such:
+
+```
+expansions:
+    expanded_form:
+        - short_form1
+        - short_form2
+        - shrtfrm3
+```
+
   * shortcut(x): Uses the "shortcuts" section of the config. Format for this section is a hash of strings, as such
-    shortcuts:
-        short1: expand to this
-        other_short: 'expand to something else!'
+
+```
+shortcuts:
+    short1: expand to this
+    other_short: 'expand to something else!'
+```
+
   * command(x): Runs the given string as a command and uses the output for the expanded form
   * default(x, y): If x is not nil, uses x. If it's nil, use y
+  * external(source, key): Loads source as a YAML file and looks for the given key. The YAML should be made of hashes (you can nest them) and the key should be dot-separated:
+
+```
+fish:
+    color: blue # accessible with key = 'fish.color'
+    alpha:
+        dog: sparky
+        cat: grouchy # accessible with key 'fish.alpha.cat'
+```
+
+## Usage
+
+1. Run `hss help` for a list of available commands
+2. Run `hss $command` to do that thing
 
 ## Debugging
 
 If you want hss to print the command it would have run rather than executing it, you just need to set the HSS\_DEBUG environment variable to something:
 
-    export HSS_DEBUG=foo
-    hss bar # will print rather than exec
+```
+export HSS_DEBUG=foo
+hss bar # will print rather than exec
+```
 
 ## License