insecure.d: expand and clarify

Closes #8017

diff --git a/docs/cmdline-opts/insecure.d b/docs/cmdline-opts/insecure.d
index 5f39a339b93fff271449f3c8ce2a2be40615f023..0fd09cfa2b38a5b82a93e34fcad99812ae0f7d07 100644 (file)
--- a/docs/cmdline-opts/insecure.d
+++ b/docs/cmdline-opts/insecure.d
@@ -2,19 +2,21 @@ Long: insecure
 Short: k
 Help: Allow insecure server connections when using SSL
 Protocols: TLS
-See-also: proxy-insecure cacert
+See-also: proxy-insecure cacert capath
 Category: tls
 Example: --insecure $URL
 Added: 7.10
 ---
-By default, every SSL connection curl makes is verified to be secure. This
-option allows curl to proceed and operate even for server connections
-otherwise considered insecure.
+By default, every SSL/TLS connection curl makes is verified to be secure
+before the transfer takes place. This option makes curl skip the verification
+step and proceed without checking.
 
-The server connection is verified by making sure the server's certificate
-contains the right name and verifies successfully using the cert store.
+When this option is not used, curl verifies the server's TLS certificate
+before it continues: that the certificate contains the right name which
+matches the host name used in the URL and that the certificate has been signed
+by a CA certificate present in the cert store.
 
 See this online resource for further details:
  https://curl.se/docs/sslcerts.html
 
-**WARNING**: this makes the transfer insecure.
+**WARNING**: using this option makes the transfer insecure.