wcurl: document how --curl-options splits its value

README.md

@@ -108,6 +108,19 @@ be using curl directly if your use case is not covered.
 Any option supported by curl can be set here. This is not used by wcurl; it is
 instead forwarded to the curl invocation.
 
+The value is split on whitespace (spaces, tabs and newlines) and each resulting
+word is passed to curl as a separate argument. Quotes and backslashes are not
+interpreted, so an argument containing whitespace cannot be passed this way. For
+example, `--curl-options='-H "Cookie: a=1; b=2"'` passes the four arguments
+`-H`, `"Cookie:`, `a=1;` and `b=2"` to curl, which treats the extra words as
+URLs to download.
+
+To pass arguments that contain whitespace, write them to a curl config file and
+pass it with `--curl-options="--config <FILE>"`, or use curl directly.
+
+Everything in `<CURL_OPTIONS>` becomes part of the curl command line, so never
+build it from untrusted input.
+
 # URL
 
 URL to be downloaded. Anything that is not a parameter is considered

wcurl

@@ -74,7 +74,9 @@ Options:
   -h, --help: Print this usage message.
 
   <CURL_OPTIONS>: Any option supported by curl can be set here. This is not used by wcurl; it is
-                 instead forwarded to the curl invocation.
+                 instead forwarded to the curl invocation. The value is split on whitespace and
+                 quotes are not interpreted; use '--config <FILE>' for arguments containing
+                 whitespace. Never build it from untrusted input.
 
   <URL>: URL to be downloaded. Anything that is not a parameter is considered
          an URL. Whitespace is percent-encoded and the URL is passed to curl, which

wcurl.1

@@ -78,6 +78,19 @@ Print help message.
 .SH CURL_OPTIONS
 Any option supported by curl can be set here. This is not used by \fBwcurl\fP; it
 is instead forwarded to the curl invocation.
+
+The value is split on whitespace (spaces, tabs and newlines) and each resulting
+word is passed to curl as a separate argument. Quotes and backslashes are not
+interpreted, so an argument containing whitespace cannot be passed this way. For
+example, \fB\--curl\-options=\(aq\-H "Cookie: a=1; b=2"\(aq\fP passes the four arguments
+\fI\-H\fP, \fI"Cookie:\fP, \fIa=1;\fP and \fIb=2"\fP to curl, which treats the extra words as
+URLs to download.
+
+To pass arguments that contain whitespace, write them to a curl config file and
+pass it with \fB\--curl\-options="\--config <FILE>"\fP, or use curl directly.
+
+Everything in <CURL_OPTIONS> becomes part of the curl command line, so never
+build it from untrusted input.
 .SH URL
 URL to be downloaded. Anything that is not a parameter is considered
 an URL. Whitespace is percent\-encoded and the URL is passed to curl, which

wcurl.md

@@ -107,6 +107,19 @@ Print help message.
 Any option supported by curl can be set here. This is not used by **wcurl**; it
 is instead forwarded to the curl invocation.
 
+The value is split on whitespace (spaces, tabs and newlines) and each resulting
+word is passed to curl as a separate argument. Quotes and backslashes are not
+interpreted, so an argument containing whitespace cannot be passed this way. For
+example, **--curl-options='-H "Cookie: a=1; b=2"'** passes the four arguments
+`-H`, `"Cookie:`, `a=1;` and `b=2"` to curl, which treats the extra words as
+URLs to download.
+
+To pass arguments that contain whitespace, write them to a curl config file and
+pass it with **--curl-options="--config \<FILE\>"**, or use curl directly.
+
+Everything in \<CURL_OPTIONS\> becomes part of the curl command line, so never
+build it from untrusted input.
+
 # URL
 
 URL to be downloaded. Anything that is not a parameter is considered