import of ba6208ac98c6bc52fab16237571a95d64be64755

2 files changed, 34 insertions, 847 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d1e76bc..fa205c4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,228 +1,2 @@
-Contributing
-============
-
-We are delighted that you want to help improve geckodriver!
-Mozilla’s WebDriver implementation consists of a few different
-parts it can be useful to know about:
-
-  * [_geckodriver_] provides the HTTP API described by the [WebDriver
-    protocol] to communicate with Gecko-based browsers such as
-    Firefox and Fennec.  It is a standalone executable written in
-    Rust, and can be used with compatible W3C WebDriver clients.
-
-  * [_Marionette_] is the Firefox remote protocol used by geckodriver
-    to communicate with, instrument, and control Gecko.  It is
-    built in to Firefox and written in [XPCOM] flavoured JavaScript.
-
-  * [_webdriver_] is a Rust crate providing interfaces, traits
-    and types, errors, type- and bounds checks, and JSON marshaling
-    for correctly parsing and emitting the [WebDriver protocol].
-
-By participating in this project, you agree to abide by the Mozilla
-[Community Participation Guidelines].  Here are some guidelines
-for contributing high-quality and actionable bugs and code.
-
-[_geckodriver_]: https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/
-[_Marionette_]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/
-[_webdriver_]: https://crates.io/crates/webdriver
-[WebDriver protocol]: https://w3c.github.io/webdriver/webdriver-spec.html#protocol
-[XPCOM]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Guide
-[Community Participation Guidelines]: https://www.mozilla.org/en-US/about/governance/policies/participation/
-
-
-Reporting bugs
-==============
-
-When opening a new issue or commenting on existing issues, please
-make sure discussions are related to concrete technical issues
-with geckodriver or Marionette.  Questions or discussions are more
-appropriate for the [mailing list].
-
-For issue reports to be actionable, it must be clear exactly
-what the observed and expected behaviours are, and how to set up
-the state required to observe the erroneous behaviour.  The most
-useful thing to provide is a minimal HTML document which permits
-the problem to be reproduced along with a [trace-level log] from
-geckodriver showing the exact wire protocol calls made.
-
-Because of the wide variety and different charateristics of clients
-used with geckodriver, their stacktraces, logs, and code examples are
-typically not very useful as they distract from the actual underlying
-cause.  **For this reason, we cannot overstate the importance of
-always providing the [trace-level log] from geckodriver.** Bugs
-relating to a specific client should be filed with that project.
-
-We welcome you to file issues in the [GitHub issue tracker] once you are
-confident it has not already been reported.  The [ISSUE_TEMPLATE.md]
-contains a helpful checklist for things we will want to know about
-the affected system, reproduction steps, and logs.
-
-geckodriver development follows a rolling release model as we don’t
-release patches for older versions.  It is therefore useful to use
-the tip-of-tree geckodriver binary, or failing this, the latest
-release when verifying the problem.  geckodriver is only compatible
-with the current release channel versions of Firefox, and it
-consequently does not help to report bugs that affect outdated and
-unsupported Firefoxen.  Please always try to verify the issue in
-the latest Firefox Nightly before you file your bug.
-
-Once we are satisfied the issue raised is of sufficiently actionable
-character, we will continue with triaging it and file a bug where it
-is appropriate.  Bugs specific to geckodriver will be filed in the
-[`Testing :: geckodriver`] component in Bugzilla.
-
-[mailing list]: #communication
-[trace-level log]: https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/TraceLogs.html
-[GitHub issue tracker]: https://github.com/mozilla/geckodriver/issues
-[`Testing :: geckodriver`]: https://bugzilla.mozilla.org/buglist.cgi?component=geckodriver
-
-
-Writing code
-============
-
-Because there are many moving parts involved remote controlling
-a web browser, it can be challenging to a new contributor to know
-where to start.  Please don’t hesitate to [ask questions]!
-
-The canonical source code repository of geckodriver is now
-[mozilla-central].  We continue to use the [GitHub issue tracker] as
-a triage ground before actual, actionable bugs and tasks are filed
-in the [`Testing :: geckodriver`] component on Bugzilla.  We also
-have a curated set of [good first bugs] you may consider attempting first.
-
-The purpose of this guide _is not_ to make sure you have a basic
-development environment set up.  For that there is plentiful
-documentation, such as the [Developer Guide] to get you rolling.
-Once you do, we can get started working up your first patch!
-Remember to [reach out to us] at any point if you have questions.
-
-[ask questions]: #communication
-[reach out to us]: #communication
-[mozilla-central]: https://searchfox.org/mozilla-central/source/testing/geckodriver/
-[good first bugs]: https://www.joshmatthews.net/bugsahoy/?automation=1&rust=1
-[Developer Guide]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide
-
-
-Building geckodriver
---------------------
-
-geckodriver is written in [Rust], a systems programming language
-from Mozilla.  Crucially, it relies on the [webdriver crate] to
-provide the HTTPD and do most of the heavy lifting of marshalling the
-[WebDriver protocol].  geckodriver translates WebDriver [commands],
-[responses], and [errors] to the [Marionette protocol], and acts
-as a proxy between WebDriver clients and [Marionette].
-
-Whilst geckodriver lives in the same source repository as Firefox
-and is built in the [Firefox CI], is _is not_ built if you build
-Firefox locally.  To enable building of geckodriver locally, ensure
-you put this in your [mozconfig]:
-
-	ac_add_options --enable-geckodriver
-
-When you have, you are ready to start off your first build:
-
-	% ./mach build testing/geckodriver
-
-To run the executable from the objdir:
-
-	% ./mach geckodriver -- --version
-	 0:00.27 /home/ato/src/gecko/obj-x86_64-pc-linux-gnu/dist/bin/geckodriver --version --binary /home/ato/src/gecko/obj-x86_64-pc-linux-gnu/dist/bin/firefox
-	geckodriver 0.19.0 (f3e939a81ee1169f9501ad96eb43bbf4bf4a1bde 2017-10-11)
-
-[Rust]: https://www.rust-lang.org/
-[webdriver crate]: https://crates.io/crates/webdriver
-[commands]: https://docs.rs/webdriver/newest/webdriver/command/index.html
-[responses]: https://docs.rs/webdriver/newest/webdriver/response/index.html
-[errors]: https://docs.rs/webdriver/newest/webdriver/error/enum.ErrorStatus.html
-[Marionette protocol]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Protocol
-[Marionette]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/index.html
-[Firefox CI]: https://treeherder.mozilla.org/
-[mozconfig]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options
-
-
-Running the tests
------------------
-
-We verify and test geckodriver in a couple of different ways.
-Since it is an implementation of the WebDriver web standard, we share
-a set of conformance tests with other browser vendors through the
-[Web Platform Tests] (WPT) initiative.  This lets us ensure web
-compatibility between _different_ WebDriver implementations for
-different browsers.
-
-In addition to the WPT tests, geckodriver and webdriver have unit tests.
-You can use a mach command to run them:
-
-	% ./mach test testing/geckodriver
-
-The webdriver crate tests are unfortunately not yet runnable through mach.
-Work to make this possible is tracked in [[https://bugzil.la/1424369]].
-For the moment you must run them manually through `cargo`:
-
-	% cd testing/webdriver
-	% cargo test
-
-To run the more extensive WPT tests you can use mach, but first
-make sure you have a build of Firefox:
-
-	% ./mach build
-	% ./mach wpt testing/web-platform/tests/webdriver
-
-As these are functional integration tests and pop up Firefox windows
-sporadically, a helpful tip is to surpress the window whilst you
-are running them by using Firefox’ [headless mode]:
-
-	% MOZ_HEADLESS=1 ./mach wpt testing/web-platform/tests/webdriver
-
-In addition to the `MOZ_HEADLESS` output variable there is also
-`MOZ_HEADLESS_WIDTH` and `MOZ_HEADLESS_HEIGHT` to control the
-dimensions of the no-op virtual display.  This is similar to using
-xvfb(1) which you may know from the X windowing system, but has
-the additional benefit of also working on macOS and Windows.
-
-As you get in to development of geckodriver and Marionette you will
-increasingly grow to understand our love for [trace-level logs].
-They provide us with the input—the HTTP requests—from the client
-(in WPT’s case from the tests’ use of a custom WebDriver client),
-the translation geckodriver makes to the [Marionette protocol],
-the log output from Marionette, its responses back to geckodriver,
-and finally the output—or the HTTP response—back to the client.
-
-The [trace-level logs] can be surfaced by passing on the `-vv`
-flag to geckodriver through WPT:
-
-	% ./mach wpt --webdriver-arg=-vv testing/web-platform/tests/webdriver
-
-[Web Platform Tests]: http://web-platform-tests.org/
-[cargo]: http://doc.crates.io/guide.html
-[headless mode]: https://developer.mozilla.org/en-US/Firefox/Headless_mode
-
-
-Submitting patches
-------------------
-
-You can submit patches by uploading .diff files to Bugzilla or by
-sending them to [MozReview].
-
-Once you have contributed a couple of patches, we are happy to
-sponsor you in [becoming a Mozilla committer].  When you have been
-granted commit access level 1 you will have permission to use the
-[Firefox CI] to trigger your own “try runs” to test your changes.
-
-[MozReview]: http://mozilla-version-control-tools.readthedocs.io/en/latest/mozreview.html
-[becoming a Mozilla committer]: https://www.mozilla.org/en-US/about/governance/policies/commit/
-
-
-Communication
-=============
-
-The mailing list for geckodriver discussion is
-tools-marionette@lists.mozilla.org ([subscribe], [archive]).
-
-If you prefer real-time chat, there is often someone in the #ateam IRC
-channel on irc.mozilla.org.  Don’t ask if you can ask a question, just
-ask, and please wait for an answer as we might not be in your timezone.
-
-[subscribe]: https://lists.mozilla.org/listinfo/tools-marionette
-[archive]: https://groups.google.com/group/mozilla.tools.marionette
+Please see our contributor documentation at
+https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/#for-developers.
diff --git a/README.md b/README.md
index e2d2cc7..4c23aa1 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 geckodriver
 ===========
 
-Proxy for using W3C WebDriver-compatible clients to interact with
+Proxy for using W3C [WebDriver] compatible clients to interact with
 Gecko-based browsers.
 
 This program provides the HTTP API described by the [WebDriver protocol]
@@ -9,638 +9,51 @@ to communicate with Gecko browsers, such as Firefox.  It translates calls
 into the [Firefox remote protocol] by acting as a proxy between the local-
 and remote ends.
 
-You can consult the [change log] for a record of all notable changes
-to the program.  [Releases] are made available on GitHub on [supported
-platforms].
+geckodriver’s [source code] is made available under the [Mozilla
+Public License].
 
-The canonical source code repository for geckodriver now lives in
-[mozilla-central] under [testing/geckodriver].  You can read more about
-[working with Mozilla source code] on MDN.  This means we do no longer
-accept pull requests on GitHub.  Patches should be uploaded to a bug in
-the [Testing :: GeckoDriver] component.
-
-[WebDriver protocol]: http://w3c.github.io/webdriver/#protocol
+[WebDriver protocol]: https://w3c.github.io/webdriver/#protocol
 [Firefox remote protocol]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/Protocol.html
-[change log]: https://github.com/mozilla/geckodriver/releases
-[Releases]: https://github.com/mozilla/geckodriver/releases
-[supported platforms]: #supported-firefoxen
-[mozilla-central]: https://hg.mozilla.org/mozilla-central/
-[testing/geckodriver]: https://hg.mozilla.org/mozilla-central/file/tip/testing/geckodriver
-[working with Mozilla source code]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Source_Code
-[Testing :: geckodriver]: https://bugzilla.mozilla.org/buglist.cgi?product=Testing&component=geckodriver&resolution=---&list_id=13613952
-
-
-Supported clients
-=================
-
-[Selenium] users must update to version 3.11 or later to
-use geckodriver.  Other clients that follow the [W3C WebDriver
-specification][WebDriver] are also supported.
-
-
-Supported Firefoxen
-===================
-
-geckodriver is not yet feature complete.  This means that it does
-not yet offer full conformance with the [WebDriver] standard or
-complete compatibility with [Selenium].  You can track the
-[implementation status] of the latest [Firefox Nightly] on MDN.  We
-also keep track of known [Selenium], [remote protocol], and
-[specification] problems in our [issue tracker].
-
-Support is best in Firefox 57 and greater, although generally the
-more recent the Firefox version, the better the experience as they
-have more bug fixes and features.  Some features will only be
-available in the most recent Firefox versions, and we strongly
-advise using the latest [Firefox Nightly] with geckodriver.  Since
-Windows XP support in Firefox was dropped with Firefox 53, we do
-not support this platform.
-
-[implementation status]: https://bugzilla.mozilla.org/showdependencytree.cgi?id=721859&hide_resolved=1
-[Firefox Nightly]: https://whattrainisitnow.com/
-[selenium]: https://github.com/mozilla/geckodriver/issues?q=is%3Aissue+is%3Aopen+label%3Aselenium
-[remote protocol]: https://github.com/mozilla/geckodriver/issues?q=is%3Aissue+is%3Aopen+label%3Amarionette
-[specification]: https://github.com/mozilla/geckodriver/issues?q=is%3Aissue+is%3Aopen+label%3Aspec
-[issue tracker]: https://github.com/mozilla/geckodriver/issues
-[Firefox Nightly]: https://nightly.mozilla.org/
-
-
-WebDriver capabilities
-======================
-
-geckodriver supports a number of [capabilities]:
-
-[capabilities]: https://w3c.github.io/webdriver/#capabilities
-
-<table>
- <thead>
-  <tr>
-   <th>Name
-   <th>Type
-   <th>Default
-   <th>Description
-  </tr>
- </thead>
-
- <tr>
-  <td><nobr><code>acceptInsecureCerts</code></nobr>
-  <td>boolean
-  <td>false
-  <td>Indicates the session will not implicitly trust untrusted
-   or self-signed TLS certificates on navigation.
-  <td>
- </tr>
-
- <tr>
-  <td><code>pageLoadStrategy</code>
-  <td>string
-  <td>`normal`
-  <td>Defines the page load strategy
-   to use for the duration of the session.
-   Setting a page load strategy will cause navigation
-   to be "<code>eager</code>",
-   waiting for the <code>interactive</code> document ready state;
-   "<code>normal</code>" (the default),
-   waiting for the <code>complete</code> ready state;
-   or "<code>none</code>",
-   which will return immediately after starting navigation.
-  <td>
- </tr>
-
- <tr>
-  <td><code>proxy</code>
-  <td><a href=#proxy-object><code>proxy</code></a>&nbsp;object
-  <td>
-  <td>Sets browser proxy settings.
- </tr>
-</table>
-
-
-`proxy` object
---------------
-
-<table>
- <thead>
-  <tr>
-   <th>Name
-   <th>Type
-   <th>Description
-  </tr>
- </thead>
-
- <tr>
-  <td><code>proxyType</code>
-  <td>string
-  <td>Indicates the type of proxy configuration.
-   This value must be one of
-   <code>pac</code>,
-   <code>direct</code>,
-   <code>autodetect</code>,
-   <code>system</code>,
-   or <code>manual</code>.
- </tr>
-
- <tr>
-  <td><code>proxyAutoconfigUrl</code>
-  <td>string
-  <td>Defines the URL for a proxy auto-config file.
-   This property should only be set
-   when <code>proxyType</code> is <code>pac</code>.
- </tr>
-
- <tr>
-  <td><code>ftpProxy</code>
-  <td>string
-  <td>Defines the proxy hostname with an optional port for FTP traffic.
-   This property should only be set when <code>proxyType</code>
-   is set to <code>manual</code>.
- </tr>
-
- <tr>
-  <td><code>httpProxy</code>
-  <td>string
-  <td>Defines the proxy hostname with an optional port for HTTP traffic.
-   This property should only be set when <code>proxyType</code>
-   is set to <code>manual</code>.
- </tr>
-
- <tr>
-  <td><code>noProxy</code>
-  <td>list
-  <td>Lists the addresses for which the proxy should be bypassed.
-   This property should only be set when <code>proxyType</code>
-   is set to <code>manual</code>.
- </tr>
-
- <tr>
-  <td><code>sslProxy</code>
-  <td>string
-  <td>Defines the proxy hostname with an optional port for encrypted TLS traffic.
-   This property should only be set when <code>proxyType</code>
-   is set to <code>manual</code>.
- </tr>
-
- <tr>
-  <td><code>socksProxy</code>
-  <td>string
-  <td>Defines the hostname with on optional port for a SOCKS proxy.
-   This property should only be set when <code>proxyType</code>
-   is set to <code>manual</code>.
- </tr>
-
- <tr>
-  <td><code>socksVersion</code>
-  <td>number
-  <td>Defines the SOCKS proxy version. This property has only to be set
-   when <code>proxyType</code> is set to <code>manual</code>.
- </tr>
-</table>
-
-
-Firefox capabilities
-====================
-
-geckodriver has a few capabilities that are specific to Firefox.
-
-
-`moz:firefoxOptions`
---------------------
-
-A dictionary used to define options which control how Firefox gets
-started and run. It may contain any of the following fields:
-
-<table>
- <thead>
-  <tr>
-   <th>Name
-   <th>Type
-   <th>Description
-  </tr>
- </thead>
-
- <tr id=capability-binary>
-  <td><code>binary</code>
-  <td>string
-  <td>Absolute path of the Firefox binary,
-   e.g. <code>/usr/bin/firefox</code>
-   or <code>/Applications/Firefox.app/Contents/MacOS/firefox</code>,
-   to select which custom browser binary to use.
-   If left undefined geckodriver will attempt
-   to deduce the default location of Firefox
-   on the current system.
- </tr>
-
- <tr id=capability-args>
-  <td><code>args</code>
-  <td>array&nbsp;of&nbsp;strings
-  <td><p>Command line arguments to pass to the Firefox binary.
-   These must include the leading dash (<code>-</code>) where required,
-   e.g. <code>["-devtools"]</code>.
-
-   <p>To have geckodriver pick up an existing profile on the filesystem,
-    you may pass <code>["-profile", "/path/to/profile"]</code>.
- </tr>
-
- <tr id=capability-profile>
-  <td><code>profile</code>
-  <td>string
-  <td><p>Base64-encoded ZIP of a profile directory to use for the Firefox instance.
-   This may be used to e.g. install extensions or custom certificates,
-   but for setting custom preferences
-   we recommend using the <a href=#capability-prefs><code>prefs</code></a> entry
-   instead of passing a profile.
-
-   <p>Profiles are created in the system’s temporary folder.
-    This is also where the encoded profile is extracted
-    when <code>profile</code> is provided.
-    By default, geckodriver will create a new profile in this location.
-
-   <p>The effective profile in use by the WebDriver session
-    is returned to the user in the <code>moz:profile</code> capability
-    in the new session response.
-
-   <p>To have geckodriver pick up an <em>existing profile</em> on the filesystem,
-    please set the <a href=#capability-args><code>args</code></a> field
-    to <code>{"args": ["-profile", "/path/to/your/profile"]}</code>.
- </tr>
-
- <tr id=capability-log>
-  <td><code>log</code>
-  <td><a href=#log-object><code>log</code></a>&nbsp;object
-  <td>To increase the logging verbosity of geckodriver and Firefox,
-   you may pass a <a href=#log-object><code>log</code> object</a>
-   that may look like <code>{"log": {"level": "trace"}}</code>
-   to include all trace-level logs and above.
- </tr>
-
- <tr id=capability-prefs>
-  <td><code>prefs</code>
-  <td><a href=#prefs-object><code>prefs</code></a>&nbsp;object
-  <td>Map of preference name to preference value, which can be a
-   string, a boolean or an integer.
- </tr>
-</table>
-
-
-`moz:useNonSpecCompliantPointerOrigin`
---------------------------------------
-
-A boolean value to indicate how the pointer origin for an action
-command will be calculated.
-
-With Firefox 59 the calculation will be based on the requirements by
-the [WebDriver] specification. This means that the pointer origin
-is no longer computed based on the top and left position of the
-referenced element, but on the in-view center point.
-
-To temporarily disable the WebDriver conformant behavior use `false`
-as value for this capability.
-
-Please note that this capability exists only temporarily, and that
-it will be removed once all Selenium bindings can handle the new behavior.
-
-
-`moz:webdriverClick`
---------------------
-
-A boolean value to indicate which kind of interactability checks
-to run when performing a click or sending keys to an elements. For
-Firefoxen prior to version 58.0 some legacy code as imported from
-an older version of FirefoxDriver was in use.
-
-With Firefox 58 the interactability checks as required by the
-[WebDriver] specification are enabled by default. This means
-geckodriver will additionally check if an element is obscured by
-another when clicking, and if an element is focusable for sending keys.
-
-Because of this change in behaviour, we are aware that some extra
-errors could be returned. In most cases the test in question might
-have to be updated so it's conform with the new checks. But if the
-problem is located in geckodriver, then please raise an issue in the
-[issue tracker].
-
-To temporarily disable the WebDriver conformant checks use `false`
-as value for this capability.
-
-Please note that this capability exists only temporarily, and that
-it will be removed once the interactability checks have been stabilized.
-
-
-`log` object
-------------
-
-<table>
- <thead>
-  <tr>
-   <th>Name
-   <th>Type
-   <th>Description
-  </tr>
- </thead>
-
- <tr>
-  <td><code>level</code>
-  <td>string
-  <td>Set the level of verbosity of geckodriver and Firefox.
-   Available levels are <code>trace</code>,
-   <code>debug</code>, <code>config</code>,
-   <code>info</code>, <code>warn</code>,
-   <code>error</code>, and <code>fatal</code>.
-   If left undefined the default is <code>info</code>.
-   The value is treated case-insensitively.
- </tr>
-</table>
-
-
-`prefs` object
---------------
-
-<table>
- <thead>
-  <tr>
-   <th>Name
-   <th>Type
-   <th>Description
-  </tr>
- </thead>
-
- <tr>
-  <td><var>preference name</var>
-  <td>string, number, boolean
-  <td>One entry per preference to override.
- </tr>
-</table>
-
-
-Capabilities example
-====================
-
-The following example selects a specific Firefox binary to run with
-a prepared profile from the filesystem in headless mode (available on
-certain systems and recent Firefoxen).  It also increases the number
-of IPC processes through a preference and enables more verbose logging.
-
-	{
-		"capabilities": {
-			"alwaysMatch": {
-				"moz:firefoxOptions": {
-					"binary": "/usr/local/firefox/bin/firefox",
-					"args": ["-headless", "-profile", "/path/to/my/profile"],
-					"prefs": {
-						"dom.ipc.processCount": 8
-					},
-					"log": {
-						"level": "trace"
-					}
-				}
-			}
-		}
-	}
-
-
-Usage
-=====
-
-geckodriver is an implementation of WebDriver, and WebDriver can
-be used for widely different purposes.  How you invoke geckodriver
-largely depends on your use case.
-
-
-Selenium
---------
-
-If you are using geckodriver through [Selenium], you must ensure that
-you have version 3.11 or greater.  Because geckodriver implements the
-[W3C WebDriver standard][WebDriver] 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.
-
-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][e10s].
-
-Selenium client bindings will pick up the _geckodriver_ binary executable
-from your [system’s `PATH` environmental variable][PATH] unless you
-override it by setting the `webdriver.gecko.driver` [Java VM system
-property]:
-
-	System.setProperty("webdriver.gecko.driver", "/home/user/bin");
-
-Or by passing it as a flag to the [java(1)] 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], 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)]:
-
-	% geckodriver &
-	[1] 16010
-	% 1491834109194   geckodriver     INFO    Listening on 127.0.0.1:4444
-	% curl -d '{"capabilities": {"alwaysMatch": {"acceptInsecureCerts": true}}}' http://localhost:4444/session
-	{"sessionId":"d4605710-5a4e-4d64-a52a-778bb0c31e00","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] library:
-
-	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
-	%
-
-[Selenium]: http://seleniumhq.org/
-[e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox
-[PATH]: https://en.wikipedia.org/wiki/PATH_(variable)
-[Java VM system property]: http://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html
-[java(1)]: http://www.manpagez.com/man/1/java/
-[WebDriver]: https://w3c.github.io/webdriver/
-[curl(1)]: http://www.manpagez.com/man/1/curl/
-[wdclient]: https://github.com/web-platform-tests/wpt/tree/master/tools/webdriver
-
-
-Flags
-=====
-
-#### <code>-b <var>BINARY</var></code>/<code>--binary <var>BINARY</var></code>
-
-Path to the Firefox binary to use.  By default geckodriver tries to find
-and use the system installation of Firefox, but that behaviour can be
-changed by using this option.  Note that the `binary` capability of the
-`moz:firefoxOptions` object that is passed when [creating a new session]
-will override this option.
-
-On Linux systems it will use the first _firefox_ binary found by searching
-the `PATH` environmental variable, which is roughly equivalent to calling
-[whereis(1)] and extracting the second column:
-
-	% whereis firefox
-	firefox: /usr/bin/firefox /usr/local/firefox
-
-On macOS, the binary is found by looking for the first _firefox-bin_
-binary in the same fashion as on Linux systems.  This means it is
-possible to also use `PATH` to control where geckodriver should find
-Firefox on macOS.  It will then look for _/Applications/Firefox.app_.
-
-On Windows systems, geckodriver looks for the system Firefox by scanning
-the Windows registry.
-
-[creating a new session]: https://w3c.github.io/webdriver/#new-session
-[whereis(1)]: http://www.manpagez.com/man/1/whereis/
-
-
-#### `--connect-existing`
-
-Connect geckodriver to an existing Firefox instance.  This means
-geckodriver will abstain from the default of starting a new Firefox
-session.
-
-The existing Firefox instance must have [Marionette] enabled.
-To enable the remote protocol in Firefox, you can pass the
-`-marionette` flag.  Unless the `marionette.port` preference
-has been user-set, Marionette will listen on port 2828.  So when
-using `--connect-existing` it is likely you will also have to use
-[`--marionette-port`] to set the correct port.
-
-[`--marionette-port`]: #marionette-port
-
-
-#### <code>--host <var>HOST</var></code>
-
-Host to use for the WebDriver server.  Defaults to 127.0.0.1.
-
-
-#### <code>--log <var>LEVEL</var></code>
-
-Set the Gecko and geckodriver log level.  Possible values are `fatal`,
-`error`, `warn`, `info`, `config`, `debug`, and `trace`.
-
-
-#### <code>--marionette-port <var>PORT</var></code>
-
-Selects the port for geckodriver’s connection to the [Marionette]
-remote protocol.
-
-In the default mode where geckodriver starts and manages the Firefox
-process, it will pick a free port assigned by the system and set the
-`marionette.port` preference in the profile.
-
-When [`--connect-existing`] is used and the Firefox process is not
-under geckodriver’s control, it will simply connect to <var>PORT</var>.
-
-[`--connect-existing`]: #connect-existing
-
-
-#### <code>-p <var>PORT</var></code>/<code>--port <var>PORT</var></code>
-
-Port to use for the WebDriver server.  Defaults to 4444.
-
-A helpful trick is that it is possible to bind to 0 to get the
-system to atomically assign a free port.
-
-
-#### <code>--jsdebugger</code>
-
-Attach [browser toolbox] debugger when Firefox starts.  This is
-useful for debugging [Marionette] internals.
-
-[browser toolbox]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox
+[source code]: https://hg.mozilla.org/mozilla-unified/file/tip/testing/geckodriver
+[Mozilla Public License]: https://www.mozilla.org/en-US/MPL/2.0/
+[WebDriver]: https://developer.mozilla.org/en-US/docs/Web/WebDriver
 
 
-#### <code>-v<var>[v]</var></code>
+Downloads
+---------
 
-Increases the logging verbosity by to debug level when passing
-a single `-v`, or to trace level if `-vv` is passed.  This is
-analogous to passing `--log debug` and `--log trace`, respectively.
+* [Releases](https://github.com/mozilla/geckodriver/releases/latest)
+* [Change log](https://searchfox.org/mozilla-central/source/testing/geckodriver/CHANGES.md)
 
 
-Building
-========
+Documentation
+-------------
 
-geckodriver is written in [Rust], a systems programming language from
-[Mozilla].  Crucially, it relies on the [webdriver crate] to provide
-the HTTPD and do most of the heavy lifting of marshalling the WebDriver
-protocol.  geckodriver translates WebDriver [commands], [responses],
-and [errors] to the [Marionette protocol], and acts as a proxy between
-[WebDriver] and [Marionette].
+* [WebDriver] (work in progress)
+  * [Commands](https://developer.mozilla.org/en-US/docs/Web/WebDriver/Commands)
+  * [Errors](https://developer.mozilla.org/en-US/docs/Web/WebDriver/Errors)
+  * [Types](https://developer.mozilla.org/en-US/docs/Web/WebDriver/Types)
 
-geckodriver is built in the [Firefox CI] by default but _not_ if you
-build Firefox locally.  To enable building of geckodriver locally,
-ensure you put this in your [mozconfig]:
+* [Cross browser testing](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing)
 
-	ac_add_options --enable-geckodriver
+* [Selenium](https://seleniumhq.github.io/docs/) (work in progress)
+  * [C# API](https://seleniumhq.github.io/selenium/docs/api/dotnet/)
+  * [JavaScript API](https://seleniumhq.github.io/selenium/docs/api/javascript/)
+  * [Java API](https://seleniumhq.github.io/selenium/docs/api/java/)
+  * [Python API](https://seleniumhq.github.io/selenium/docs/api/py/)
+  * [Ruby API](https://seleniumhq.github.io/selenium/docs/api/rb/)
 
-You build geckodriver with the `./mach build testing/geckodriver`
-command, run tests with `./mach test testing/geckodriver`, and run
-the built executable with `./mach geckodriver -- --other --flags`.
+* [geckodriver usage](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/Usage.html)
+  * [Firefox capabilities](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/Capabilities.html)
+  * [Capabilities example](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/Capabilities.html#capabilities-example)
+  * [Enabling trace logs](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/TraceLogs.html)
+  * [Analyzing crash data from Firefox](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/CrashReports.html)
 
-[Rust]: https://www.rust-lang.org/
-[Mozilla]: https://www.mozilla.org/en-US/
-[webdriver crate]: https://crates.io/crates/webdriver
-[commands]: https://docs.rs/webdriver/newest/webdriver/command/
-[responses]: https://docs.rs/webdriver/newest/webdriver/response/
-[errors]: https://docs.rs/webdriver/newest/webdriver/error/enum.ErrorStatus.html
-[Marionette protocol]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/Protocol.html
-[WebDriver]: https://w3c.github.io/webdriver/
-[Marionette]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/
-[Firefox CI]: https://treeherder.mozilla.org/
-[mozconfig]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options
+* [Contributing](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/index.html#for-developers)
 
 
 Contact
-=======
+-------
 
 The mailing list for geckodriver discussion is
 tools-marionette@lists.mozilla.org ([subscribe], [archive]).
@@ -649,4 +62,4 @@ There is also an IRC channel to talk about using and developing
 geckodriver in #ateam on irc.mozilla.org.
 
 [subscribe]: https://lists.mozilla.org/listinfo/tools-marionette
-[archive]: https://groups.google.com/group/mozilla.tools.marionette
+[archive]: https://lists.mozilla.org/pipermail/tools-marionette/