Update release notes for 0.3.1

* update README
* update man page
* fix doc errors

Change-Id: I5682654bf482289879c8ba9016e348f2b2782971

1 files changed, 74 insertions, 33 deletions

diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst
index 3a780e24..74db6815 100644
--- a/doc/source/man/openstack.rst
+++ b/doc/source/man/openstack.rst
@@ -18,7 +18,7 @@ DESCRIPTION
 ===========
 
 :program:`openstack` provides a common command-line interface to OpenStack APIs.  It is generally
-equivalent to the CLIs provided by the OpenStack project client librariess, but with
+equivalent to the CLIs provided by the OpenStack project client libraries, but with
 a distinct and consistent command structure.
 
 :program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with
@@ -37,49 +37,51 @@ command line.  The primary difference is the use of 'project' in the name of the
 OPTIONS
 =======
 
+:program:`openstack` takes global options that control overall behaviour and command-specific options that control the command operation.  Most global options have a corresponding environment variable that may also be used to set the value. If both are present, the command-line option takes priority. The environment variable names are derived from the option name by dropping the leading dashes ('--'), converting each embedded dash ('-') to an underscore ('_'), and converting to upper case.
+
 :program:`openstack` recognizes the following global topions:
 
-:option:`--os-auth-url <auth-url>`
+:option:`--os-auth-url` <auth-url>
     Authentication URL
 
-:option:`--os-project-name <auth-project-name>`
-    Authentication project name (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied)
+:option:`--os-domain-name` <auth-domain-name> | :option:`--os-domain-id` <auth-domain-id>
+    Domain-level authorization scope (name or ID)
+
+:option:`--os-project-name` <auth-project-name> | :option:`--os-project-id` <auth-project-id>
+    Project-level authentication scope (name or ID)
 
-:option:`--os-project-id <auth-project-id>`
-    Authentication tenant ID  (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied)
+:option:`--os-project-domain-name` <auth-project-domain-name> | :option:`--os-project-domain-id` <auth-project-domain-id>
+    Domain name or id containing project
 
-:option:`--os-username <auth-username>`
+:option:`--os-username` <auth-username>
     Authentication username
 
-:option:`--os-password <auth-password>`
+:option:`--os-user-domain-name` <auth-user-domain-name> | :option:`--os-user-domain-id` <auth-user-domain-id>
+    Domain name or id containing user
+
+:option:`--os-password` <auth-password>
     Authentication password
 
-:option:`--os-region-name <auth-region-name>`
+:option:`--os-region-name` <auth-region-name>
     Authentication region name
 
-:option:`--os-default-domain <auth-domain>`
+:option:`--os-default-domain` <auth-domain>
     Default domain ID (Default: 'default')
 
-:options:`--os-use-keyring`
+:option:`--os-use-keyring`
     Use keyring to store password (default: False)
 
-:option:`--os-cacert <ca-bundle-file>`
+:option:`--os-cacert` <ca-bundle-file>
     CA certificate bundle file
 
-:option:`--verify|--insecure`
+:option:`--verify` | :option:`--insecure`
     Verify or ignore server certificate (default: verify)
 
-:option:`--os-identity-api-version <identity-api-version>`
+:option:`--os-identity-api-version` <identity-api-version>
     Identity API version (Default: 2.0)
 
-:option:`--os-XXXX-api-version <XXXX-api-version>`
-    Additional API version options will be presend depending on the installed API libraries.
-
-
-NOTES
-=====
-
-[This section intentionally left blank.  So there.]
+:option:`--os-XXXX-api-version` <XXXX-api-version>
+    Additional API version options will be available depending on the installed API libraries.
 
 
 COMMANDS
@@ -87,7 +89,7 @@ COMMANDS
 
 To get a list of the available commands::
 
-    openstack -h
+    openstack --help
 
 To get a description of a specific command::
 
@@ -101,12 +103,23 @@ To get a description of a specific command::
     Print help for an individual command
 
 
+NOTES
+=====
+
+The command list displayed in help output reflects the API versions selected.  For
+example, to see Identity v3 commands ``OS_IDENTITY_API_VERSION`` must be set to ``3``.
+
+
 EXAMPLES
 ========
 
 Show the detailed information for server ``appweb01``::
 
-    openstack --os-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url http://localhost:5000:/v2.0 server show appweb01
+    openstack \
+        --os-project-name ExampleCo \
+        --os-username demo --os-password secrete \
+        --os-auth-url http://localhost:5000:/v2.0 \
+        server show appweb01
 
 The same command if the auth environment variables (:envvar:`OS_AUTH_URL`, :envvar:`OS_PROJECT_NAME`,
 :envvar:`OS_USERNAME`, :envvar:`OS_PASSWORD`) are set::
@@ -126,25 +139,53 @@ Create a new image::
 FILES
 =====
 
-  :file:`~/.openstack`
+:file:`~/.openstack`
+    Placeholder for future local state directory.  This directory is intended to be shared among multiple OpenStack-related applications; contents are namespaced with an identifier for the app that owns it.  Shared contents (such as :file:`~/.openstack/cache`) have no prefix and the contents must be portable.
 
 
 ENVIRONMENT VARIABLES
 =====================
 
-The following environment variables can be set to alter the behaviour of :program:`openstack`
+The following environment variables can be set to alter the behaviour of :program:`openstack`.  Most of them have corresponding command-line options that take precedence if set.
+
+:envvar:`OS_AUTH_URL`
+    Authentication URL
+
+:envvar:`OS_DOMAIN_NAME`
+    Domain-level authorization scope (name or ID)
+
+:envvar:`OS_PROJECT_NAME`
+    Project-level authentication scope (name or ID)
+
+:envvar:`OS_PROJECT_DOMAIN_NAME`
+    Domain name or id containing project
 
 :envvar:`OS_USERNAME`
-    Set the username
+    Authentication username
+
+:envvar:`OS_USER_DOMAIN_NAME`
+    Domain name or id containing user
 
 :envvar:`OS_PASSWORD`
-    Set the password
+    Authentication password
 
-:envvar:`OS_PROJECT_NAME`
-    Set the project name
+:envvar:`OS_REGION_NAME`
+    Authentication region name
 
-:envvar:`OS_AUTH_URL`
-    Set the authentication URL
+:envvar:`OS_DEFAULT_DOMAIN`
+    Default domain ID (Default: ‘default’)
+
+:envvar:`OS_USE_KEYRING`
+    Use keyring to store password (default: False)
+
+:envvar:`OS_CACERT`
+    CA certificate bundle file
+
+:envvar:`OS_IDENTITY_API_VERISON`
+    Identity API version (Default: 2.0)
+
+:envvar:`OS_XXXX_API_VERISON`
+    Additional API version options will be available depending on the installed API libraries.
 
 
 BUGS
@@ -163,7 +204,7 @@ Please refer to the AUTHORS file distributed with OpenStackClient.
 COPYRIGHT
 =========
 
-Copyright 2011-2013 OpenStack Foundation and the authors listed in the AUTHORS file.
+Copyright 2011-2014 OpenStack Foundation and the authors listed in the AUTHORS file.
 
 
 LICENSE