README.md in tty-command-0.7.0 vs README.md in tty-command-0.8.0

@@ -50,10 +50,12 @@
   * [2.1. Run](#21-run)
   * [2.2. Run!](#22-run)
   * [2.3. Logging](#23-logging)
     * [2.3.1. Color](#231-color)
     * [2.3.2. UUID](#232-uuid)
+    * [2.3.3. Only output on error](#233-only-output-on-error)
+    * [2.3.4. Verbose](#234-verbose)
   * [2.4. Dry run](#24-dry-run)
   * [2.5. Wait](#25-wait)
   * [2.6. Test](#26-test)
   * [2.7. Ruby interpreter](#27-ruby-interpreter)
 * [3. Advanced Interface](#3-advanced-interface)
@@ -80,10 +82,12 @@
 ## 1. Usage
 
 Create a command instance and then run some commands:
 
 ```ruby
+require 'tty-command'
+
 cmd = TTY::Command.new
 cmd.run('ls -la')
 cmd.run('echo Hello!')
 ```
 
@@ -186,22 +190,63 @@
 cmd = TTY::Command.new(color: true)
 ```
 
 #### 2.3.1 Color
 
-When using printers you can switch off coloring by using `color` option set to `false`.
+When using printers you can switch off coloring by using `:color` option set to `false`.
 
 #### 2.3.2 Uuid
 
-By default when logging is enabled each log entry is prefixed by specific command run uuid number. This number can be switched off using `uuid` option:
+By default, when logging is enabled, each log entry is prefixed by specific command run uuid number. This number can be switched off using the `:uuid` option:
 
 ```ruby
-cmd = TTY::Command.new uuid: false
+cmd = TTY::Command.new(uuid: false)
 cmd.run('rm -R all_my_files')
 # => rm -r all_my_files
 ```
 
+#### 2.3.3 Only output on error
+
+When using a command that can fail, setting `:only_output_on_error` option to `true` hides the output if the command succeeds:
+
+```ruby
+cmd = TTY::Command.new
+cmd.run('non_failing_command', only_output_on_error: true)
+```
+
+This will only print the `Running` and `Finished` lines, while:
+
+```ruby
+cmd.run('non_failing_command')
+```
+
+will also print any output that the `non_failing_command` might generate.
+
+Running either:
+
+```ruby
+cmd.run('failing_command', only_output_on_error: true)
+```
+
+either:
+
+```ruby
+cmd.run('failing_command')
+```
+
+will also print the output.
+
+*Setting this option will cause the output to show at once, at the end of the command.*
+
+#### 2.3.4 Verbose
+
+By default commands will produce warnings when, for example `pty` option is not supported on a given platform. You can switch off such warnings with `:verbose` option set to `false`.
+
+```ruby
+cmd.run("echo '\e[32mColors!\e[0m'", pty: true, verbose: false)
+```
+
 ### 2.4 Dry run
 
 Sometimes it can be useful to put your script into a "dry run" mode that prints commands without actually running them. To simulate execution of the command use the `:dry_run` option:
 
 ```ruby
@@ -392,39 +437,41 @@
 cmd.run("whilte test1; sleep1; done", timeout: 5, signal: :KILL)
 ```
 
 #### 3.2.6 PTY(pseudo terminal)
 
-The `:pty` configuration option causes the command to be executed in subprocess where each stream is a pseudo terminal. By default this options is set to `false`. However, some comamnds may require a terminal like device to work correctly. For example, a command may emit colored output only if it is running via terminal.
+The `:pty` configuration option causes the command to be executed in subprocess where each stream is a `pseudo terminal`. By default this options is set to `false`.
 
-In order to run command in pseudo terminal, either set the flag globally for all commands:
+If you require to interface with interactive subprocess then setting this option to `true` will enable a `pty` terminal device. For example, a command may emit colored output only if it is running via terminal device. You may also wish to run a program that waits for user input, and simulates typing in commands and reading responses.
 
+This option will only work on systems that support BSD pty devices such as Linux or OS X, and it will gracefully fallback to non-pty device on all the other.
+
+In order to run command in `pseudo terminal`, either set the flag globally for all commands:
+
 ```ruby
 cmd = TTY::Command.new(pty: true)
 ```
 
-or for each executed command individually:
+or individually for each executed command:
 
 ```ruby
 cmd.run("echo 'hello'", pty: true)
 ```
 
-Please note though, that setting `:pty` to `true` may change how the command behaves. For instance, on unix like systems the line feed character `\n` in output will be prefixed with carriage return `\r`:
+Please note that setting `:pty` to `true` may change how the command behaves. It's important to understand the difference between `interactive` and `non-interactive` modes. For example, executing `git log` to view the commit history in default `non-interactive` mode:
 
 ```ruby
-out, _ = cmd.run("echo 'hello'")
-out # => "hello\n"
+cmd.run("git log") # => finishes and produces full output
 ```
 
-and with `:pty` option:
+However, in `interactive` mode with `pty` flag on:
 
 ```ruby
-out, _ = cmd.run("echo 'hello'", pty: true)
-out # => "hello\r\n"
+cmd.run("git log", pty: true) # => uses pager and waits for user input (never returns)
 ```
 
-In addition, any input to command may be echoed to the standard output.
+In addition, when pty device is used, any input to command may be echoed to the standard output, as well as some redirets may not work.
 
 #### 3.2.7 Current directory
 
 To change directory in which the command is run pass the `:chdir` option:
 
@@ -586,6 +633,6 @@
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
 ## Copyright
 
-Copyright (c) 2016-2017 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2016-2018 Piotr Murach. See LICENSE for further details.