docs: Markdown and misc improvements [ci skip]

Approved-by: Daniel Stenberg
Closes #3896

docs/CIPHERS.md

@@ -271,7 +271,8 @@ When specifying multiple cipher names, separate them with colon (`:`).
 
 ## 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)
@@ -446,9 +447,12 @@ but libcurl maps them to the following case-insensitive names.
 `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`,

docs/CODE_STYLE.md

@@ -9,8 +9,8 @@ style is more important than individual contributors having their own personal
 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
@@ -227,7 +227,7 @@ Align with the "current open" parenthesis:
 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

docs/INSTALL.md

@@ -64,7 +64,7 @@ have OpenSSL installed in your system, you can run configure like this:
    ./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:
 
@@ -121,9 +121,9 @@ libressl.
  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
@@ -148,7 +148,7 @@ make targets available to build libcurl with more features, use:
    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:
 
@@ -172,8 +172,8 @@ If you want to enable LDAPS support then set LDAPS=1.
 ## 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`
 
@@ -200,9 +200,9 @@ protocols:
 
 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
@@ -213,12 +213,12 @@ versions.
 ## 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
@@ -248,13 +248,13 @@ look for dynamic import symbols.
 
 ## 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
@@ -269,12 +269,12 @@ the server. This, of course, includes the root certificates that ship with the
 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
@@ -288,7 +288,7 @@ will run on cats as old as OS X 10.6 ("Snow Leopard") (using bash):
 
 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
@@ -327,7 +327,7 @@ In some cases, you may be able to simplify the above commands to as little as:
 
 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.
@@ -360,8 +360,8 @@ use, here are some other flags that can reduce the size of the library:
 
 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"
@@ -383,7 +383,7 @@ in a lower total size than dynamically linking.
 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