sync with central 31a33fc61956.

1 files changed, 30 insertions, 13 deletions

diff --git a/README.md b/README.md
index d596a2e..6dac0b5 100644
--- a/README.md
+++ b/README.md
@@ -538,11 +538,18 @@ the Windows registry.
 
 #### `--connect-existing`
 
-Connecting to an existing Firefox instance.  The instance must have
-Marionette enabled.
+Connect geckodriver to an existing Firefox instance.  This means
+geckodriver will abstain from the default of starting a new Firefox
+session.
 
-To enable the Marionette remote protocol you can pass the `--marionette`
-flag to Firefox.
+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>
@@ -558,16 +565,25 @@ Set the Gecko and geckodriver log level.  Possible values are `fatal`,
 
 #### <code>--marionette-port <var>PORT</var></code>
 
-Port to use for connecting to the Marionette remote protocol.  By default
-it will pick a free port assigned by the system.
+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.
+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>
@@ -577,11 +593,12 @@ useful for debugging [Marionette] internals.
 
 [browser toolbox]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox
 
+
 #### <code>-v<var>[v]</var></code>
 
-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.
+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.
 
 
 Building
@@ -610,10 +627,10 @@ the built executable with `./mach geckodriver -- --other --flags`.
 [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 protocol]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/Protocol.html
 [WebDriver]: https://w3c.github.io/webdriver/webdriver-spec.html
 [FirefoxDriver]: https://github.com/SeleniumHQ/selenium/wiki/FirefoxDriver
-[Marionette]: http://searchfox.org/mozilla-central/source/testing/marionette/README
+[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