Work on OpenFact documentation

- Change wording
- Review examples and text
- Add new information

Signed-off-by: Martin Alfke <ma@betadots.de>

Author: tuxmea

docs/_openfact_5x/_facter_toc.html

@@ -3,21 +3,21 @@ layout: default
 title: "Custom facts walkthrough"
 ---
 
-[Facter 3.0.2 release notes]: ../3.0/release_notes.html#facter--p-restored
-[Plugins in Modules]: /docs/puppet/latest/plugins_in_modules.html
-[Adding plug-ins to a module]: /docs/puppet/latest/plugins_in_modules.html#adding-plug-ins-to-a-module
+[Plugins in Modules]: /openvox/latest/plugins_in_modules.html
+[Adding plug-ins to a module]: /openvox/latest/plugins_in_modules.html
+[Facts overview]: ./fact_overview.html
 
-You can add custom facts by writing snippets of Ruby code on the Puppet master. Puppet then uses [Plugins in Modules][] to distribute the facts to the client.
+You can add custom facts by adding snippets of Ruby code to the OpenVox server. OpenVox then uses [Plugins in Modules][] to distribute the facts to all agents.
 
 For information on how to add custom facts to modules, see [Adding plug-ins to a module][].
 
 ## Adding custom facts to OpenFact
 
 Sometimes you need to be able to write conditional expressions based on site-specific data that just isn't available via OpenFact, or perhaps you'd like to include it in a template.
 
-Because you can't include arbitrary Ruby code in your manifests, the best solution is to add a new fact to OpenFact. These additional facts can then be distributed to Puppet clients and are available for use in manifests and templates, just like any other fact is.
+Because you can't include arbitrary Ruby code in your manifests, the best solution is to add a new fact to OpenFact. These additional facts can then be distributed to OpenVox agent and are available for use in manifests and templates, just like any other fact is.
 
-> **Note:** Facter 3.0 removed the Ruby implementations of some features and replaced them with a [custom facts API](https://github.com/puppetlabs/facter/blob/master/Extensibility.md#custom-facts-compatibility). Any custom fact that requires one of the Ruby files previously stored in `lib/facter/util` fails with an error. For more information, see the [Facter 3.0 release notes](../3.0/release_notes.html).
+> **Note:** OpenFact provides a [custom facts API](https://github.com/openvoxproject/openfact/blob/master/Extensibility.md#custom-facts-compatibility).
 
 ## Loading custom facts
 
@@ -51,10 +51,11 @@ OpenFact can take multiple `--custom-dir` options on the command line that speci
 to search for custom facts. OpenFact attempts to load all Ruby files in the specified directories.
 This allows you to do something like this:
 
-    $ ls my_facts
-    system_load.rb
-    $ ls my_other_facts
-    users.rb
+    #~/my_facts
+    └── system_load.rb
+    #~/my_other_facts
+    └── users.rb
+
     $ facter --custom-dir=./my_facts --custom-dir=./my_other_facts system_load users
     system_load => 0.25
     users => thomas,pat
@@ -65,23 +66,17 @@ OpenFact also checks the environment variable `FACTERLIB` for a delimited (semic
 other platforms) set of directories, and tries to load all Ruby files in those directories.
 This allows you to do something like this:
 
-    $ ls my_facts
-    system_load.rb
-    $ ls my_other_facts
-    users.rb
+    #~/my_facts
+    └── system_load.rb
+    #~/my_other_facts
+    └── users.rb
+
     $ export FACTERLIB="./my_facts:./my_other_facts"
     $ facter system_load users
     system_load => 0.25
     users => thomas,pat
 
-> ### Note: Changes in built-in pluginsync support in Facter 3
->
-> Facter 2.4 **deprecated** Facter's support for loading facts via Puppet's pluginsync
-> (the `-p` option), and Facter 3.0.0 **removed** the `-p` option. However, we reversed
-> this decision in Facter 3.0.2 and re-enabled the `-p` option. For details about current
-> and future support for this option, see the [Facter 3.0.2 release notes][].
-
-## Two parts of every fact
+## Two parts of every custom fact
 
 Most facts have at least two elements:
 
@@ -90,16 +85,20 @@ Most facts have at least two elements:
 
 Facts *can* get a lot more complicated than that, but those two together are the most common implementation of a custom fact.
 
-## Executing shell commands in facts
+## Executing shell commands in custom facts
 
-Puppet gets information about a system from OpenFact, and the most common way for OpenFact to
+OpenVox gets information about a system from OpenFact, and the most simple way for OpenFact to
 get that information is by executing shell commands. You can then parse and manipulate the
-output from those commands using standard Ruby code. The OpenFact API gives you a few ways to
+output from those commands using standard Ruby code.
+
+> **Note:** However, it is important to also ceck if any of the OpenVox agent bundled Ruby Libraries can be used.
+
+The OpenFact API gives you a few ways to
 execute shell commands:
 
--   To run a command and use the output verbatim, as your fact's value, you can pass the command into `setcode` directly. For example: `setcode 'uname --hardware-platform'`
--   If your fact is more complicated than that, you can call `Facter::Core::Execution.execute('uname --hardware-platform')` from within the `setcode do`...`end` block. Whatever the `setcode` statement returns is used as the fact's value.
--   Your shell command is also a Ruby string, so you need to escape special characters if you want to pass them through.
+- To run a command and use the output verbatim, as your fact's value, you can pass the command into `setcode` directly. For example: `setcode 'uname --hardware-platform'`
+- If your fact is more complicated than that, you can call `Facter::Core::Execution.execute('uname --hardware-platform')` from within the `setcode do`...`end` block. Whatever the `setcode` statement returns is used as the fact's value.
+- Your shell command is also a Ruby string, so you need to escape special characters if you want to pass them through.
 
 > **Note:** Not everything that works in the terminal works in a fact. You can use the pipe (`|`) and similar operators as you normally would, but Bash-specific syntax like `if` statements do not work. The best way to handle this limitation is to write your conditional logic in Ruby.
 
@@ -109,10 +108,10 @@ To get the output of `uname --hardware-platform` to single out a specific type o
 
 1.  Start by giving the fact a name, in this case, `hardware_platform`.
 
-2.  Create your new fact in a file, `hardware_platform.rb` on the Puppet master server:
+2.  Create your new fact in a file, `hardware_platform.rb` on an OpenVox agent system:
 
     ``` ruby
-    # hardware_platform.rb
+    #~/my_facts/hardware_platform.rb
 
     Facter.add('hardware_platform') do
       setcode do
@@ -121,19 +120,19 @@ To get the output of `uname --hardware-platform` to single out a specific type o
     end
     ```
 
-3.  Use the instructions in the [Plugins in Modules][] page to copy the new fact to a module and distribute it. During your next Puppet run, the value of the new fact is available to use in your manifests and templates.
+3.  Use the instructions in the [Plugins in Modules][] page to copy the new fact to a module and distribute it. During your next OpenVox run, the value of the new fact is available to use in your manifests and templates.
 
-## Using other facts
+## Accessing other facts
 
-You can write a fact that uses other facts by accessing `Facter.value(:somefact)`.
+You can write a custom fact that uses other facts by accessing `Facter.value(:somefact)`.
 If the fact fails to resolve or is not present, OpenFact returns `nil`.
 
 For example:
 
 ``` ruby
 Facter.add(:osfamily) do
   setcode do
-    distid = Facter.value(:lsbdistid)
+    distid = Facter.value(:os)['family']
     case distid
     when /RedHatEnterprise|CentOS|Fedora/
       'redhat'
@@ -146,11 +145,11 @@ Facter.add(:osfamily) do
 end
 ```
 
-## Configuring facts
+## Configuring custom facts
 
 Facts have a few properties that you can use to customize how they are evaluated.
 
-### Confining facts
+### Confining custom facts
 
 One of the more commonly used properties is the `confine` statement, which
 restricts the fact to only run on systems that matches another given fact.
@@ -174,7 +173,9 @@ available on the given system. Since this is only available on Linux systems,
 we use the `confine` statement to ensure that this fact isn't needlessly run on
 systems that don't support this type of enumeration.
 
-### Fact precedence
+> **Note:** More information on other ways to confine. e.g. files present can be found a the [Facts overview]
+
+### Custom facts precedence
 
 A single fact can have multiple **resolutions**, each of which is a different way
 of ascertaining what the value of the fact should be. It's very common to have
@@ -221,7 +222,9 @@ Facter.add(:role) do
 end
 ```
 
-### Execution timeouts
+> **Hint:** A weight above 1000 overwrites external facts
+
+### Custom facts execution timeouts
 
 Although this version of OpenFact does not support overall timeouts on resolutions, you can pass a timeout
 to `Facter::Core::Execution#execute`:
@@ -239,11 +242,11 @@ Facter.add(:sleep) do
 end
 ```
 
-## Structured facts
+## Structured custom facts
 
 Structured facts take the form of either a hash or an array. To create a structured fact, return a hash or an array from the `setcode` statement.
 
-You can see some relevant examples in the [writing structured facts](./fact_overview.html#writing-structured-facts) section of the [Fact Overview](./fact_overview.html).
+You can see some relevant examples in the [writing structured facts](./fact_overview.html#writing-structured-facts) section of the [Facts overview].
 
 ## Aggregate resolutions
 
@@ -287,21 +290,21 @@ end
 
 If the `chunk` blocks all return arrays or hashes, you can omit the `aggregate` block. If you do, OpenFact automatically merges all of your data into one array or hash and uses that as the fact's value.
 
-For more examples of aggregate resolutions, see the [aggregate resolutions](./fact_overview.html#writing-facts-with-aggregate-resolutions) section of the [Fact Overview](./fact_overview.html) page.
+For more examples of aggregate resolutions, see the [aggregate resolutions](./fact_overview.html#writing-facts-with-aggregate-resolutions) section of the [Fact overview] page.
 
 ## Viewing fact values
 
-[puppetdb]: /puppetdb/latest
+[OpenVox-DB]: /openvoxdb/latest
 
-If your Puppet masters are configured to use [PuppetDB][puppetdb], you can view and search all of the facts for any node, including custom facts. See [the PuppetDB docs][puppetdb] for more info.
+If your Puppet masters are configured to use [OpenVox-DB][OpenVox-DB], you can view and search all of the facts for any node, including custom facts. See [the OpenVox-DB docs][openvoxdb] for more info.
 
 ## External facts
 
 ### What are external facts?
 
 External facts provide a way to use arbitrary executables or scripts as facts, or set facts statically with structured data. If you've ever wanted to write a custom fact in Perl, C, or a one-line text file, this is how.
 
-### Executable facts --- Unix
+### Executable external facts --- Unix
 
 Executable facts on Unix work by dropping an executable file into the standard
 external fact path. A shebang (`#!`) is always required for executable facts on Unix. If the shebang is missing, the execution of the fact fails.
@@ -329,7 +332,7 @@ STDOUT in the format:
 
 Using this format, a single script can return multiple facts.
 
-### Executable facts --- Windows
+### Executable external facts --- Windows
 
 Executable facts on Windows work by dropping an executable file into the external fact path. Unlike with Unix, the external facts interface expects Windows scripts to end with a known extension. Line endings can be either `LF` or `CRLF`. The following extensions are currently supported:
 
@@ -345,11 +348,11 @@ As with Unix facts, each script must return key/value pairs on STDOUT in the for
 
 Using this format, a single script can return multiple facts in one return.
 
-#### Executable fact locations
+#### Executable eternal fact locations
 
-The best way to distribute external executable facts is with pluginsync, which added support for them in [Puppet 3.4] (/puppet/3/reference/release_notes.html#preparations-for-syncing-external-facts)/[Facter 2.0.1](../2.0/release_notes.html#pluginsync-for-external-facts). To add external executable facts to your Puppet modules, just place them in <MODULEPATH>/<MODULE>/facts.d/.
+The best way to distribute external executable facts is with pluginsync, To add external executable facts to your OpenVox modules, just place them in <MODULEPATH>/<MODULE>/facts.d/.
 
-If you're not using pluginsync, then external facts must go in a standard directory. The location of this directory varies depending on your operating system, whether your deployment uses Puppet Enterprise or open source releases, and whether you are running as root/Administrator. When calling facter from the command line, you can specify the external facts directory with the `--external-dir` option.
+If you're not using pluginsync, then external facts must go in a standard directory. The location of this directory varies depending on your operating system and whether you are running as root/Administrator. When calling OpenFact from the command line, you can specify the external facts directory with the `--external-dir` option.
 
 > **Note:** These directories don't necessarily exist by default; you may need to create them. If you create the directory, make sure to restrict access so that only Administrators can write to the directory.
 
@@ -371,9 +374,9 @@ When running as a non-root / non-Administrator user:
 
     <HOME DIRECTORY>/.facter/facts.d/
 
-> **Note:** You can only use custom facts as a non-root user if you have first [configured non-root user access]({{pe}}/deploy_nonroot-agent.html) and previously run Puppet agent as that same user.
+> **Note:** You can only use custom facts as a non-root user if you have previously run OpenVox agent as that same user.
 
-#### Batch scripts
+#### Windows batch scripts
 
 The file encoding for `.bat/.cmd` files must be `ANSI` or `UTF8 without BOM` (Byte Order Mark), otherwise you may get strange output.
 
@@ -398,7 +401,7 @@ Here is a sample PowerShell script which outputs facts using the required format
 
 You should be able to save and execute this PowerShell script on the command line.
 
-### Structured data facts
+### Structured data based external facts
 
 OpenFact can parse structured data files stored in the external facts directory and set facts based on their contents.
 
@@ -433,7 +436,7 @@ key3=value3
 
 As with executable facts, structured data files can set multiple facts at once.
 
-``` javascript
+``` json
 {
   "datacenter":
   {
@@ -449,14 +452,14 @@ As with executable facts, structured data files can set multiple facts at once.
 }
 ```
 
-#### Structured data facts on Windows
+#### Structured data based external facts on Windows
 
 All of the above types are supported on Windows with the following caveats:
 
 -   The line endings can be either `LF` or `CRLF`.
 -   The file encoding must be either `ANSI` or `UTF8 without BOM` (Byte Order Mark).
 
-### Troubleshooting
+### Troubleshooting external facts
 
 If your external fact is not appearing in OpenFact's output, running
 OpenFact in debug mode should give you a meaningful reason and tell you which file is causing the problem:
@@ -489,7 +492,7 @@ found in the `stdlib` module.
 
 ### Drawbacks
 
-While external facts provide a mostly-equal way to create variables for Puppet, they have a few drawbacks:
+While external facts provide a mostly-equal way to create variables for OpenVox, they have a few drawbacks:
 
 -   An external fact cannot internally reference another fact. However, due to parse order, you can reference an external fact from a Ruby fact.
 -   External executable facts are forked instead of executed within the same process.

docs/_openfact_5x/custom_facts.md

@@ -5,7 +5,9 @@ title: "Documentation index"
 
 OpenFact is OpenVox's cross-platform system profiling library. It discovers and reports per-node facts, which are available in your OpenVox manifests as variables.
 
-* [The list of core facts](./core_facts.html) lists and describes every built-in fact that ships with OpenFact.
+* [The OpenFact release notes](./release_notes.html) document OpenFact's history.
+* [The CLI](./cli.html) lists and describes the command line interface usage and options for OpenFact (auto-generated).
+* [The list of core facts](./core_facts.html) lists and describes every built-in fact that ships with OpenFact (auto-generated).
 * [The custom fact reference](./fact_overview.html) serves as an example-driven primer and quick reference for fact authors.
 * [The custom facts walkthrough](./custom_facts.html) explains in detail how to write and distribute your own custom or external facts.
-* [The OpenFact release notes](./release_notes.html) document OpenFact's history.
+* [The configuration file options](./configuring_openfact.html) explains in detail how to configure the behavior of OpenFact.