improve curl client doc

Author: dbu

clients/curl-client.rst

@@ -12,25 +12,24 @@ To install the cURL client, run:
 
     $ composer require php-http/curl-client
 
-Usage
------
-
-The cURL client needs a :ref:`message <message-factory>` and a :ref:`stream <stream-factory>`
-factory in order to to work::
+.. include:: includes/install-message-factory.inc
 
-    use Http\Client\Curl\Client;
+.. include:: includes/install-discovery.inc
 
-    $client = new Client($messageFactory, $streamFactory);
+Usage
+-----
 
-Using `php-http/message <https://packagist.org/packages/php-http/message>`_::
+The cURL client needs a :ref:`message factory <message-factory>` and a
+:ref:`stream factory <stream-factory>` in order to to work. You can either specify the factory
+explicitly::
 
     use Http\Client\Curl\Client;
     use Http\Message\MessageFactory\DiactorosMessageFactory;
     use Http\Message\StreamFactory\DiactorosStreamFactory;
 
     $client = new Client(new DiactorosMessageFactory(), new DiactorosStreamFactory());
 
-Using `php-http/discovery <https://packagist.org/packages/php-http/discovery>`_::
+Or you can use :doc:`../discovery`::
 
     use Http\Client\Curl\Client;
     use Http\Discovery\MessageFactoryDiscovery;
@@ -53,7 +52,8 @@ You can use `cURL options <http://php.net/curl_setopt>`_ to configure Client::
     ];
     $client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find(), $options);
 
-These options cannot be used (will be overwritten by Client):
+The following options can not be changed in the set up. Most of them are to be provided with the
+request instead:
 
     * CURLOPT_CUSTOMREQUEST
     * CURLOPT_FOLLOWLOCATION

discovery.rst

@@ -2,12 +2,16 @@ Discovery
 =========
 
 The discovery service allows to find and use installed resources.
+
 Under the hood it uses `Puli`_ for the discovery logic. All of our packages provide Puli resources.
 Discovery is simply a convenience wrapper to statically access clients and factories for when
 Dependency Injection is not an option. Discovery is useful in libraries that want to offer
 zero-configuration services relying on the virtual packages. If you have Dependency Injection available,
 using Puli directly is more elegant (see for example the Symfony HttplugBundle).
 
+Consumers of libraries using discovery still need to make sure they install one of the implementations.
+Discovery can only find installed code, not fetch code from other sources.
+
 Currently available discovery services:
 
 - HTTP Client Discovery
@@ -32,7 +36,7 @@ In both cases you have to install the discovery package itself:
 
 .. code-block:: bash
 
-        $ composer require php-http/discovery
+    $ composer require php-http/discovery
 
 As mentioned above, discovery relies on Puli. In order to use discovery, you need to also set up Puli.
 The easiest way is installing the composer-plugin which automatically configures all the composer packages to act as