[CHEF-2201] start a manpage for shef.

1 files changed, 99 insertions, 0 deletions

diff --git a/chef/distro/common/markdown/man1/shef.mkd b/chef/distro/common/markdown/man1/shef.mkd
new file mode 100644
index 0000000000..064925debd
--- /dev/null
+++ b/chef/distro/common/markdown/man1/shef.mkd
@@ -0,0 +1,99 @@
+shef(1) -- Interactive Chef Console
+========================================
+
+## SYNOPSIS
+
+__shef__ [_named configuration_] _(options)_
+
+  * `-S`, `--server CHEF_SERVER_URL`:
+    The chef server URL
+  * `-z`, `--client`:
+    chef-client mode
+  * `-c`, `--config CONFIG`:
+    The configuration file to use
+  * `-j`, `--json-attributes JSON_ATTRIBS`:
+    Load attributes from a JSON file or URL
+  * `-l`, `--log-level LOG_LEVEL`:
+    Set the logging level
+  * `-s`, `--solo`:
+    chef-solo shef session
+  * `-a`, `--standalone`:
+    standalone shef session
+  * `-v`, `--version`:
+    Show chef version
+  * `-h`, `--help`:
+    Show command options
+
+When no CONFIG is specified, shef attempts to load a default configuration file:
+* If a _named configuration_ is given, shef will load ~/.chef/_named
+  configuration_/shef.rb
+* If no _named configuration_ is given shef will load ~/.chef/shef.rb if it exists
+* Shef falls back to loading /etc/chef/client.rb or /etc/chef/solo.rb if -z or
+  -s options are given and no shef.rb can be found.
+* The --config option takes precedence over implicit configuration
+  paths.
+
+## DESCRIPTION
+
+`shef` is an irb(1) (interactive ruby) session customized for Chef.
+`shef` serves two primary functions: it provides a means to
+interact with a Chef Server interactively using a convenient DSL; it
+allows you to define and run Chef recipes interactively.
+
+## SYNTAX
+Shef uses irb's subsession feature to provide multiple modes of
+interaction. The following commands are available in the primary
+session:
+
+  * `help`:
+    Prints a list of available commands
+  * `version`:
+    Prints the Chef version
+  * `recipe`:
+    Switches to `recipe` mode
+  * `run_chef`:
+    Initiates a chef run
+  * `reset`:
+    reinitializes shef
+  * `echo :on|:off`:
+    Turns irb's echo function on or off. Echo is _on_ by default.
+  * `tracing :on|:off`:
+    Turns irb's function tracing feature on or off. Tracing is extremely
+    verbose and expected to be of interest primarily to developers.
+  * `node`:
+    Returns the _node_ object for the current host. See knife-node(1)
+    for more information about nodes.
+  * `ohai`:
+    Prints the attributes of _node_
+
+In addition to these commands, shef provides a DSL for accessing data on
+the Chef Server.
+
+## BUGS
+The name `shef` looks very clever in print but is confusing when spoken
+aloud.
+
+`shef` often does not perfectly replicate the context in which
+chef-client(8) configures a host, which may lead to discrepancies in
+observed behavior.
+
+`shef` has to duplicate much code from chef-client's internal libraries
+and may become out of sync with the behavior of those libraries.
+
+## SEE ALSO
+  chef-client(8) knife(1)
+
+## AUTHOR
+   Chef was written by Adam Jacob <adam@opscode.com> with many
+   contributions from the community. Shef was written by Daniel DeLeo.
+
+## DOCUMENTATION
+   This manual page was written by Daniel DeLeo <dan@opscode.com>.
+   Permission is granted to copy, distribute and / or modify this
+   document under the terms of the Apache 2.0 License.
+
+## CHEF
+   Shef is distributed with Chef. <http://wiki.opscode.com/display/chef/Home>
+
+
+