Merge pull request #8818 from BobosilaVictor/PUP-10151/update-documentation-lookup

(PUP-10151) Update man page for the puppet lookup command

Author: ciprianbadescu

lib/puppet/application/lookup.rb

@@ -134,7 +134,9 @@ def help
 The lookup command is a CLI for Puppet's 'lookup()' function. It searches your
 Hiera data and returns a value for the requested lookup key, so you can test and
 explore your data. It is a modern replacement for the 'hiera' command.
-
+Lookup uses the setting for global hiera.yaml from puppet's config,
+and the environment to find the environment level hiera.yaml as well as the
+resulting modulepath for the environment (for hiera.yaml files in modules).
 Hiera usually relies on a node's facts to locate the relevant data sources. By
 default, 'puppet lookup' uses facts from the node you run the command on, but
 you can get data for any other node with the '--node <NAME>' option. If
@@ -183,7 +185,8 @@ def help
 * --environment <ENV>
   Like with most Puppet commands, you can specify an environment on the command
   line. This is important for lookup because different environments can have
-  different Hiera data.
+  different Hiera data. This environment will be always be the one used regardless
+  of any other factors.
 
 * --merge first|unique|hash|deep:
   Specify the merge behavior, overriding any merge behavior from the data's
@@ -234,6 +237,13 @@ def help
   To look up 'key_name' using the Puppet Server node's facts:
   $ puppet lookup key_name
 
+  To look up 'key_name' using the Puppet Server node's arbitrary variables from a manifest, and 
+  classify the node if applicable:
+  $ puppet lookup key_name --compile
+
+  To look up 'key_name' using the Puppet Server node's facts, overridden by facts given in a file:
+  $ puppet lookup key_name --facts fact_file.yaml
+
   To look up 'key_name' with agent.local's facts:
   $ puppet lookup --node agent.local key_name