docs: Markdown and misc improvements [ci skip]

## GSKit

Ciphers are internally defined as numeric codes (https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_73/apis/gsk_attribute_set_buffer.htm),

Ciphers are internally defined as

[numeric codes](https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_73/apis/gsk_attribute_set_buffer.htm),

but libcurl maps them to the following case-insensitive names.

### SSL2 cipher suites (insecure: disabled by default)

`DHE-PSK-CHACHA20-POLY1305`,

`EDH-RSA-DES-CBC3-SHA`,

## WinSSL

## Schannel

WinSSL allows the enabling and disabling of encryption algorithms, but not specific ciphersuites. They are defined by Microsoft (https://msdn.microsoft.com/en-us/library/windows/desktop/aa375549(v=vs.85).aspx)

Schannel allows the enabling and disabling of encryption algorithms, but not

specific ciphersuites. They are

[defined](https://docs.microsoft.com/windows/desktop/SecCrypto/alg-id) by

Microsoft.

`CALG_MD2`,

`CALG_MD4`,

tastes satisfied.

Our C code has a few style rules. Most of them are verified and upheld by the

"lib/checksrc.pl" script. Invoked with "make checksrc" or even by default by

the build system when built after "./configure --enable-debug" has been used.

`lib/checksrc.pl` script. Invoked with `make checksrc` or even by default by

the build system when built after `./configure --enable-debug` has been used.

It is normally not a problem for anyone to follow the guidelines, as you just

need to copy the style already used in the source code and there are no

Use **#ifdef HAVE_FEATURE** to do conditional code. We avoid checking for

particular operating systems or hardware in the #ifdef lines. The HAVE_FEATURE

shall be generated by the configure script for unix-like systems and they are

hard-coded in the config-[system].h files for the others.

hard-coded in the `config-[system].h` files for the others.

We also encourage use of macros/functions that possibly are empty or defined

to constants when libcurl is built without that feature, to make the code

   ./configure --without-ssl

If you have OpenSSL installed, but with the libraries in one place and the

header files somewhere else, you have to set the LDFLAGS and CPPFLAGS

header files somewhere else, you have to set the `LDFLAGS` and `CPPFLAGS`

environment variables prior to running configure.  Something like this should

work:

 KB140584 is a must for any Windows developer. Especially important is full

 understanding if you are not going to follow the advice given above.

 - [How To Use the C Run-Time](https://support.microsoft.com/kb/94248/en-us)

 - [Run-Time Library Compiler Options](https://docs.microsoft.com/en-us/cpp/build/reference/md-mt-ld-use-run-time-library)

 - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://msdn.microsoft.com/en-us/library/ms235460)

 - [How To Use the C Run-Time](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time)

 - [Run-Time Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)

 - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://docs.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries)

If your app is misbehaving in some strange way, or it is suffering from

memory corruption, before asking for further help, please try first to

   and SSPI support.

If you have any problems linking libraries or finding header files, be sure

to verify that the provided "Makefile.m32" files use the proper paths, and

to verify that the provided `Makefile.m32` files use the proper paths, and

adjust as necessary. It is also possible to override these paths with

environment variables, for example:

## Cygwin

Almost identical to the unix installation. Run the configure script in the

curl source tree root with `sh configure`. Make sure you have the sh

executable in /bin/ or you'll see the configure fail toward the end.

curl source tree root with `sh configure`. Make sure you have the `sh`

executable in `/bin/` or you'll see the configure fail toward the end.

Run `make`

If you want to set any of these defines you have the following options:

 - Modify lib/config-win32.h

 - Modify lib/curl_setup.h

 - Modify winbuild/Makefile.vc

 - Modify `lib/config-win32.h`

 - Modify `lib/curl_setup.h`

 - Modify `winbuild/Makefile.vc`

 - Modify the "Preprocessor Definitions" in the libcurl project

Note: The pre-processor settings can be found using the Visual Studio IDE

## Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds

In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack it is

necessary to make definition of preprocessor symbol USE_LWIPSOCK visible to

necessary to make definition of preprocessor symbol `USE_LWIPSOCK` visible to

libcurl and curl compilation processes. To set this definition you have the

following alternatives:

 - Modify lib/config-win32.h and src/config-win32.h

 - Modify winbuild/Makefile.vc

 - Modify `lib/config-win32.h` and `src/config-win32.h`

 - Modify `winbuild/Makefile.vc`

 - Modify the "Preprocessor Definitions" in the libcurl project

Note: The pre-processor settings can be found using the Visual Studio IDE

## Legacy Windows and SSL

WinSSL (specifically Schannel from Windows SSPI), is the native SSL library in

Windows. However, WinSSL in Windows <= XP is unable to connect to servers that

Schannel (from Windows SSPI), is the native SSL library in Windows. However,

Schannel in Windows <= XP is unable to connect to servers that

no longer support the legacy handshakes and algorithms used by those

versions. If you will be using curl in one of those earlier versions of

Windows you should choose another SSL backend such as OpenSSL.

# Apple iOS and Mac OS X

# Apple iOS and macOS

On modern Apple operating systems, curl can be built to use Apple's SSL/TLS

implementation, Secure Transport, instead of OpenSSL. To build with Secure

OS. The `--cert` and `--engine` options, and their libcurl equivalents, are

currently unimplemented in curl with Secure Transport.

For OS X users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul to

the Secure Transport API that, among other things, added support for the newer

TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you must

build curl on Mountain Lion or later, or by using the equivalent SDK. If you

set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier

version of OS X prior to building curl, then curl will use the new Secure

For macOS users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul

to the Secure Transport API that, among other things, added support for the

newer TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you

must build curl on Mountain Lion or later, or by using the equivalent SDK. If

you set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier

version of macOS prior to building curl, then curl will use the new Secure

Transport API on Mountain Lion and later, and fall back on the older API when

the same curl binary is executed on older cats. For example, running these

commands in curl's directory in the shell will build the code such that it

Download and unpack the curl package.

'cd' to the new directory. (e.g. `cd curl-7.12.3`)

`cd` to the new directory. (e.g. `cd curl-7.12.3`)

Set environment variables to point to the cross-compile toolchain and call

configure with any options you need.  Be sure and specify the `--host` and

There are a number of configure options that can be used to reduce the size of

libcurl for embedded applications where binary size is an important factor.

First, be sure to set the CFLAGS variable when configuring with any relevant

First, be sure to set the `CFLAGS` variable when configuring with any relevant

compiler optimization flags to reduce the size of the binary.  For gcc, this

would mean at minimum the -Os option, and potentially the `-march=X`,

`-mdynamic-no-pic` and `-flto` options as well, e.g.

The GNU compiler and linker have a number of options that can reduce the

size of the libcurl dynamic libraries on some platforms even further.

Specify them by providing appropriate CFLAGS and LDFLAGS variables on the

configure command-line, e.g.

Specify them by providing appropriate `CFLAGS` and `LDFLAGS` variables on

the configure command-line, e.g.

    CFLAGS="-Os -ffunction-sections -fdata-sections

            -fno-unwind-tables -fno-asynchronous-unwind-tables -flto"

Note that the curl test harness can detect the use of some, but not all, of

the `--disable` statements suggested above. Use will cause tests relying on

those features to fail.  The test harness can be manually forced to skip the

relevant tests by specifying certain key words on the runtests.pl command

relevant tests by specifying certain key words on the `runtests.pl` command

line.  Following is a list of appropriate key words:

 - `--disable-cookies`          !cookies

- run "./maketgz 7.34.0" to build the release tarballs. It is important that

  you run this on a machine with the correct set of autotools etc installed

  as this is what then will be shipped and used by most users on *nix like

  as this is what then will be shipped and used by most users on \*nix like

  systems.

- push the git commits and the new tag