Reported by: Tomas Mlcoch

... so that it adheres to the API documentation.

Reported by: Tomas Mlcoch

Moved SMTP, POP3, IMAP and New Protocol sections to be listed after the
other protocols (FTP, HTTP and TELNET) and SASL to be after SSL and
GnuTLS as these are all security related.

Additionally fixed numbering of the SSL and GnuTLS sections as they
weren't consecutive.

Introducing a number of options to the multi interface that
allows for multiple pipelines to the same host, in order to
optimize the balance between the penalty for opening new
connections and the potential pipelining latency.

Two new options for limiting the number of connections:

CURLMOPT_MAX_HOST_CONNECTIONS - Limits the number of running connections
to the same host. When adding a handle that exceeds this limit,
that handle will be put in a pending state until another handle is
finished, so we can reuse the connection.

CURLMOPT_MAX_TOTAL_CONNECTIONS - Limits the number of connections in total.
When adding a handle that exceeds this limit,
that handle will be put in a pending state until another handle is
finished. The free connection will then be reused, if possible, or
closed if the pending handle can't reuse it.

Several new options for pipelining:

CURLMOPT_MAX_PIPELINE_LENGTH - Limits the pipeling length. If a
pipeline is "full" when a connection is to be reused, a new connection
will be opened if the CURLMOPT_MAX_xxx_CONNECTIONS limits allow it.
If not, the handle will be put in a pending state until a connection is
ready (either free or a pipe got shorter).

CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE - A pipelined connection will not
be reused if it is currently processing a transfer with a content
length that is larger than this.

CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE - A pipelined connection will not
be reused if it is currently processing a chunk larger than this.

CURLMOPT_PIPELINING_SITE_BL - A blacklist of hosts that don't allow
pipelining.

CURLMOPT_PIPELINING_SERVER_BL - A blacklist of server types that don't allow
pipelining.

See the curl_multi_setopt() man page for details.

The flag can be used in pycurl-based applications where using the multi
interface would not be acceptable because of the performance lost caused
by implementing the select() loop in python.

Bug: http://curl.haxx.se/bug/view.cgi?id=1168
Downstream Bug: https://bugzilla.redhat.com/919127

No API change involved.

Info: http://curl.haxx.se/mail/lib-2013-02/0234.html

Patch by: Myk Taylor

No more use exit(3) but instead tell libcurl that no byte has been
written to let it return a `CURLE_WRITE_ERROR`. In addition, check
curl easy handle return code.

Added examples of the list command and clarified existing example URLs
following recent changes.

Updated the imap features list, corrected a typo in the smtp features
and clarified a pop3 feature.

URL examples that included the UID weren't technically correct although
would pass the curl parser.

Corrected layout issues with the POP3 and IMAP URL examples introduced
in commit cb3ae689.

Updated the POP3 sub-section to refer to message ID rather than mailbox.

Added an IMAP sub-section with example URLs depicting the specification
of mailbox, uid and section.

Fixes a typo get → git in docs/CONTRIBUTE.

* Elaborates on default values of some curl_easy_setopt() options.
* Reminds the user to cast variadic arguments to curl_easy_setopt() to
  'void *' where curl internally interprets them as such.
* Clarifies the working of the CURLOPT_SEEKFUNCTION option for
  curl_easy_setopt().
* Fixes typo 'forth' → 'fourth'.
* Elaborates on CURL_SOCKET_TIMEOUT.
* Adds some missing periods.
* Notes that the return value of curl_version() must not be passed to
  free().

* Adds several links to documentation of library functions which were
  missing.
* Marks documentation of deprecated library functions "(deprecated)".
* Removes spurious .html suffixes.

I just noticed Metalink support wasn't listed as a feature of the tool.

Schannel and darwinssl use the certificates built into the
OS to do vert verification instead of bundles. darwinssl
is thread-safe. Corrected typos in the NSS docs.

Use 'vs' directory tree given that 'vc' intended one clashes
with an already existing build target in file Makefile.dist.