docs: Markdown and misc improvements [ci skip]

## GSKit

## 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.

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

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

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

`DHE-PSK-CHACHA20-POLY1305`,

`DHE-PSK-CHACHA20-POLY1305`,

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

`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_MD2`,

`CALG_MD4`,

`CALG_MD4`,

tastes satisfied.

tastes satisfied.

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

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

`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.

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

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

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

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

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

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

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

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

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

   ./configure --without-ssl

   ./configure --without-ssl

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

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

environment variables prior to running configure.  Something like this should

work:

work:

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

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

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

 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)

 - [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/en-us/cpp/build/reference/md-mt-ld-use-run-time-library)

 - [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://msdn.microsoft.com/en-us/library/ms235460)

 - [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

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

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

   and SSPI support.

   and SSPI support.

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

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

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

environment variables, for example:

environment variables, for example:

## Cygwin

## Cygwin

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

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

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.

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

Run `make`

Run `make`

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

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

 - Modify lib/config-win32.h

 - Modify `lib/config-win32.h`

 - Modify lib/curl_setup.h

 - Modify `lib/curl_setup.h`

 - Modify winbuild/Makefile.vc

 - Modify `winbuild/Makefile.vc`

 - Modify the "Preprocessor Definitions" in the libcurl project

 - Modify the "Preprocessor Definitions" in the libcurl project

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

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

## 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

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

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

following alternatives:

following alternatives:

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

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

 - Modify winbuild/Makefile.vc

 - Modify `winbuild/Makefile.vc`

 - Modify the "Preprocessor Definitions" in the libcurl project

 - Modify the "Preprocessor Definitions" in the libcurl project

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

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

## Legacy Windows and SSL

## Legacy Windows and SSL

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

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

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

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

no longer support the legacy handshakes and algorithms used by those

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

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

Windows you should choose another SSL backend such as OpenSSL.

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

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

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

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

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

currently unimplemented in curl with Secure Transport.

currently unimplemented in curl with Secure Transport.

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

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

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

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

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

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

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

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

set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier

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

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

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

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

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

Download and unpack the curl package.

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

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

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

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.

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

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`,

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

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

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

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

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.

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

Specify them by providing appropriate CFLAGS and LDFLAGS variables on the

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

configure command-line, e.g.

the configure command-line, e.g.

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

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

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

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

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

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

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

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:

line.  Following is a list of appropriate key words:

 - `--disable-cookies`          !cookies

 - `--disable-cookies`          !cookies

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

- 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

  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.

  systems.

- push the git commits and the new tag

- push the git commits and the new tag