Rewrote readme

README.md

@@ -5,28 +5,30 @@ A Commander for modern go CLI interactions
 [![Build Status](https://travis-ci.org/spf13/cobra.png)](https://travis-ci.org/spf13/cobra)
 
 ## Overview
-Cobra provides a simple interface to create powerful modern CLI
-interfaces similar to git & go tools.
 
-Cobra was inspired by go, go-Commander, gh and subcommand
+Cobra is a commander providing a simple interface to create powerful modern CLI
+interfaces similar to git & go tools. In addition to providing an iterface, Cobra
+simultaneously provides a controller to organize your application code.
 
+Inspired by go, go-Commander, gh and subcommand, Cobra improves on these by
+providing **fully posix compliant flags** (including short & long versions),
+**nesting commands**, and the ability to **define your own help and usage** for any or
+all commands.
+
+Cobra has an exceptionally clean interface and simple design without needless
+constructors or initialization methods.
 
 ## Concepts
 
-There are 3 different core objects to become familiar with to use Cobra.
+Cobra is built on a structure of commands & flags.
-To help illustrate these 3 items better use the following as an example:
+
+**Commands** represent actions and **Flags** are modifiers for those actions.
+
+In the following example 'server' is a command and 'port' is a flag.
 
     hugo server --port=1313
 
-### Commander
+### Commands
-
-The Commander is the head of your application. It holds the configuration
-for your application. It also is responsible for all global flags.
-
-In the example above 'hugo' is the commander.
-
-
-### Command
 
 Command is the central point of the application. Each interaction that
 the application supports will be contained in a Command. A command can
@@ -34,21 +36,37 @@ have children commands and optionally run an action.
 
 In the example above 'server' is the command
 
+A Command has the following structure:
+
+    type Command struct {
+        Use string // The one-line usage message.
+        Short string // The short description shown in the 'help' output.
+        Long string // The long message shown in the 'help <this-command>' output.
+        Run func(cmd *Command, args []string) // Run runs the command.
+    }
 
 ### Flags
 
-A flag is a way to modify the behavior of an command. Cobra supports
+A Flag is a way to modify the behavior of an command. Cobra supports
-fully posix compliant flags as well as remaining consistent with
+fully posix compliant flags as well as the go flag package. 
-the go flag package. A Cobra command has can define flags that 
+A Cobra command has can define flags that persist through to children commands
-persist through to children commands and flags that are only available
+and flags that are only available to that command.
-to that command.
 
 In the example above 'port' is the flag.
 
+Flag functionality is provided by the [pflag
+libary](https://github.com/ogier/pflag), a fork of the flag standard library
+which maintains the same interface while adding posix compliance.
+
 ## Usage
 
-### Implementing Cobra
+Cobra works by creating a set of commands and then organizing them into a tree.
+The tree defines the structure of the application.
 
+Once each command is defined with it's corresponding flags, then the
+tree is assigned to the commander which is finally executed.
+
+### Installing
 Using Cobra is easy. First use go get to install the latest version
 of the library.
 
@@ -58,23 +76,81 @@ Next include cobra in your application.
 
     import "github.com/spf13/cobra"
 
-Now you are ready to implement Cobra. 
+### Create the root command
 
-Cobra works by creating a set of commands and then organizing them into a tree.
+The root command represents your binary itself.
-The tree defines the structure of the application.
 
-Once each command is defined with it's corresponding flags, then the
+Cobra doesn't require any special constructors. Simply create your commands.
-tree is assigned to the commander which is finally executed.
 
-In the example below we have defined three commands. Two are at the top
+    var HugoCmd = &cobra.Command{
-level and one (cmdTimes) is a child of one of the top commands.
+        Use:   "hugo",
+        Short: "Hugo is a very fast static site generator",
+        Long: `A Fast and Flexible Static Site Generator built with
+                love by spf13 and friends in Go.
+                Complete documentation is available at http://hugo.spf13.com`,
+        Run: func(cmd *cobra.Command, args []string) {
+            // Do Stuff Here
+        },
+    }
+
+### Create additional commands
+
+Additional commands can be defined.
+
+    var versionCmd = &cobra.Command{
+        Use:   "version",
+        Short: "Print the version number of Hugo",
+        Long:  `All software has versions. This is Hugo's`,
+        Run: func(cmd *cobra.Command, args []string) {
+            fmt.Println("Hugo Static Site Generator v0.9 -- HEAD")
+        },
+    }
+
+### Attach command to it's parent
+In this example we are attaching it to the root, but commands can be attached at any level.
+
+	HugoCmd.AddCommand(versionCmd)
+
+### Assign flags to a command
+
+Since the flags are defined and used in different locations, we need to define a variable outside with the correct scope to assign the flag to work with.
+
+    var Verbose bool
+    var Source string
+
+There are two different approaches to assign a flag.
+
+#### Persistent Flags
+
+A flag can be 'persistent' meaning that this flag will be available to the
+command it's assigned to as well as every command under that command. For
+global flags assign a flag as a persistent flag on the root.
+
+	HugoCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")
+
+#### Local Flags
+
+A flag can also be assigned locally which will only apply to that specific command.
+
+	HugoCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")
+
+### Once all commands and flags are defined, Execute the commands
+
+Execute should be run on the root for clarity, though it can be called on any command.
+
+    HugoCmd.Execute()
+
+## Example
+
+In the example below we have defined three commands. Two are at the top level
+and one (cmdTimes) is a child of one of the top commands. In this case the root
+is not executible meaning that a subcommand is required. This is accomplished
+by not providing a 'Run' for the 'rootCmd'.
 
 We have only defined one flag for a single command.
 
 More documentation about flags is available at https://github.com/spf13/pflag
 
-## Example
-
     Import(
         "github.com/spf13/cobra"
         "fmt"
@@ -119,17 +195,150 @@ More documentation about flags is available at https://github.com/spf13/pflag
             },
         }
 
-
         cmdTimes().Flags().IntVarP(&echoTimes, "times", "t", 1, "times to echo the input")
 
-        var commander = cobra.NewCommander()
+        var rootCmd = &cobra.Command{Use: "app"}
-        commander.SetName("CobraExample")
+        rootCmd.AddCommand(cmdPrint, cmdEcho)
-        commander.AddCommand(cmdPrint, cmdEcho)
         cmdEcho.AddCommand(cmdTimes)
-        commander.Execute()
+        rootCmd.Execute()
     }
 
+For a more complete example of a larger application, please checkout [Hugo](http://hugo.spf13.com)
+
+## The Help Command
+
+Cobra automatically adds a help command to your application.
+This will be called when a user runs 'app help'. Additionally help will also
+support all other commands as input. Say for instance you have a command called
+'create' without any additional configuration cobra will work when 'app help
+create' is called.
+
+### Example
+
+The following output is automatically generated by cobra. Nothing beyond the
+command and flag definitions are needed.
+
+    > hugo help
+
+    A Fast and Flexible Static Site Generator built with
+    love by spf13 and friends in Go.
+
+    Complete documentation is available at http://hugo.spf13.com
+
+    Usage:
+      hugo [flags]
+      hugo [command]
+
+    Available Commands:
+      server          :: Hugo runs it's own a webserver to render the files
+      version         :: Print the version number of Hugo
+      check           :: Check content in the source directory
+      benchmark       :: Benchmark hugo by building a site a number of times
+      help [command]  :: Help about any command
+
+     Available Flags:
+      -b, --base-url="": hostname (and path) to the root eg. http://spf13.com/
+      -D, --build-drafts=false: include content marked as draft
+          --config="": config file (default is path/config.yaml|json|toml)
+      -d, --destination="": filesystem path to write files to
+      -s, --source="": filesystem path to read files relative from
+          --stepAnalysis=false: display memory and timing of different steps of the program
+          --uglyurls=false: if true, use /filename.html instead of /filename/
+      -v, --verbose=false: verbose output
+      -w, --watch=false: watch filesystem for changes and recreate as needed
+
+    Use "hugo help [command]" for more information about that command.
+
+
+
+Help is just a command like any other. There is no special logic or behavior
+around it. In fact you can provide your own if you want.
+
+### Defining your own help
+
+You can provide your own Help command or you own template for the default command to use.
+
+The default help command is 
+
+    func (c *Command) initHelp() {
+        if c.helpCommand == nil {
+            c.helpCommand = &Command{
+                Use:   "help [command]",
+                Short: "Help about any command",
+                Long: `Help provides help for any command in the application.
+        Simply type ` + c.Name() + ` help [path to command] for full details.`,
+                Run: c.HelpFunc(),
+            }
+        }
+        c.AddCommand(c.helpCommand)
+    }
+
+You can provide your own command, function or template through the following methods.
+
+    command.SetHelpCommand(cmd *Command)
+
+    command.SetHelpFunc(f func(*Command, []string))
+
+    command.SetHelpTemplate(s string)
+
+The latter two will also apply to any children commands.
+
+
+## Usage
+
+When the user provides an invalid flag or invalid command Cobra responds by
+showing the user the 'usage'
+
+### Example
+You may recognize this from the help above. That's because the default help 
+embeds the usage as part of it's output.
+
+    Usage:
+      hugo [flags]
+      hugo [command]
+
+    Available Commands:
+      server          :: Hugo runs it's own a webserver to render the files
+      version         :: Print the version number of Hugo
+      check           :: Check content in the source directory
+      benchmark       :: Benchmark hugo by building a site a number of times
+      help [command]  :: Help about any command
+
+     Available Flags:
+      -b, --base-url="": hostname (and path) to the root eg. http://spf13.com/
+      -D, --build-drafts=false: include content marked as draft
+          --config="": config file (default is path/config.yaml|json|toml)
+      -d, --destination="": filesystem path to write files to
+      -s, --source="": filesystem path to read files relative from
+          --stepAnalysis=false: display memory and timing of different steps of the program
+          --uglyurls=false: if true, use /filename.html instead of /filename/
+      -v, --verbose=false: verbose output
+      -w, --watch=false: watch filesystem for changes and recreate as needed
+
+### Defining your own usage
+You can provide your own usage function or template for cobra to use.
+
+The default usage function is
+
+		return func(c *Command) error {
+			err := tmpl(c.Out(), c.UsageTemplate(), c)
+			return err
+		}
+
+Like help the function and template are over ridable through public methods.
+
+    command.SetUsageFunc(f func(*Command) error)
+
+    command.SetUsageTemplate(s string)
+
+
 ## Release Notes
+* **0.8.0** Nov 5, 2013
+  * Reworked interface to remove commander completely
+  * Command now primary structure
+  * No initialization needed
+  * Usage & Help templates & functions definable at any level
+  * Updated Readme
 * **0.7.0** Sept 24, 2013
   * Needs more eyes
   * Test suite
@@ -142,8 +351,6 @@ More documentation about flags is available at https://github.com/spf13/pflag
   * Implement first draft
 
 ## ToDo
-* More testing of non-runnable
-* More testing
 * Launch proper documentation site
 
 ## Contributing