README.md in vcloud-walker-3.2.1 vs README.md in vcloud-walker-3.2.2

@@ -1,8 +1,9 @@
 # VCloud Walker
 
-Vcloud-walker is a command line tool, to describe different VMware vCloud Director 5.1 entities. It uses Fog under the hood.
+Vcloud-walker is a command line tool, to describe different VMware vCloud
+Director 5.1 entities. It uses Fog under the hood.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
@@ -22,11 +23,12 @@
 You can perform following operations with walker.
 
 #### Walk vdcs:
    vcloud-walk vdcs
 
-describes all vdcs within given organization. This includes vapp, vm and network information.
+describes all vdcs within given organization. This includes vapp, vm and network
+information.
 
 #### Walk catalogs:
     vcloud-walk catalogs
 
 describes all catalogs and catalog items within given organization.
@@ -37,64 +39,72 @@
 describes all organization networks.
 
 #### Walk edgegateways:
     vcloud-walk edgegateways
 
-describes all edgegateway for given organization. Each edgegateway includes configuration for firewall, load balancer and nat services.
+describes all edgegateway for given organization. Each edgegateway includes
+configuration for firewall, load balancer and nat services.
 
 #### Walk entire organization:
      vcloud-walk organization
 
-describes the entire organization, which includes edgegateway, catalogs, networks and vdcs within an organization.
+describes the entire organization, which includes edgegateway, catalogs,
+networks and vdcs within an organization.
 
-### Credentials
+## Credentials
 
-You will need to specify the credentials for your VMware environment. Vcloud-walker uses fog to query the VMware api,
-which offers two ways to do this.
+vCloud Walker is based around [fog](http://fog.io/). To use it you'll need to give it
+credentials that allow it to talk to a vCloud Director environment.
 
-#### 1. Create a `.fog` file containing your credentials
+1. Create a '.fog' file in your home directory.
 
-An example of .fog file is:
+  For example:
 
-````
-default:
-  vcloud_director_username: 'user_id@org_id'
-  vcloud_director_password: 'password'
-  vcloud_director_host: 'api_endpoint'
-````
+      test_credentials:
+        vcloud_director_host: 'host.api.example.com'
+        vcloud_director_username: 'username@org_name'
+        vcloud_director_password: ''
 
-To understand more about `.fog` files, visit the 'Credentials' section here => http://fog.io/about/getting_started.html.
+2. Obtain a session token. First, curl the API:
 
-### 2. Log on externally and supply your session token
+        curl -D- -d '' \
+            -H 'Accept: application/*+xml;version=5.1' -u '<username>@<org_name>' \
+            https://<host.api.example.com>/api/sessions
 
-You can choose to log on externally by interacting independently with the API and supplying your session token to the
-tool by setting the `FOG_VCLOUD_TOKEN` ENV variable. This option reduces the risk footprint by allowing the user to
-store their credentials in safe storage. The default token lifetime is '30 minutes idle' - any activity extends the life by another 30 mins.
+  This will prompt for your password.
 
-A basic example of this would be the following:
+  From the headers returned, the value of the `x-vcloud-authorization` header is your
+  session token, and this will be valid for 30 minutes idle - any activity will extend
+  its life by another 30 minutes.
 
-    curl
-       -D-
-       -d ''
-       -H 'Accept: application/*+xml;version=5.1' -u '<user>@<org>'
-       https://host.com/api/sessions
+3. Specify your credentials and session token at the beginning of the command. For example:
 
-This will prompt for your password.
+        FOG_CREDENTIAL=test_credentials \
+            FOG_VCLOUD_TOKEN=AAAABBBBBCCCCCCDDDDDDEEEEEEFFFFF= \
+            vcloud-walk organization
 
-From the headers returned, select the header below
+  You may find it easier to export one or both of the values as environment variables.
 
-     x-vcloud-authorization: AAAABBBBBCCCCCCDDDDDDEEEEEEFFFFF=
+  **NB** It is also possible to sidestep the need for the session token by saving your
+  password in the fog file. This is **not recommended**.
 
-Use token as ENV var FOG_VCLOUD_TOKEN
 
-    FOG_VCLOUD_TOKEN=AAAABBBBBCCCCCCDDDDDDEEEEEEFFFFF= vcloud-walk organization
-
 ### Output
 
 Walker can output data in JSON or YAML format. The default output format is JSON.
 You can use command line option ```--yaml``` for yaml output.
 
 Find sample json output in docs/examples directory.
+
+## The vCloud API
+
+vCloud Tools currently use version 5.1 of the [vCloud API](http://pubs.vmware.com/vcd-51/index.jsp?topic=%2Fcom.vmware.vcloud.api.doc_51%2FGUID-F4BF9D5D-EF66-4D36-A6EB-2086703F6E37.html). Version 5.5 may work but is not currently supported. You should be able to access the 5.1 API in a 5.5 environment, and this *is* currently supported.
+
+The default version is defined in [Fog](https://github.com/fog/fog/blob/244a049918604eadbcebd3a8eaaf433424fe4617/lib/fog/vcloud_director/compute.rb#L32).
+
+If you want to be sure you are pinning to 5.1, or use 5.5, you can set the API version to use in your fog file, e.g.
+
+`vcloud_director_api_version: 5.1`
 
 ## Debugging
 
 `export EXCON_DEBUG=true` - this will print out the API requests and responses.