to make it obvious to users trying to use the feature with TLS backends
not supporting it.

Discussed in #781
Reported-by: Travis Burtrum

... not used by any test yet but can be used stand-alone.

Closes #786

As discussed in #785

Reported-by: mgendre
Closes #784

Closes #675

curl_printf.h defines printf to curl_mprintf, etc. This can cause
problems with external headers which may use
__attribute__((format(printf, ...))) markers etc.

To avoid that they cause problems with system includes, we include
curl_printf.h after any system headers. That makes the three last
headers to always be, and we keep them in this order:

 curl_printf.h
 curl_memory.h
 memdebug.h

None of them include system headers, they all do funny #defines.

Reported-by: David Benjamin

Fixes #743

Mostly because they're not needed, because memdebug.h is always included
last of all headers so the others already included the correct ones.

But also, starting now we don't want this to accidentally include any
system headers, as the header included _before_ this header may add
defines and other fun stuff that we won't want used in system includes.

It does open up a miniscule risk that one of the other protocols that
libcurl could use would send back a Content-Disposition header and then
curl would act on it even if not HTTP.

A future mitigation for this risk would be to allow the callback to ask
libcurl which protocol is being used.

Verified with test 1312

Closes #760

This script now also scans src/tool_getparam.c, docs/curl.1 and
src/tool_help.c and will warn if any of them lists a command line option
not mentioned in one of the other places.

In commit 2e42b0a2 (Jan 2008) we made the option "--socks" deprecated
and it has not been documented since. The more explicit socks options
(like --socks4 or --socks5) should be used.

It was mentioned as deprecated already in commit ae1912cb from
1999. It has not been documented in this millennium.

Even if deprecated, document it so that people will find it as old
scripts may still use it.

The code said "telnet-options" but no documentation ever said so. It
worked fine since the code is fine with a unique match of the first
part.

It has been deprecated and undocumented since commit ad5ead8b (Dec
2003). --ftp-port is the proper long option name.

To make the aliases list reflect reality.

... moved around options so that parsing the code to find all
single-letter options easier.

Bug: https://curl.haxx.se/mail/lib-2016-04/0126.html
Reported-by: Bru Rom

- checks that each option has its own man page present

- checks that each option is mentioned in its corresponding index man
  page

... although it is deprecated.

This also fixes PolarSSL session resume.

Prior to this change the TLS session information wasn't properly
saved and restored for PolarSSL and mbedTLS.

Bug: https://curl.haxx.se/mail/lib-2016-01/0070.html
Reported-by: Thomas Glanzmann

Bug: https://curl.haxx.se/mail/lib-2016-04/0095.html
Reported-by: Moti Avrahami

Fixes #779

OpenSSL 1.1.0-pre seems to return NULL(?) for a whole lot of those
numbers so make sure the function handles this.

Reported-by: Linus Nordberg

Previously, connections were closed immediately before the user had a
chance to extract the socket when the proxy required Negotiate
authentication.

This regression was brought in with the security fix in commit
79b9d5f1

Closes #655