Update usage instructions (#625)

* readme: expand usage instructions

Expands the usage instructions section of the README to contain actual,
useful information on how to use geckodriver with Selenium and as a
standalone WebDriver server.

README.md

@@ -16,10 +16,11 @@ for a record of all notable changes to the program.
 are made available on GitHub
 on [supported platforms](#supported-firefoxen).
 
-## Supported Clients
+## Supported clients
-
-[Selenium](http://docs.seleniumhq.org/) users must update to [version 3.3.1](https://github.com/SeleniumHQ/selenium/releases/tag/selenium-3.3.1) or later to use geckodriver.
 
+[Selenium](http://docs.seleniumhq.org/) users
+must update to [version 3.3.1](https://github.com/SeleniumHQ/selenium/releases/tag/selenium-3.3.1)
+or later to use geckodriver.
 Other clients that follow the [W3C WebDriver specification](https://w3c.github.io/webdriver/webdriver-spec.html) are also supported.
 
 ## Supported Firefoxen
@@ -307,14 +308,18 @@ and enable verbose logging:
 
 ```js
 {
-	"moz:firefoxOptions": {
+	"capabilities": {
-		"binary": "/usr/local/firefox/bin/firefox",
+		"alwaysMatch": {
-		"args": ["--no-remote"],
+			"moz:firefoxOptions": {
-		"prefs": {
+				"binary": "/usr/local/firefox/bin/firefox",
-			"dom.ipc.processCount": 8
+				"args": ["--no-remote"],
-		},
+				"prefs": {
-		"log": {
+					"dom.ipc.processCount": 8
-			"level": "trace"
+				},
+				"log": {
+					"level": "trace"
+				}
+			}
 		}
 	}
 }
@@ -323,13 +328,108 @@ and enable verbose logging:
 ## Usage
 
 Usage steps are [documented on MDN](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver),
-but the gist of it is this:
+but how you invoke geckodriver largely depends on your use case.
 
-	% geckodriver -b /usr/bin/firefox
+### Selenium
 
-Or if you’re on Mac:
+If you are using geckodriver through [Selenium](http://seleniumhq.org/),
+you must ensure that you have version 3.3.1 or greater.
+Because geckodriver implements the [W3C WebDriver standard](https://w3c.github.io/webdriver/webdriver-spec.html)
+and not the same Selenium wire protocol older drivers are using,
+you may experience incompatibilities and migration problems
+when making the switch from FirefoxDriver to geckodriver.
 
-	% geckodriver -b /Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin
+Generally speaking, Selenium 3 enabled geckodriver
+as the default WebDriver implementation for Firefox.
+With the release of Firefox 47, FirefoxDriver had to be discontinued
+for its lack of support for the [new multi-processing architecture in Gecko](https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox).
+
+Selenium client bindings will pick up the _geckodriver_ binary executable
+from your [system’s `PATH` environmental variable](https://en.wikipedia.org/wiki/PATH_(variable))
+unless you override it by setting the `webdriver.gecko.driver`
+[Java VM system property](http://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html):
+
+```java
+System.setProperty("webdriver.gecko.driver", "/home/user/bin");
+```
+
+Or by passing it as a flag to the [java(1)](http://www.manpagez.com/man/1/java/) launcher:
+
+	% java -Dwebdriver.gecko.driver=/home/user/bin YourApplication
+
+Your milage with this approach may vary
+based on which programming language bindings you are using.
+It is in any case generally the case that geckodriver will be picked up
+if it is available on the system path.
+In a bash compatible shell,
+you can make other programs aware of its location
+by exporting or setting the `PATH` variable:
+
+	% export PATH=$PATH:/home/user/bin
+	% whereis geckodriver
+	geckodriver: /home/user/bin/geckodriver
+
+On Window systems you can change the system path
+by right-clicking **My Computer** and choosing **Properties**.
+In the dialogue that appears, navigate
+**Advanced** → **Environmental Variables** → **Path**.
+
+Or in the Windows console window:
+
+	$ set PATH=%PATH%;C:\bin\geckodriver
+
+### Standalone
+
+Since geckodriver is a separate HTTP server
+that is a complete remote end implementation
+of [WebDriver](https://w3c.github.io/webdriver/webdriver-spec.html),
+it is possible to avoid using the Selenium remote server
+if you have no requirements
+to distribute processes across a matrix of systems.
+
+Given a W3C WebDriver conforming client library (or _local end_)
+you may interact with the geckodriver HTTP server
+as if you were speaking to any Selenium server.
+
+Using [curl(1)](http://www.manpagez.com/man/1/curl/):
+
+	% geckodriver &
+	[1] 16010
+	% 1491834109194   geckodriver     INFO    Listening on 127.0.0.1:4444
+	% curl -d '{"capabilities": {"alwaysMatch": {"acceptInsecureCerts": true}}}' http://localhost:4444/session
+	{"sessionId":"ad1e71a4-aad8-4c75-b7e6-8d57a7133161","value":{"XULappId":"{ec8030f7-c20a-464f-9b0e-13a3a9e97384}","acceptSslCerts":false,"appBuildId":"20160913030425","browserName":"firefox","browserVersion":"51.0a1","command_id":1,"platform":"LINUX","platformName":"linux","platformVersion":"4.9.0-1-amd64","processId":17474,"proxy":{},"raisesAccessibilityExceptions":false,"rotatable":false,"specificationLevel":0,"takesElementScreenshot":true,"takesScreenshot":true,"version":"51.0a1"}}
+	% curl -d '{"url": "https://mozilla.org"}' http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00/url
+	{}
+	% curl http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00/url
+	{"value":"https://www.mozilla.org/en-US/"
+	% curl -X DELETE http://localhost:4444/session/d4605710-5a4e-4d64-a52a-778bb0c31e00
+	{}
+	% fg
+	geckodriver
+	^C
+	%
+
+Using the Python [wdclient](https://github.com/w3c/wpt-tools/tree/master/webdriver) library:
+
+```py
+import webdriver
+
+with webdriver.Session("127.0.0.1", 4444) as session:
+    session.url = "https://mozilla.org"
+    print "The current URL is %s" % session.url
+```
+
+And to run:
+
+	% geckodriver &
+	[1] 16054
+	% python example.py
+	1491835308354   geckodriver     INFO    Listening on 127.0.0.1:4444
+	The current URL is https://www.mozilla.org/en-US/
+	% fg
+	geckodriver
+	^C
+	%
 
 You may also see all flags and options
 available in geckodriver by viewing the help message:
@@ -361,14 +461,17 @@ available in geckodriver by viewing the help message:
 
 ## Building
 
-geckodriver is written in [Rust](https://www.rust-lang.org/)
+geckodriver is written in [Rust](https://www.rust-lang.org/),
-and you need the [Rust toolchain](https://rustup.rs/) to compile it.
+a systems programming language from [Mozilla](https://www.mozilla.org/en-US/).
+In order to build this program,
+you will need the [Rust compiler toolchain](https://rustup.rs/).
 
 To build the project for release,
-ensure you do a compilation with optimisations:
+ensure you compile with optimisations
+to get the best performance:
 
-    % cargo build --release
+	% cargo build --release
 
 Or if you want a non-optimised binary for debugging:
 
-    % cargo build
+	% cargo build