cmdline/docs: add a required 'multi' keyword for each option

The keyword specifies how option works when specified multiple times:

 - single: the last provided value replaces the earlier ones
 - append: it supports being provided multiple times
 - boolean: on/off values
 - mutex: flag-like option that disable anoter flag

The 'gen.pl' script then outputs the proper and unified language for
each option's multi-use behavior in the generated man page.

The multi: header is requires in each .d file and will cause build error
if missing or set to an unknown value.

Closes #9759

docs/cmdline-opts/MANPAGE.md

@@ -23,20 +23,22 @@ Each file has a set of meta-data and a body of text.
 
 ### Meta-data
 
-    Short: (single letter, without dash)
-    Long: (long form name, without dashes)
+    Added: (version number in which this was added)
     Arg: (the argument the option takes)
+    c: (copyright line)
+    Example: (example command line, without "curl" and can use `$URL`)
+    Experimental: yes (if so)
+    Help: (short text for the --help output for this option)
+    Long: (long form name, without dashes)
     Magic: (description of "magic" options)
-    Tags: (space separated list)
-    Protocols: (space separated list for which protocols this option works)
-    Added: (version number in which this was added)
+    Multi: single/append/boolean/mutex (if used more than once)
     Mutexed: (space separated list of options this overrides, no dashes)
+    Protocols: (space separated list for which protocols this option works)
     Requires: (space separated list of features this requires, no dashes)
     See-also: (space separated list of related options, no dashes)
-    Help: (short text for the --help output for this option)
-    Example: (example command line, without "curl" and can use `$URL`)
-    c: (copyright line)
+    Short: (single letter, without dash)
     SPDX-License-Identifier: curl
+    Tags: (space separated list)
     --- (end of meta-data)
 
 ### Body

docs/cmdline-opts/abstract-unix-socket.d

@@ -8,6 +8,7 @@ Protocols: HTTP
 Category: connection
 See-also: unix-socket
 Example: --abstract-unix-socket socketpath $URL
+Multi: single
 ---
 Connect through an abstract Unix domain socket, instead of using the network.
 Note: netstat shows the path of an abstract socket prefixed with '@', however

docs/cmdline-opts/alt-svc.d

@@ -8,6 +8,7 @@ Added: 7.64.1
 Category: http
 See-also: resolve connect-to
 Example: --alt-svc svc.txt $URL
+Multi: append
 ---
 This option enables the alt-svc parser in curl. If the file name points to an
 existing alt-svc cache file, that will be used. After a completed transfer,

docs/cmdline-opts/anyauth.d

@@ -7,6 +7,7 @@ See-also: proxy-anyauth basic digest
 Category: http proxy auth
 Example: --anyauth --user me:pwd $URL
 Added: 7.10.6
+Multi: mutex
 ---
 Tells curl to figure out authentication method by itself, and use the most
 secure one the remote site claims to support. This is done by first doing a

docs/cmdline-opts/append.d

@@ -8,6 +8,7 @@ Category: ftp sftp
 See-also: range continue-at
 Example: --upload-file local --append ftp://example.com/
 Added: 4.8
+Multi: boolean
 ---
 When used in an upload, this makes curl append to the target file instead of
 overwriting it. If the remote file does not exist, it will be created. Note

docs/cmdline-opts/aws-sigv4.d

@@ -7,6 +7,7 @@ Category: auth http
 Added: 7.75.0
 See-also: basic user
 Example: --aws-sigv4 "aws:amz:east-2:es" --user "key:secret" $URL
+Multi: single
 ---
 Use AWS V4 signature authentication in the transfer.
 

docs/cmdline-opts/basic.d

@@ -7,6 +7,7 @@ Protocols: HTTP
 Category: auth
 Example: -u name:password --basic $URL
 Added: 7.10.6
+Multi: mutex
 ---
 Tells curl to use HTTP Basic authentication with the remote host. This is the
 default and this option is usually pointless, unless you use it to override a

docs/cmdline-opts/cacert.d

@@ -8,6 +8,7 @@ Category: tls
 See-also: capath insecure
 Example: --cacert CA-file.txt $URL
 Added: 7.5
+Multi: single
 ---
 Tells curl to use the specified certificate file to verify the peer. The file
 may contain multiple CA certificates. The certificate(s) must be in PEM
@@ -35,5 +36,3 @@ preferred method of verifying the peer's certificate chain.
 with libcurl 7.60 or later. This option is supported for backward
 compatibility with other SSL engines; instead it is recommended to use
 Windows' store of root certificates (the default for Schannel).
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/capath.d

@@ -8,6 +8,7 @@ Category: tls
 See-also: cacert insecure
 Example: --capath /local/directory $URL
 Added: 7.9.8
+Multi: single
 ---
 Tells curl to use the specified certificate directory to verify the
 peer. Multiple paths can be provided by separating them with ":" (e.g.
@@ -17,5 +18,4 @@ c_rehash utility supplied with OpenSSL. Using --capath can allow
 OpenSSL-powered curl to make SSL-connections much more efficiently than using
 --cacert if the --cacert file contains many CA certificates.
 
-If this option is set, the default capath value will be ignored, and if it is
-used several times, the last one will be used.
+If this option is set, the default capath value will be ignored.

docs/cmdline-opts/cert-status.d

@@ -7,12 +7,13 @@ Help: Verify the status of the server cert via OCSP-staple
 Category: tls
 See-also: pinnedpubkey
 Example: --cert-status $URL
+Multi: boolean
 ---
 Tells curl to verify the status of the server certificate by using the
 Certificate Status Request (aka. OCSP stapling) TLS extension.
 
 If this option is enabled and the server sends an invalid (e.g. expired)
-response, if the response suggests that the server certificate has been revoked,
-or no response at all is received, the verification fails.
+response, if the response suggests that the server certificate has been
+revoked, or no response at all is received, the verification fails.
 
 This is currently only implemented in the OpenSSL, GnuTLS and NSS backends.

docs/cmdline-opts/cert-type.d

@@ -8,6 +8,7 @@ See-also: cert key key-type
 Category: tls
 Example: --cert-type PEM --cert file $URL
 Added: 7.9.3
+Multi: single
 ---
 Tells curl what type the provided client certificate is using. PEM, DER, ENG
 and P12 are recognized types.
@@ -15,5 +16,3 @@ and P12 are recognized types.
 The default type depends on the TLS backend and is usually PEM, however for
 Secure Transport and Schannel it is P12. If --cert is a pkcs11: URI then ENG is
 the default type.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/cert.d

@@ -9,6 +9,7 @@ See-also: cert-type key key-type
 Category: tls
 Example: --cert certfile --key keyfile $URL
 Added: 5.0
+Multi: single
 ---
 Tells curl to use the specified client certificate file when getting a file
 with HTTPS, FTPS or another SSL-based protocol. The certificate must be in
@@ -55,5 +56,3 @@ usually a SHA-1 hex string which you can see in certificate details. Following
 store locations are supported: CurrentUser, LocalMachine, CurrentService,
 Services, CurrentUserGroupPolicy, LocalMachineGroupPolicy,
 LocalMachineEnterprise.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/ciphers.d

@@ -8,10 +8,9 @@ Category: tls
 See-also: tlsv1.3
 Example: --ciphers ECDHE-ECDSA-AES256-CCM8 $URL
 Added: 7.9
+Multi: single
 ---
 Specifies which ciphers to use in the connection. The list of ciphers must
 specify valid ciphers. Read up on SSL cipher list details on this URL:
 
  https://curl.se/docs/ssl-ciphers.html
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/compressed-ssh.d

@@ -7,6 +7,7 @@ Added: 7.56.0
 Category: scp ssh
 See-also: compressed
 Example: --compressed-ssh sftp://example.com/
+Multi: boolean
 ---
 Enables built-in SSH compression.
 This is a request, not an order; the server may or may not do it.

docs/cmdline-opts/compressed.d

@@ -7,6 +7,7 @@ Category: http
 Example: --compressed $URL
 See-also: compressed-ssh
 Added: 7.10
+Multi: boolean
 ---
 Request a compressed response using one of the algorithms curl supports, and
 automatically decompress the content. Headers are not modified.

docs/cmdline-opts/config.d

@@ -8,6 +8,7 @@ Category: curl
 Example: --config file.txt $URL
 Added: 4.10
 See-also: disable
+Multi: append
 ---
 Specify a text file to read curl arguments from. The command line arguments
 found in the text file will be used as if they were provided on the command
@@ -73,5 +74,3 @@ checks for one in the same dir the curl executable is placed.
 
 On Windows two filenames are checked per location: .curlrc and _curlrc,
 preferring the former. Older versions on Windows checked for _curlrc only.
-
-This option can be used multiple times to load multiple config files.

docs/cmdline-opts/connect-timeout.d

@@ -8,10 +8,9 @@ Category: connection
 Example: --connect-timeout 20 $URL
 Example: --connect-timeout 3.14 $URL
 Added: 7.7
+Multi: single
 ---
 Maximum time in seconds that you allow curl's connection to take.  This only
 limits the connection phase, so if curl connects within the given period it
 will continue - if not it will exit.  Since version 7.32.0, this option
 accepts decimal values.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/connect-to.d

@@ -7,6 +7,7 @@ Added: 7.49.0
 See-also: resolve header
 Category: connection
 Example: --connect-to example.com:443:example.net:8443 $URL
+Multi: append
 ---
 
 For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.
@@ -21,5 +22,3 @@ request's original host/port".
 A "host" specified to this option is compared as a string, so it needs to
 match the name used in request URL. It can be either numerical such as
 "127.0.0.1" or the full host name such as "example.org".
-
-This option can be used many times to add many connect rules.

docs/cmdline-opts/continue-at.d

@@ -9,6 +9,7 @@ Category: connection
 Example: -C - $URL
 Example: -C 400 $URL
 Added: 4.8
+Multi: single
 ---
 Continue/Resume a previous file transfer at the given offset. The given offset
 is the exact number of bytes that will be skipped, counting from the beginning
@@ -17,5 +18,3 @@ uploads, the FTP server command SIZE will not be used by curl.
 
 Use "-C -" to tell curl to automatically find out where/how to resume the
 transfer. It then uses the given output/input files to figure that out.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/cookie-jar.d

@@ -10,6 +10,7 @@ Example: -c store-here.txt $URL
 Example: -c store-here.txt -b read-these $URL
 Added: 7.9
 See-also: cookie
+Multi: single
 ---
 Specify to which file you want curl to write all cookies after a completed
 operation. Curl writes all cookies from its in-memory cookie storage to the
@@ -26,6 +27,3 @@ If the cookie jar cannot be created or written to, the whole curl operation
 will not fail or even report an error clearly. Using --verbose will get a
 warning displayed, but that is the only visible feedback you get about this
 possibly lethal situation.
-
-If this option is used several times, the last specified file name will be
-used.

docs/cmdline-opts/cookie.d

@@ -10,6 +10,7 @@ Example: -b cookiefile $URL
 Example: -b cookiefile -c cookiefile $URL
 See-also: cookie-jar junk-session-cookies
 Added: 4.9
+Multi: append
 ---
 Pass the data to the HTTP server in the Cookie header. It is supposedly the
 data previously received from the server in a "Set-Cookie:" line. The data
@@ -36,8 +37,6 @@ cookie is not sent since the domain will never match. To address this, set a
 domain in Set-Cookie line (doing that will include sub-domains) or preferably:
 use the Netscape format.
 
-This option can be used multiple times.
-
 Users often want to both read cookies from a file and write updated cookies
 back to a file, so using both --cookie and --cookie-jar in the same command
 line is common.

docs/cmdline-opts/create-dirs.d

@@ -6,6 +6,7 @@ Category: curl
 Example: --create-dirs --output local/dir/file $URL
 Added: 7.10.3
 See-also: ftp-create-dirs output-dir
+Multi: boolean
 ---
 When used in conjunction with the --output option, curl will create the
 necessary local directory hierarchy as needed. This option creates the

docs/cmdline-opts/create-file-mode.d

@@ -8,11 +8,10 @@ Category: sftp scp file upload
 See-also: ftp-create-dirs
 Added: 7.75.0
 Example: --create-file-mode 0777 -T localfile sftp://example.com/new
+Multi: single
 ---
 When curl is used to create files remotely using one of the supported
 protocols, this option allows the user to set which 'mode' to set on the file
 at creation time, instead of the default 0644.
 
 This option takes an octal number as argument.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/crlf.d

@@ -7,6 +7,7 @@ Category: ftp smtp
 Example: --crlf -T file ftp://example.com/
 Added: 5.7
 See-also: use-ascii
+Multi: boolean
 ---
 Convert LF to CRLF in upload. Useful for MVS (OS/390).
 

docs/cmdline-opts/crlfile.d

@@ -8,8 +8,7 @@ Added: 7.19.7
 Category: tls
 Example: --crlfile rejects.txt $URL
 See-also: cacert capath
+Multi: single
 ---
 Provide a file using PEM format with a Certificate Revocation List that may
 specify peer certificates that are to be considered revoked.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/curves.d

@@ -8,6 +8,7 @@ Added: 7.73.0
 Category: tls
 Example: --curves X25519 $URL
 See-also: ciphers
+Multi: single
 ---
 Tells curl to request specific curves to use during SSL session establishment
 according to RFC 8422, 5.1.  Multiple algorithms can be provided by separating

docs/cmdline-opts/data-ascii.d

@@ -8,5 +8,6 @@ Category: http post upload
 Example: --data-ascii @file $URL
 Added: 7.2
 See-also: data-binary data-raw data-urlencode
+Multi: append
 ---
 This is just an alias for --data.

docs/cmdline-opts/data-binary.d

@@ -8,6 +8,7 @@ Category: http post upload
 Example: --data-binary @filename $URL
 Added: 7.2
 See-also: data-ascii
+Multi: append
 ---
 This posts data exactly as specified with no extra processing whatsoever.
 

docs/cmdline-opts/data-raw.d

@@ -9,6 +9,7 @@ See-also: data
 Category: http post upload
 Example: --data-raw "hello" $URL
 Example: --data-raw "@at@at@" $URL
+Multi: append
 ---
 This posts data similarly to --data but without the special
 interpretation of the @ character.

docs/cmdline-opts/data-urlencode.d

@@ -11,6 +11,7 @@ Example: --data-urlencode name=val $URL
 Example: --data-urlencode =encodethis $URL
 Example: --data-urlencode name@file $URL
 Example: --data-urlencode @fileonly $URL
+Multi: append
 ---
 This posts data, similar to the other --data options with the exception
 that this performs URL-encoding.

docs/cmdline-opts/data.d

@@ -12,6 +12,7 @@ Example: -d "name=curl" $URL
 Example: -d "name=curl" -d "tool=cmdline" $URL
 Example: -d @filename $URL
 Added: 4.0
+Multi: append
 ---
 Sends the specified data in a POST request to the HTTP server, in the same way
 that a browser does when a user has filled in an HTML form and presses the

docs/cmdline-opts/delegation.d

@@ -8,6 +8,7 @@ Category: auth
 Example: --delegation "none" $URL
 Added: 7.22.0
 See-also: insecure ssl
+Multi: single
 ---
 Set LEVEL to tell the server what it is allowed to delegate when it
 comes to user credentials.
@@ -20,5 +21,3 @@ service ticket, which is a matter of realm policy.
 .IP "always"
 Unconditionally allow the server to delegate.
 .RE
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/digest.d

@@ -8,9 +8,8 @@ See-also: user proxy-digest anyauth
 Category: proxy auth http
 Example: -u name:password --digest $URL
 Added: 7.10.6
+Multi: boolean
 ---
 Enables HTTP Digest authentication. This is an authentication scheme that
 prevents the password from being sent over the wire in clear text. Use this in
 combination with the normal --user option to set user name and password.
-
-If this option is used several times, only the first one is used.

docs/cmdline-opts/disable-eprt.d

@@ -7,6 +7,7 @@ Category: ftp
 Example: --disable-eprt ftp://example.com/
 Added: 7.10.5
 See-also: disable-epsv ftp-port
+Multi: boolean
 ---
 Tell curl to disable the use of the EPRT and LPRT commands when doing active
 FTP transfers. Curl will normally always first attempt to use EPRT, then LPRT

docs/cmdline-opts/disable-epsv.d

@@ -7,6 +7,7 @@ Category: ftp
 Example: --disable-epsv ftp://example.com/
 Added: 7.9.2
 See-also: disable-eprt ftp-port
+Multi: boolean
 ---
 Tell curl to disable the use of the EPSV command when doing passive FTP
 transfers. Curl will normally always first attempt to use EPSV before

docs/cmdline-opts/disable.d

@@ -7,6 +7,7 @@ Category: curl
 Example: -q $URL
 Added: 5.0
 See-also: config
+Multi: boolean
 ---
 If used as the first parameter on the command line, the *curlrc* config
 file will not be read and used. See the --config for details on the default

docs/cmdline-opts/disallow-username-in-url.d

@@ -7,6 +7,7 @@ Added: 7.61.0
 See-also: proto
 Category: curl http
 Example: --disallow-username-in-url $URL
+Multi: boolean
 ---
 This tells curl to exit if passed a URL containing a username. This is probably
 most useful when the URL is being provided at runtime or similar.

docs/cmdline-opts/dns-interface.d

@@ -9,6 +9,7 @@ Added: 7.33.0
 Requires: c-ares
 Category: dns
 Example: --dns-interface eth0 $URL
+Multi: single
 ---
 Tell curl to send outgoing DNS requests through <interface>. This option is a
 counterpart to --interface (which does not affect DNS). The supplied string

docs/cmdline-opts/dns-ipv4-addr.d

@@ -9,9 +9,8 @@ Added: 7.33.0
 Requires: c-ares
 Category: dns
 Example: --dns-ipv4-addr 10.1.2.3 $URL
+Multi: single
 ---
 Tell curl to bind to <ip-address> when making IPv4 DNS requests, so that
 the DNS requests originate from this address. The argument should be a
 single IPv4 address.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/dns-ipv6-addr.d

@@ -9,9 +9,8 @@ Added: 7.33.0
 Requires: c-ares
 Category: dns
 Example: --dns-ipv6-addr 2a04:4e42::561 $URL
+Multi: single
 ---
 Tell curl to bind to <ip-address> when making IPv6 DNS requests, so that
 the DNS requests originate from this address. The argument should be a
 single IPv6 address.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/dns-servers.d

@@ -8,10 +8,9 @@ Added: 7.33.0
 Category: dns
 Example: --dns-servers 192.168.0.1,192.168.0.2 $URL
 See-also: dns-interface dns-ipv4-addr
+Multi: single
 ---
 Set the list of DNS servers to be used instead of the system default.
 The list of IP addresses should be separated with commas. Port numbers
 may also optionally be given as *:<port-number>* after each IP
 address.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/doh-cert-status.d

@@ -6,5 +6,6 @@ Added: 7.76.0
 Category: dns tls
 Example: --doh-cert-status --doh-url https://doh.example $URL
 See-also: doh-insecure
+Multi: boolean
 ---
 Same as --cert-status but used for DoH (DNS-over-HTTPS).

docs/cmdline-opts/doh-insecure.d

@@ -6,5 +6,6 @@ Added: 7.76.0
 Category: dns tls
 Example: --doh-insecure --doh-url https://doh.example $URL
 See-also: doh-url
+Multi: boolean
 ---
 Same as --insecure but used for DoH (DNS-over-HTTPS).

docs/cmdline-opts/doh-url.d

@@ -7,6 +7,7 @@ Added: 7.62.0
 Category: dns
 Example: --doh-url https://doh.example $URL
 See-also: doh-insecure
+Multi: single
 ---
 Specifies which DNS-over-HTTPS (DoH) server to use to resolve hostnames,
 instead of using the default name resolver mechanism. The URL must be HTTPS.
@@ -18,5 +19,3 @@ settings are not inherited and can be controlled separately via
 
 This option is unset if an empty string "" is used as the URL. (Added in
 7.85.0)
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/dump-header.d

@@ -9,11 +9,10 @@ See-also: output
 Category: http ftp
 Example: --dump-header store.txt $URL
 Added: 5.7
+Multi: single
 ---
 Write the received protocol headers to the specified file. If no headers are
 received, the use of this option will create an empty file.
 
 When used in FTP, the FTP server response lines are considered being "headers"
 and thus are saved there.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/egd-file.d

@@ -8,6 +8,7 @@ See-also: random-file
 Category: tls
 Example: --egd-file /random/here $URL
 Added: 7.7
+Multi: single
 ---
 Deprecated option. This option is ignored by curl since 7.84.0. Prior to that
 it only had an effect on curl if built to use old versions of OpenSSL.

docs/cmdline-opts/engine.d

@@ -8,6 +8,7 @@ Category: tls
 Example: --engine flavor $URL
 Added: 7.9.3
 See-also: ciphers curves
+Multi: single
 ---
 Select the OpenSSL crypto engine to use for cipher operations. Use --engine
 list to print a list of build-time supported engines. Note that not all (and

docs/cmdline-opts/etag-compare.d

@@ -8,6 +8,7 @@ Added: 7.68.0
 Category: http
 Example: --etag-compare etag.txt $URL
 See-also: etag-save time-cond
+Multi: single
 ---
 This option makes a conditional HTTP request for the specific ETag read
 from the given file by sending a custom If-None-Match header using the

docs/cmdline-opts/etag-save.d

@@ -8,6 +8,7 @@ Added: 7.68.0
 Category: http
 Example: --etag-save storetag.txt $URL
 See-also: etag-compare
+Multi: single
 ---
 This option saves an HTTP ETag to the specified file. An ETag is a
 caching related header, usually returned in a response.

docs/cmdline-opts/expect100-timeout.d

@@ -8,6 +8,7 @@ Added: 7.47.0
 See-also: connect-timeout
 Category: http
 Example: --expect100-timeout 2.5 -T file $URL
+Multi: single
 ---
 Maximum time in seconds that you allow curl to wait for a 100-continue
 response when curl emits an Expects: 100-continue header in its request. By

docs/cmdline-opts/fail-early.d

@@ -6,6 +6,7 @@ Added: 7.52.0
 Category: curl
 Example: --fail-early $URL https://two.example
 See-also: fail fail-with-body
+Multi: boolean
 ---
 Fail and exit on the first detected transfer error.
 

docs/cmdline-opts/fail-with-body.d

@@ -8,6 +8,7 @@ Added: 7.76.0
 See-also: fail
 Mutexed: fail
 Example: --fail-with-body $URL
+Multi: boolean
 ---
 Return an error on server errors where the HTTP response code is 400 or
 greater). In normal cases when an HTTP server fails to deliver a document, it

docs/cmdline-opts/fail.d

@@ -9,6 +9,7 @@ Category: important http
 Example: --fail $URL
 Mutexed: fail-with-body
 Added: 4.0
+Multi: boolean
 ---
 Fail fast with no output at all on server errors. This is useful to enable
 scripts and users to better deal with failed attempts. In normal cases when an

docs/cmdline-opts/false-start.d

@@ -7,6 +7,7 @@ Added: 7.42.0
 Category: tls
 Example: --false-start $URL
 See-also: tcp-fastopen
+Multi: boolean
 ---
 Tells curl to use false start during the TLS handshake. False start is a mode
 where a TLS client will start sending application data before verifying the

docs/cmdline-opts/form-escape.d

@@ -7,6 +7,7 @@ See-also: form
 Added: 7.81.0
 Category: http upload
 Example: --form-escape -F 'field\\name=curl' -F 'file=@load"this' $URL
+Multi: single
 ---
 Tells curl to pass on names of multipart form fields and files using
 backslash-escaping instead of percent-encoding.

docs/cmdline-opts/form-string.d

@@ -8,6 +8,7 @@ See-also: form
 Category: http upload
 Example: --form-string "data" $URL
 Added: 7.13.2
+Multi: append
 ---
 Similar to --form except that the value string for the named parameter is used
 literally. Leading '@' and '<' characters, and the ';type=' string in

docs/cmdline-opts/form.d

@@ -10,6 +10,7 @@ Category: http upload
 Example: --form "name=curl" --form "file=@loadthis" $URL
 Added: 5.0
 See-also: data form-string form-escape
+Multi: append
 ---
 For HTTP protocol family, this lets curl emulate a filled-in form in which a
 user has pressed the submit button. This causes curl to POST data using the
@@ -132,5 +133,3 @@ base64 attached file:
       -F '=@localfile;encoder=base64' ... smtp://example.com
 
 See further examples and details in the MANUAL.
-
-This option can be used multiple times.

docs/cmdline-opts/ftp-account.d

@@ -8,8 +8,7 @@ Added: 7.13.0
 Category: ftp auth
 Example: --ftp-account "mr.robot" ftp://example.com/
 See-also: user
+Multi: single
 ---
 When an FTP server asks for "account data" after user name and password has
 been provided, this data is sent off using the ACCT command.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/ftp-alternative-to-user.d

@@ -8,6 +8,7 @@ Added: 7.15.5
 Category: ftp
 Example: --ftp-alternative-to-user "U53r" ftp://example.com
 See-also: ftp-account user
+Multi: single
 ---
 If authenticating with the USER and PASS commands fails, send this command.
 When connecting to Tumbleweed's Secure Transport server over FTPS using a

docs/cmdline-opts/ftp-create-dirs.d

@@ -7,6 +7,7 @@ See-also: create-dirs
 Category: ftp sftp curl
 Example: --ftp-create-dirs -T file ftp://example.com/remote/path/file
 Added: 7.10.7
+Multi: boolean
 ---
 When an FTP or SFTP URL/operation uses a path that does not currently exist on
 the server, the standard behavior of curl is to fail. Using this option, curl

docs/cmdline-opts/ftp-method.d

@@ -10,6 +10,7 @@ Example: --ftp-method multicwd ftp://example.com/dir1/dir2/file
 Example: --ftp-method nocwd ftp://example.com/dir1/dir2/file
 Example: --ftp-method singlecwd ftp://example.com/dir1/dir2/file
 See-also: list-only
+Multi: single
 ---
 Control what method curl should use to reach a file on an FTP(S)
 server. The method argument should be one of the following alternatives:

docs/cmdline-opts/ftp-pasv.d

@@ -7,14 +7,14 @@ Added: 7.11.0
 See-also: disable-epsv
 Category: ftp
 Example: --ftp-pasv ftp://example.com/
+Multi: boolean
 ---
 Use passive mode for the data connection. Passive is the internal default
 behavior, but using this option can be used to override a previous --ftp-port
 option.
 
-If this option is used several times, only the first one is used. Undoing an
-enforced passive really is not doable but you must then instead enforce the
-correct --ftp-port again.
+Reversing an enforced passive really is not doable but you must then instead
+enforce the correct --ftp-port again.
 
 Passive mode means that curl will try the EPSV command first and then PASV,
 unless --disable-epsv is used.

docs/cmdline-opts/ftp-port.d

@@ -11,6 +11,7 @@ Example: -P - ftp:/example.com
 Example: -P eth0 ftp:/example.com
 Example: -P 192.168.0.2 ftp:/example.com
 Added: 4.0
+Multi: single
 ---
 Reverses the default initiator/listener roles when connecting with FTP. This
 option makes curl use active mode. curl then tells the server to connect back
@@ -29,9 +30,8 @@ make curl pick the same IP address that is already used for the control
 connection
 .RE
 
-If this option is used several times, the last one will be used. Disable the
-use of PORT with --ftp-pasv. Disable the attempt to use the EPRT command
-instead of PORT by using --disable-eprt. EPRT is really PORT++.
+Disable the use of PORT with --ftp-pasv. Disable the attempt to use the EPRT
+command instead of PORT by using --disable-eprt. EPRT is really PORT++.
 
 You can also append ":[start]-[end]\&" to the right of the address, to tell
 curl what TCP port range to use. That means you specify a port range, from a

docs/cmdline-opts/ftp-pret.d

@@ -7,6 +7,7 @@ Added: 7.20.0
 Category: ftp
 Example: --ftp-pret ftp://example.com/
 See-also: ftp-port ftp-pasv
+Multi: boolean
 ---
 Tell curl to send a PRET command before PASV (and EPSV). Certain FTP servers,
 mainly drftpd, require this non-standard command for directory listings as

docs/cmdline-opts/ftp-skip-pasv-ip.d

@@ -7,6 +7,7 @@ Added: 7.14.2
 See-also: ftp-pasv
 Category: ftp
 Example: --ftp-skip-pasv-ip ftp://example.com/
+Multi: boolean
 ---
 Tell curl to not use the IP address the server suggests in its response
 to curl's PASV command when curl connects the data connection. Instead curl

docs/cmdline-opts/ftp-ssl-ccc-mode.d

@@ -8,6 +8,7 @@ Added: 7.16.2
 See-also: ftp-ssl-ccc
 Category: ftp tls
 Example: --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
+Multi: boolean
 ---
 Sets the CCC mode. The passive mode will not initiate the shutdown, but
 instead wait for the server to do it, and will not reply to the shutdown from

docs/cmdline-opts/ftp-ssl-ccc.d

@@ -7,6 +7,7 @@ See-also: ssl ftp-ssl-ccc-mode
 Added: 7.16.1
 Category: ftp tls
 Example: --ftp-ssl-ccc ftps://example.com/
+Multi: boolean
 ---
 Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after
 authenticating. The rest of the control channel communication will be

docs/cmdline-opts/ftp-ssl-control.d

@@ -7,6 +7,7 @@ Added: 7.16.0
 Category: ftp tls
 Example: --ftp-ssl-control ftp://example.com
 See-also: ssl
+Multi: boolean
 ---
 Require SSL/TLS for the FTP login, clear for transfer.  Allows secure
 authentication, but non-encrypted data transfers for efficiency.  Fails the

docs/cmdline-opts/gen.pl

@@ -204,6 +204,8 @@ sub single {
     my @examples; # there can be more than one
     my $magic; # cmdline special option
     my $line;
+    my $multi;
+    my $experimental;
     while(<F>) {
         $line++;
         if(/^Short: *(.)/i) {
@@ -242,6 +244,12 @@ sub single {
         elsif(/^Example: *(.*)/i) {
             push @examples, $1;
         }
+        elsif(/^Multi: *(.*)/i) {
+            $multi=$1;
+        }
+        elsif(/^Experimental: yes/i) {
+            $experimental=1;
+        }
         elsif(/^C: (.*)/i) {
             $copyright=$1;
         }
@@ -256,6 +264,10 @@ sub single {
                 print STDERR "ERROR: no 'Long:' in $f\n";
                 return 1;
             }
+            if($multi !~ /(single|append|boolean|mutex)/) {
+                print STDERR "ERROR: bad 'Multi:' in $f\n";
+                return 1;
+            }
             if(!$category) {
                 print STDERR "ERROR: no 'Category:' in $f\n";
                 return 2;
@@ -326,9 +338,35 @@ sub single {
         print ".SH DESCRIPTION\n";
     }
 
+    if($experimental) {
+        print "**WARNING**: this option is experimental. Do not use in production.\n\n";
+    }
+
     printdesc(@desc);
     undef @desc;
 
+    if($multi eq "single") {
+        print "\nIf --$long is provided several times, the last set ".
+            "value will be used.\n";
+    }
+    elsif($multi eq "append") {
+        print "\n--$long can be used several times in a command line\n";
+    }
+    elsif($multi eq "boolean") {
+        my $rev = "no-$long";
+        # for options that start with "no-" the reverse is then without
+        # the no- prefix
+        if($long =~ /^no-/) {
+            $rev = $long;
+            $rev =~ s/^no-//;
+        }
+        print "\nProviding --$long multiple times has no extra effect.\n".
+            "Disable it again with --$rev.\n";
+    }
+    elsif($multi eq "mutex") {
+        print "\nProviding --$long multiple times has no extra effect.\n";
+    }
+
     my @foot;
     if($seealso) {
         my @m=split(/ /, $seealso);

docs/cmdline-opts/get.d

@@ -9,6 +9,7 @@ Example: --get -d "tool=curl" -d "age=old" $URL
 Example: --get -I -d "tool=curl" $URL
 Added: 7.8.1
 See-also: data request
+Multi: boolean
 ---
 When used, this option will make all data specified with --data, --data-binary
 or --data-urlencode to be used in an HTTP GET request instead of the POST
@@ -17,7 +18,3 @@ with a '?' separator.
 
 If used in combination with --head, the POST data will instead be appended to
 the URL with a HEAD request.
-
-If this option is used several times, only the first one is used. This is
-because undoing a GET does not make sense, but you should then instead enforce
-the alternative method you prefer.

docs/cmdline-opts/globoff.d

@@ -7,6 +7,7 @@ Category: curl
 Example: -g "https://example.com/{[]}}}}"
 Added: 7.6
 See-also: config disable
+Multi: boolean
 ---
 This option switches off the "URL globbing parser". When you set this option,
 you can specify URLs that contain the letters {}[] without having curl itself

docs/cmdline-opts/happy-eyeballs-timeout-ms.d

@@ -7,6 +7,7 @@ Added: 7.59.0
 Category: connection
 Example: --happy-eyeballs-timeout-ms 500 $URL
 See-also: max-time connect-timeout
+Multi: single
 ---
 Happy Eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6
 addresses for dual-stack hosts, giving IPv6 a head-start of the specified
@@ -18,5 +19,3 @@ The range of suggested useful values is limited. Happy Eyeballs RFC 6555 says
 "It is RECOMMENDED that connection attempts be paced 150-250 ms apart to
 balance human factors against network load." libcurl currently defaults to
 200 ms. Firefox and Chrome currently default to 300 ms.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/haproxy-protocol.d

@@ -7,6 +7,7 @@ Added: 7.60.0
 Category: http proxy
 Example: --haproxy-protocol $URL
 See-also: proxy
+Multi: boolean
 ---
 Send a HAProxy PROXY protocol v1 header at the beginning of the
 connection. This is used by some load balancers and reverse proxies to

docs/cmdline-opts/head.d

@@ -8,6 +8,7 @@ Category: http ftp file
 Example: -I $URL
 Added: 4.0
 See-also: get verbose trace-ascii
+Multi: boolean
 ---
 Fetch the headers only! HTTP-servers feature the command HEAD which this uses
 to get nothing but the header of a document. When used on an FTP or FILE file,

docs/cmdline-opts/header.d

@@ -11,6 +11,7 @@ Example: -H "X-First-Name: Joe" $URL
 Example: -H "User-Agent: yes-please/2000" $URL
 Example: -H "Host:" $URL
 Added: 5.0
+Multi: append
 ---
 Extra header to include in information sent. When used within an HTTP request,
 it is added to the regular request headers.
@@ -53,5 +54,3 @@ with a request body, will make curl send the data using chunked encoding.
 lead to the header being sent to other hosts than the original host, so
 sensitive headers should be used with caution combined with following
 redirects.
-
-This option can be used multiple times to add/replace/remove multiple headers.

docs/cmdline-opts/help.d

@@ -8,6 +8,7 @@ Category: important curl
 Example: --help all
 Added: 4.0
 See-also: verbose
+Multi: boolean
 ---
 Usage help. This lists all commands of the <category>.
 If no arg was provided, curl will display the most important

docs/cmdline-opts/hostpubmd5.d

@@ -8,6 +8,7 @@ Added: 7.17.1
 Category: sftp scp
 Example: --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/
 See-also: hostpubsha256
+Multi: single
 ---
 Pass a string containing 32 hexadecimal digits. The string should
 be the 128 bit MD5 checksum of the remote host's public key, curl will refuse

docs/cmdline-opts/hostpubsha256.d

@@ -8,6 +8,7 @@ Added: 7.80.0
 Category: sftp scp
 Example: --hostpubsha256 NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ= sftp://example.com/
 See-also: hostpubmd5
+Multi: single
 ---
 Pass a string containing a Base64-encoded SHA256 hash of the remote
 host's public key. Curl will refuse the connection with the host

docs/cmdline-opts/hsts.d

@@ -8,6 +8,7 @@ Added: 7.74.0
 Category: http
 Example: --hsts cache.txt $URL
 See-also: proto
+Multi: append
 ---
 This option enables HSTS for the transfer. If the file name points to an
 existing HSTS cache file, that will be used. After a completed transfer, the

docs/cmdline-opts/http0.9.d

@@ -8,6 +8,7 @@ Category: http
 Example: --http0.9 $URL
 Added: 7.64.0
 See-also: http1.1 http2 http3
+Multi: boolean
 ---
 Tells curl to be fine with HTTP version 0.9 response.
 

docs/cmdline-opts/http1.0.d

@@ -10,6 +10,7 @@ Help: Use HTTP 1.0
 Category: http
 Example: --http1.0 $URL
 See-also: http0.9 http1.1
+Multi: mutex
 ---
 Tells curl to use HTTP version 1.0 instead of using its internally preferred
 HTTP version.

docs/cmdline-opts/http1.1.d

@@ -9,5 +9,6 @@ Help: Use HTTP 1.1
 Category: http
 Example: --http1.1 $URL
 See-also: http1.0 http0.9
+Multi: mutex
 ---
 Tells curl to use HTTP version 1.1.

docs/cmdline-opts/http2-prior-knowledge.d

@@ -10,6 +10,7 @@ Help: Use HTTP 2 without HTTP/1.1 Upgrade
 Category: http
 Example: --http2-prior-knowledge $URL
 See-also: http2 http3
+Multi: boolean
 ---
 Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1
 Upgrade. It requires prior knowledge that the server supports HTTP/2 straight

docs/cmdline-opts/http2.d

@@ -11,6 +11,7 @@ Help: Use HTTP 2
 See-also: http1.1 http3
 Category: http
 Example: --http2 $URL
+Multi: mutex
 ---
 Tells curl to use HTTP version 2.
 

docs/cmdline-opts/http3.d

@@ -10,9 +10,9 @@ Help: Use HTTP v3
 See-also: http1.1 http2
 Category: http
 Example: --http3 $URL
+Multi: mutex
+Experimental: yes
 ---
-**WARNING**: this option is experimental. Do not use in production.
-
 Tells curl to use HTTP version 3 directly to the host and port number used in
 the URL. A normal HTTP/3 transaction will be done to a host and then get
 redirected via Alt-Svc, but this option allows a user to circumvent that when

docs/cmdline-opts/ignore-content-length.d

@@ -7,6 +7,7 @@ Category: http ftp
 Example: --ignore-content-length $URL
 Added: 7.14.1
 See-also: ftp-skip-pasv-ip
+Multi: boolean
 ---
 For HTTP, Ignore the Content-Length header. This is particularly useful for
 servers running Apache 1.x, which will report incorrect Content-Length for

docs/cmdline-opts/include.d

@@ -7,6 +7,7 @@ See-also: verbose
 Category: important verbose
 Example: -i $URL
 Added: 4.8
+Multi: boolean
 ---
 Include the HTTP response headers in the output. The HTTP response headers can
 include things like server name, cookies, date of the document, HTTP version

docs/cmdline-opts/insecure.d

@@ -8,6 +8,7 @@ See-also: proxy-insecure cacert capath
 Category: tls sftp scp
 Example: --insecure $URL
 Added: 7.10
+Multi: boolean
 ---
 By default, every secure connection curl makes is verified to be secure before
 the transfer takes place. This option makes curl skip the verification step

docs/cmdline-opts/interface.d

@@ -7,14 +7,13 @@ See-also: dns-interface
 Category: connection
 Example: --interface eth0 $URL
 Added: 7.3
+Multi: single
 ---
 Perform an operation using a specified interface. You can enter interface
 name, IP address or host name. An example could look like:
 
  curl --interface eth0:1 https://www.example.com/
 
-If this option is used several times, the last one will be used.
-
 On Linux it can be used to specify a VRF, but the binary needs to either
 have CAP_NET_RAW or to be run as root. More information about Linux VRF:
 https://www.kernel.org/doc/Documentation/networking/vrf.txt

docs/cmdline-opts/ipv4.d

@@ -11,6 +11,7 @@ See-also: http1.1 http2
 Help: Resolve names to IPv4 addresses
 Category: connection dns
 Example: --ipv4 $URL
+Multi: boolean
 ---
 This option tells curl to use IPv4 addresses only, and not for example try
 IPv6.

docs/cmdline-opts/ipv6.d

@@ -11,6 +11,7 @@ See-also: http1.1 http2
 Help: Resolve names to IPv6 addresses
 Category: connection dns
 Example: --ipv6 $URL
+Multi: boolean
 ---
 This option tells curl to use IPv6 addresses only, and not for example try
 IPv4.

docs/cmdline-opts/json.d

@@ -12,6 +12,7 @@ Example: --json '{ "drink":' --json ' "coffe" }' $URL
 Example: --json @prepared $URL
 Example: --json @- $URL < json.txt
 Added: 7.82.0
+Multi: append
 ---
 Sends the specified JSON data in a POST request to the HTTP server. --json
 works as a shortcut for passing on these three options:

docs/cmdline-opts/junk-session-cookies.d

@@ -8,6 +8,7 @@ See-also: cookie cookie-jar
 Category: http
 Example: --junk-session-cookies -b cookies.txt $URL
 Added: 7.9.7
+Multi: boolean
 ---
 When curl is told to read cookies from a given file, this option will make it
 discard all "session cookies". This will basically have the same effect as if

docs/cmdline-opts/keepalive-time.d

@@ -7,6 +7,7 @@ Added: 7.18.0
 Category: connection
 Example: --keepalive-time 20 $URL
 See-also: no-keepalive max-time
+Multi: single
 ---
 This option sets the time a connection needs to remain idle before sending
 keepalive probes and the time between individual keepalive probes. It is
@@ -17,5 +18,4 @@ connections. The number of missed keepalive probes before declaring the
 connection down is OS dependent and is commonly 9 or 10. This option has no
 effect if --no-keepalive is used.
 
-If this option is used several times, the last one will be used. If
-unspecified, the option defaults to 60 seconds.
+If unspecified, the option defaults to 60 seconds.

docs/cmdline-opts/key-type.d

@@ -8,8 +8,7 @@ Category: tls
 Example: --key-type DER --key here $URL
 Added: 7.9.3
 See-also: key
+Multi: single
 ---
 Private key file type. Specify which type your --key provided private key
 is. DER, PEM, and ENG are supported. If not specified, PEM is assumed.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/key.d

@@ -8,6 +8,7 @@ Category: tls ssh
 Example: --cert certificate --key here $URL
 Added: 7.9.3
 See-also: key-type cert
+Multi: single
 ---
 Private key file name. Allows you to provide your private key in this separate
 file. For SSH, if not specified, curl tries the following candidates in order:
@@ -24,5 +25,3 @@ If curl is built against Secure Transport or Schannel then this option is
 ignored for TLS protocols (HTTPS, etc). Those backends expect the private key
 to be already present in the keychain or PKCS#12 file containing the
 certificate.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/krb.d

@@ -9,9 +9,8 @@ Category: ftp
 Example: --krb clear ftp://example.com/
 Added: 7.3
 See-also: delegation ssl
+Multi: single
 ---
 Enable Kerberos authentication and use. The level must be entered and should
 be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a
 level that is not one of these, 'private' will instead be used.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/libcurl.d

@@ -7,6 +7,7 @@ Added: 7.16.1
 Category: curl
 Example: --libcurl client.c $URL
 See-also: verbose
+Multi: single
 ---
 Append this option to any ordinary curl command line, and you will get
 libcurl-using C source code written to the file that does the equivalent
@@ -14,6 +15,3 @@ of what your command-line operation does!
 
 This option is global and does not need to be specified for each use of
 --next.
-
-If this option is used several times, the last given file name will be
-used.

docs/cmdline-opts/limit-rate.d

@@ -9,6 +9,7 @@ Example: --limit-rate 1000 $URL
 Example: --limit-rate 10M $URL
 Added: 7.10
 See-also: speed-limit speed-time
+Multi: single
 ---
 Specify the maximum transfer rate you want curl to use - for both downloads
 and uploads. This feature is useful if you have a limited pipe and you would like
@@ -26,5 +27,3 @@ the set threshold over a period of multiple seconds.
 If you also use the --speed-limit option, that option will take precedence and
 might cripple the rate-limiting slightly, to help keeping the speed-limit
 logic working.
-
-If this option is used several times, the last one will be used.

docs/cmdline-opts/list-only.d

@@ -8,6 +8,7 @@ Added: 4.0
 Category: ftp pop3
 Example: --list-only ftp://example.com/dir/
 See-also: quote request
+Multi: boolean
 ---
 (FTP)
 When listing an FTP directory, this switch forces a name-only view. This is