FAQ: refreshed

 - remove a few ancient questions
 - add configure with static libs question
 - updated wording in several places
 - lowercased curl

Closes #6177

1 files changed, 48 insertions, 95 deletions

diff --git a/docs/FAQ b/docs/FAQ
index c4f2d53ff..e1b4b777c 100644
--- a/docs/FAQ
+++ b/docs/FAQ
@@ -24,11 +24,8 @@ FAQ
   1.15 How do I port libcurl to my OS?
 
  2. Install Related Problems
-  2.1 configure doesn't find OpenSSL even when it is installed
-   2.1.1 native linker doesn't find OpenSSL
-   2.1.2 only the libssl lib is missing
+  2.1 configure fails when using static libraries
   2.2 Does curl work/build with other SSL libraries?
-  2.3 Where can I find a copy of LIBEAY32.DLL?
   2.4 Does curl support SOCKS (RFC 1928) ?
 
  3. Usage Problems
@@ -56,7 +53,6 @@ FAQ
   3.22 curl -X gives me HTTP problems
 
  4. Running Problems
-  4.1 Problems connecting to SSL servers.
   4.2 Why do I get problems when I use & or % in the URL?
   4.3 How can I use {, }, [ or ] to specify multiple URLs?
   4.4 Why do I get downloaded data even though the web page doesn't exist?
@@ -68,9 +64,9 @@ FAQ
    4.5.5 "405 Method Not Allowed"
    4.5.6 "301 Moved Permanently"
   4.6 Can you tell me what error code 142 means?
-  4.7 How do I keep user names and passwords secret in Curl command lines?
+  4.7 How do I keep user names and passwords secret in curl command lines?
   4.8 I found a bug!
-  4.9 Curl can't authenticate to the server that requires NTLM?
+  4.9 curl can't authenticate to the server that requires NTLM?
   4.10 My HTTP request using HEAD, PUT or DELETE doesn't work!
   4.11 Why do my HTTP range requests return the full document?
   4.12 Why do I get "certificate verify failed" ?
@@ -129,7 +125,7 @@ FAQ
   originally with URL spelled in uppercase to make it obvious it deals with
   URLs. The fact it can also be pronounced 'see URL' also helped, it works as
   an abbreviation for "Client URL Request Library" or why not the recursive
-  version: "Curl URL Request Library".
+  version: "curl URL Request Library".
 
   The cURL project produces two products:
 
@@ -185,22 +181,22 @@ FAQ
 
   1.3 What is curl not?
 
-  Curl is not a wget clone. That is a common misconception.  Never, during
+  curl is not a wget clone. That is a common misconception.  Never, during
   curl's development, have we intended curl to replace wget or compete on its
-  market. Curl is targeted at single-shot file transfers.
+  market. curl is targeted at single-shot file transfers.
 
-  Curl is not a website mirroring program. If you want to use curl to mirror
-  something: fine, go ahead and write a script that wraps around curl to make
-  it reality (like curlmirror.pl does).
+  curl is not a website mirroring program. If you want to use curl to mirror
+  something: fine, go ahead and write a script that wraps around curl or use
+  libcurl to make it reality.
 
-  Curl is not an FTP site mirroring program. Sure, get and send FTP with curl
+  curl is not an FTP site mirroring program. Sure, get and send FTP with curl
   but if you want systematic and sequential behavior you should write a
   script (or write a new program that interfaces libcurl) and do it.
 
-  Curl is not a PHP tool, even though it works perfectly well when used from
+  curl is not a PHP tool, even though it works perfectly well when used from
   or with PHP (when using the PHP/CURL module).
 
-  Curl is not a program for a single operating system. Curl exists, compiles,
+  curl is not a program for a single operating system. curl exists, compiles,
   builds and runs under a wide range of operating systems, including all
   modern Unixes (and a bunch of older ones too), Windows, Amiga, BeOS, OS/2,
   OS X, QNX etc.
@@ -211,12 +207,12 @@ FAQ
   better. We do however believe in a few rules when it comes to the future of
   curl:
 
-  Curl -- the command line tool -- is to remain a non-graphical command line
+  curl -- the command line tool -- is to remain a non-graphical command line
   tool. If you want GUIs or fancy scripting capabilities, you should look for
   another tool that uses libcurl.
 
   We do not add things to curl that other small and available tools already do
-  very well at the side. Curl's output can be piped into another program or
+  very well at the side. curl's output can be piped into another program or
   redirected to another file for the next program to interpret.
 
   We focus on protocol related issues and improvements. If you want to do more
@@ -376,7 +372,8 @@ FAQ
   lots of people who can review patches, comment on them and "receive" them
   properly.
 
-  Lots of more details are found in the CONTRIBUTE and INTERNALS docs.
+  Lots of more details are found in the CONTRIBUTE.md and INTERNALS.md
+  documents.
 
   1.15 How do I port libcurl to my OS?
 
@@ -394,46 +391,27 @@ FAQ
 
 2. Install Related Problems
 
-  2.1 configure doesn't find OpenSSL even when it is installed
+  2.1 configure fails when using static libraries
 
-  This may be because of several reasons.
+  You may find that configure fails to properly detect the entire dependency
+  chain of libraries when you provide static versions of the libraries that
+  configure checks for.
 
-    2.1.1 native linker doesn't find openssl
+  The reason why static libraries is much harder to deal with is that for them
+  we don't get any help but the script itself must know or check what more
+  libraries that are needed (with shared libraries, that dependency "chain" is
+  handled automatically). This is a very error-prone process and one that also
+  tends to vary over time depending on the release versions of the involved
+  components and may also differ between operating systems.
 
-    Affected platforms:
-      Solaris (native cc compiler)
-      HPUX (native cc compiler)
-      SGI IRIX (native cc compiler)
-      SCO UNIX (native cc compiler)
+  For that reason, configure does very little attempts to actually figure this
+  out and you are instead encouraged to set LIBS and LDFLAGS accordingly when
+  you invoke configure, and point out the needed libraries and set the
+  necessary flags yourself.
 
-    When configuring curl, I specify --with-ssl. OpenSSL is installed in
-    /usr/local/ssl Configure reports SSL in /usr/local/ssl, but fails to find
-    CRYPTO_lock in -lcrypto
+  2.2 Does curl work with other SSL libraries?
 
-    Cause: The cc for this test places the -L/usr/local/ssl/lib AFTER
-    -lcrypto, so ld can't find the library. This is due to a bug in the GNU
-    autoconf tool.
-
-    Workaround: Specifying "LDFLAGS=-L/usr/local/ssl/lib" in front of
-    ./configure places the -L/usr/local/ssl/lib early enough in the command
-    line to make things work
-
-    2.1.2 only the libssl lib is missing
-
-    If all include files and the libcrypto lib is present, with only the
-    libssl being missing according to configure, this is most likely because
-    a few functions are left out from the libssl.
-
-    If the function names missing include RSA or RSAREF you can be certain
-    that this is because libssl requires the RSA and RSAREF libs to build.
-
-    See the INSTALL file section that explains how to add those libs to
-    configure. Make sure that you remove the config.cache file before you
-    rerun configure with the new flags.
-
-  2.2 Does curl work/build with other SSL libraries?
-
-  Curl has been written to use a generic SSL function layer internally, and
+  curl has been written to use a generic SSL function layer internally, and
   that SSL functionality can then be provided by one out of many different SSL
   backends.
 
@@ -443,20 +421,10 @@ FAQ
   i), or BearSSL. They all have their pros and cons, and we try to maintain a
   comparison of them here: https://curl.se/docs/ssl-compared.html
 
-  2.3 Where can I find a copy of LIBEAY32.DLL?
-
-  That is an OpenSSL binary built for Windows.
-
-  Curl can be built with OpenSSL to do the SSL stuff. The LIBEAY32.DLL is then
-  what curl needs on a windows machine to do https:// etc. Check out the curl
-  website to find accurate and up-to-date pointers to recent OpenSSL DLLs and
-  other binary packages.
-
   2.4 Does curl support SOCKS (RFC 1928) ?
 
   Yes, SOCKS 4 and 5 are supported.
 
-
 3. Usage problems
 
   3.1 curl: (1) SSL is disabled, https: not supported
@@ -480,18 +448,18 @@ FAQ
 
   3.2 How do I tell curl to resume a transfer?
 
-  Curl supports resumed transfers both ways on both FTP and HTTP.
+  curl supports resumed transfers both ways on both FTP and HTTP.
   Try the -C option.
 
   3.3 Why doesn't my posting using -F work?
 
-  You can't arbitrarily use -F or -d, the choice between -F or -d depends on the
-  HTTP operation you need curl to do and what the web server that will receive
-  your post expects.
+  You can't arbitrarily use -F or -d, the choice between -F or -d depends on
+  the HTTP operation you need curl to do and what the web server that will
+  receive your post expects.
 
-  If the form you're trying to submit uses the type 'multipart/form-data', then
-  and only then you must use the -F type. In all the most common cases, you
-  should use -d which then causes a posting with the type
+  If the form you're trying to submit uses the type 'multipart/form-data',
+  then and only then you must use the -F type. In all the most common cases,
+  you should use -d which then causes a posting with the type
   'application/x-www-form-urlencoded'.
 
   This is described in some detail in the MANUAL and TheArtOfHttpScripting
@@ -539,7 +507,7 @@ FAQ
 
   3.8 How do I tell curl to follow HTTP redirects?
 
-  Curl does not follow so-called redirects by default. The Location: header
+  curl does not follow so-called redirects by default. The Location: header
   that informs the client about this is only interpreted if you're using the
   -L/--location option. As in:
 
@@ -574,7 +542,7 @@ FAQ
 
   3.10 What about SOAP, WebDAV, XML-RPC or similar protocols over HTTP?
 
-  Curl adheres to the HTTP spec, which basically means you can play with *any*
+  curl adheres to the HTTP spec, which basically means you can play with *any*
   protocol that is built on top of HTTP. Protocols such as SOAP, WEBDAV and
   XML-RPC are all such ones. You can use -X to set custom requests and -H to
   set custom headers (or replace internally generated ones).
@@ -626,7 +594,7 @@ FAQ
 
   3.14 Does curl support Javascript or PAC (automated proxy config)?
 
-  Many web pages do magic stuff using embedded Javascript. Curl and libcurl
+  Many web pages do magic stuff using embedded Javascript. curl and libcurl
   have no built-in support for that, so it will be treated just like any other
   contents.
 
@@ -790,21 +758,6 @@ FAQ
 
 4. Running Problems
 
-  4.1 Problems connecting to SSL servers.
-
-  It took a very long time before we could sort out why curl had problems to
-  connect to certain SSL servers when using SSLeay or OpenSSL v0.9+.  The
-  error sometimes showed up similar to:
-
-  16570:error:1407D071:SSL routines:SSL2_READ:bad mac decode:s2_pkt.c:233:
-
-  It turned out to be because many older SSL servers don't deal with SSLv3
-  requests properly. To correct this problem, tell curl to select SSLv2 from
-  the command line (-2/--sslv2).
-
-  There have also been examples where the remote server didn't like the SSLv2
-  request and instead you had to force curl to use SSLv3 with -3/--sslv3.
-
   4.2 Why do I get problems when I use & or % in the URL?
 
   In general unix shells, the & symbol is treated specially and when used, it
@@ -841,7 +794,7 @@ FAQ
 
   4.4 Why do I get downloaded data even though the web page doesn't exist?
 
-  Curl asks remote servers for the page you specify. If the page doesn't exist
+  curl asks remote servers for the page you specify. If the page doesn't exist
   at the server, the HTTP protocol defines how the server should respond and
   that means that headers and a "page" will be returned. That's simply how
   HTTP works.
@@ -900,7 +853,7 @@ FAQ
   appreciate a detailed bug report from you that describes how we could go
   ahead and repeat this!
 
-  4.7 How do I keep user names and passwords secret in Curl command lines?
+  4.7 How do I keep user names and passwords secret in curl command lines?
 
   This problem has two sides:
 
@@ -934,7 +887,7 @@ FAQ
   If there is a bug, read the BUGS document first. Then report it as described
   in there.
 
-  4.9 Curl can't authenticate to the server that requires NTLM?
+  4.9 curl can't authenticate to the server that requires NTLM?
 
   NTLM support requires OpenSSL, GnuTLS, mbedTLS, NSS, Secure Transport, or
   Microsoft Windows libraries at build-time to provide this functionality.
@@ -967,7 +920,7 @@ FAQ
       SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
 
   Then it means that curl couldn't verify that the server's certificate was
-  good. Curl verifies the certificate using the CA cert bundle that comes with
+  good. curl verifies the certificate using the CA cert bundle that comes with
   the curl installation.
 
   To disable the verification (which makes it act like curl did before 7.10),
@@ -1219,7 +1172,7 @@ FAQ
   5.6 What about Keep-Alive or persistent connections?
 
   curl and libcurl have excellent support for persistent connections when
-  transferring several files from the same server.  Curl will attempt to reuse
+  transferring several files from the same server.  curl will attempt to reuse
   connections for all URLs specified on the same command line/config file, and
   libcurl will reuse connections for all transfers that are made using the
   same libcurl handle.
@@ -1438,7 +1391,7 @@ FAQ
 
 6. License Issues
 
-  Curl and libcurl are released under a MIT/X derivate license. The license is
+  curl and libcurl are released under a MIT/X derivate license. The license is
   very liberal and should not impose a problem for your project. This section
   is just a brief summary for the cases we get the most questions. (Parts of
   this section was much enhanced by Bjorn Reese.)