5917 - Provide documentation for filters on the CLI

Document the use of filters and fix some warnings while building docs
from Jekyll

website/changelog.md

@@ -11,6 +11,7 @@ title: Changelog
 
 |Date|Description|Ticket|
 |----|-----------|------|
+|2011/04/11|Document the use filters on the CLI|5917|
 |2011/04/11|Improve handling of unknown facts in Util#has_fact? to avoid exceptions about nil#clone|6956|
 |2011/04/11|Correctly set timeout on the discovery agent to 5 seconds as default|7045|
 |2011/04/11|Let rpcutil#agent_inventory supply _unknown_ for missing values in agent meta data|7044|

website/reference/index.md

@@ -21,6 +21,7 @@ Index to basic users documentation.
 ### User Interface
 
  1. [Node Reports](ui/nodereports.html)
+ 2. [CLI Filters](ui/filters.html)
 
 ### Integration
 

website/reference/ui/filters.md

@@ -0,0 +1,101 @@
+---
+layout: default
+title: Discovery Filters
+disqus: true
+---
+
+[FactPlugin]: /mcollective/reference/plugins/facts.html
+
+# {{page.title}}
+
+ * TOC Placeholder
+ {:toc}
+
+Using filters to control discovery and addressing is a key concept in mcollective.
+You can use facts, classes, agents and server identities in filters and combine
+to narrow down what hosts you will affect.
+
+To determine if your client support filters use the _--help_ option:
+
+
+{% highlight console %}
+$ mco rpc --help
+.
+.
+.
+Host Filters
+    -W, --with FILTER                Combined classes and facts filter
+    -F, --wf, --with-fact fact=val   Match hosts with a certain fact
+    -C, --wc, --with-class CLASS     Match hosts with a certain config management class
+    -A, --wa, --with-agent AGENT     Match hosts with a certain agent
+    -I, --wi, --with-identity IDENT  Match hosts with a certain configured identity
+{% endhighlight %}
+
+If you see a section as above then the client supports filters, this is the default
+for all clients using SimpleRPC.
+
+All filters support Regular Expressions and some support comparisons like greater than
+or less than.
+
+Filters are applied in a combined manner, if you supply 5 filters they must all match
+your nodes.
+
+## Fact Filters
+
+Filtering on facts require that you've correctly set up a [FactPlugin].  The examples below
+show common fact filters.
+
+Prior to version 1.2.0 the only fact filters that were supported were equality and regular
+expressions.
+
+Install the ZSH package on machines with the fact _country=de_:
+
+{% highlight console %}
+% mco rpc package install zsh -F country=de
+{% endhighlight %}
+
+Install the ZSH package on machines where the _country_ fact starts with the letter _d_:
+
+{% highlight console %}
+% mco rpc package install zsh -F country=/^d/
+{% endhighlight %}
+
+{% highlight console %}
+% mco rpc package install zsh -F country=~^d
+{% endhighlight %}
+
+Install the ZSH package on machines with more than 2 CPUs, other available operators
+include _==, <=, >=, <, >, !=_.  For facts where the comparison and the
+actual fact is numeric it will do a numerical comparison else it wil do alphabetical:
+
+{% highlight console %}
+% mco rpc package install zsh -F "physicalprocessorcount>=2"
+{% endhighlight %}
+
+## Agent, Identity and Class filters
+
+These filters all work on the same basic pattern, they just support equality or regular
+expressions:
+
+Install ZSH on machines with hostnames starting with _web_:
+
+{% highlight console %}
+% mco rpc package install zsh -I /^web/
+{% endhighlight %}
+
+Install ZSH on machines with hostnames _web1.example.com_:
+
+{% highlight console %}
+% mco rpc package install zsh -I web1.example.com
+{% endhighlight %}
+
+## Combining Fact and Class filters
+
+As a short-hand you can combine Fact and Class filters into a single filter:
+
+Install ZSH on machines in Germany that has classes matching _/apache/_:
+
+{% highlight console %}
+% mco rpc package install zsh -W "/apache/ country=de"
+{% endhighlight %}
+

website/simplerpc/agents.md

@@ -247,7 +247,7 @@ The simplest case is just to run a command and send output back to the client:
 reply[:status] = run("echo 'hello world'", :stdout => :out, :stderr => :err)
 {% endhighlight %}
 
-Here you will have set _reply[:out]_, _reply[:err]_ and _reply[:status]_ based
+Here you will have set _reply`[`:out`]`_, _reply`[`:err`]`_ and _reply`[`:status`]`_ based
 on the output from the command
 
 You can append the output of the command to any string:
@@ -278,7 +278,7 @@ You can shorten this to:
 reply[:status] = run("echo 'hello world'", :stdout => :out, :stderr => :err, :chomp => true)
 {% endhighlight %}
 
-This will remove a trailing new line from the _reply[:out]_ and _reply[:err]_.
+This will remove a trailing new line from the _reply`[`:out`]`_ and _reply`[`:err`]`_.
 
 If you wanted this command to run from the _/tmp_ directory: