curl.1: provide examples for each option

The file format for each option now features a "Example:" header that
can provide one or more examples that get rendered appropriately in the
output. All options MUST have at least one example or gen.pl complains
at build-time.

This fix also does a few other minor format and consistency cleanups.

Closes #7654

docs/cmdline-opts/MANPAGE.md

@@ -28,6 +28,7 @@ Each file has a set of meta-data and a body of text.
     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`)
     --- (end of meta-data)
 
 ### Body

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

@@ -4,6 +4,7 @@ Help: Connect via abstract Unix domain socket
 Added: 7.53.0
 Protocols: HTTP
 Category: connection
+Example: --abstract-unix-socket socketpath $URL
 ---
 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

@@ -4,9 +4,8 @@ Protocols: HTTPS
 Help: Enable alt-svc with this cache file
 Added: 7.64.1
 Category: http
+Example: --alt-svc svc.txt $URL
 ---
-WARNING: this option is experimental. Do not use in production.
-
 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,
 the cache will be saved to the file name again if it has been modified.

docs/cmdline-opts/anyauth.d

@@ -3,6 +3,7 @@ Help: Pick any authentication method
 Protocols: HTTP
 See-also: proxy-anyauth basic digest
 Category: http proxy auth
+Example: --anyauth --user me:pwd $URL
 ---
 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

@@ -3,6 +3,7 @@ Long: append
 Help: Append to target file when uploading
 Protocols: FTP SFTP
 Category: ftp sftp
+Example: --upload-file local --append ftp://example.com/
 ---
 When used in an upload, this makes curl append to the target file instead of
 overwriting it. If the remote file doesn't exist, it will be created.  Note

docs/cmdline-opts/aws-sigv4.d

@@ -3,6 +3,7 @@ Arg: <provider1[:provider2[:region[:service]]]>
 Help: Use AWS V4 signature authentication
 Category: auth http
 Added: 7.75.0
+Example: --aws-sigv4 "aws:amz:east-2:es" --user "key:secret" $URL
 ---
 Use AWS V4 signature authentication in the transfer.
 

docs/cmdline-opts/basic.d

@@ -3,6 +3,7 @@ Help: Use HTTP Basic Authentication
 See-also: proxy-basic
 Protocols: HTTP
 Category: auth
+Example: -u name:password --basic $URL
 ---
 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

@@ -3,6 +3,7 @@ Arg: <file>
 Help: CA certificate to verify peer against
 Protocols: TLS
 Category: tls
+Example: --cacert CA-file.txt $URL
 ---
 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
@@ -26,9 +27,9 @@ should not be set. If the option is not set, then curl will use the
 certificates in the system and user Keychain to verify the peer, which is the
 preferred method of verifying the peer's certificate chain.
 
-(Schannel only) This option is supported for Schannel in Windows 7 or later 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).
+(Schannel only) This option is supported for Schannel in Windows 7 or later
+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

@@ -3,6 +3,7 @@ Arg: <dir>
 Help: CA directory to verify peer against
 Protocols: TLS
 Category: tls
+Example: --capath /local/directory $URL
 ---
 Tells curl to use the specified certificate directory to verify the
 peer. Multiple paths can be provided by separating them with ":" (e.g.

docs/cmdline-opts/cert-status.d

@@ -3,6 +3,7 @@ Protocols: TLS
 Added: 7.41.0
 Help: Verify the status of the server cert via OCSP-staple
 Category: tls
+Example: --cert-status $URL
 ---
 Tells curl to verify the status of the server certificate by using the
 Certificate Status Request (aka. OCSP stapling) TLS extension.

docs/cmdline-opts/cert-type.d

@@ -4,6 +4,7 @@ Arg: <type>
 Help: Certificate type (DER/PEM/ENG)
 See-also: cert key key-type
 Category: tls
+Example: --cert-type PEM --cert file $URL
 ---
 Tells curl what type the provided client certificate is using. PEM, DER, ENG
 and P12 are recognized types.  If not specified, PEM is assumed.

docs/cmdline-opts/cert.d

@@ -5,6 +5,7 @@ Help: Client certificate file and password
 Protocols: TLS
 See-also: cert-type key key-type
 Category: tls
+Example: --cert certfile --key keyfile $URL
 ---
 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

docs/cmdline-opts/ciphers.d

@@ -3,6 +3,7 @@ Arg: <list of ciphers>
 Help: SSL ciphers to use
 Protocols: TLS
 Category: tls
+Example: --ciphers ECDHE-ECDSA-AES256-CCM8 $URL
 ---
 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:

docs/cmdline-opts/compressed-ssh.d

@@ -3,6 +3,7 @@ Help: Enable SSH compression
 Protocols: SCP SFTP
 Added: 7.56.0
 Category: scp ssh
+Example: --compressed-ssh sftp://example.com/
 ---
 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

@@ -2,6 +2,7 @@ Long: compressed
 Help: Request compressed response
 Protocols: HTTP
 Category: http
+Example: --compressed $URL
 ---
 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

@@ -3,6 +3,7 @@ Arg: <file>
 Help: Read config from a file
 Short: K
 Category: curl
+Example: --config file.txt $URL
 ---
 
 Specify a text file to read curl arguments from. The command line arguments

docs/cmdline-opts/connect-timeout.d

@@ -1,8 +1,10 @@
 Long: connect-timeout
-Arg: <seconds>
+Arg: <fractional seconds>
 Help: Maximum time allowed for connection
 See-also: max-time
 Category: connection
+Example: --connect-timeout 20 $URL
+Example: --connect-timeout 3.14 $URL
 ---
 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

docs/cmdline-opts/connect-to.d

@@ -4,6 +4,7 @@ Help: Connect to host
 Added: 7.49.0
 See-also: resolve header
 Category: connection
+Example: --connect-to example.com:443:example.net:8443 $URL
 ---
 
 For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.

docs/cmdline-opts/continue-at.d

@@ -4,6 +4,8 @@ Arg: <offset>
 Help: Resumed transfer offset
 See-also: range
 Category: connection
+Example: -C - $URL
+Example: -C 400 $URL
 ---
 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

docs/cmdline-opts/cookie-jar.d

@@ -4,6 +4,8 @@ Arg: <filename>
 Protocols: HTTP
 Help: Write cookies to <filename> after operation
 Category: http
+Example: -c store-here.txt $URL
+Example: -c store-here.txt -b read-these $URL
 ---
 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

docs/cmdline-opts/cookie.d

@@ -4,6 +4,8 @@ Arg: <data|filename>
 Protocols: HTTP
 Help: Send cookies from string/file
 Category: http
+Example: -b cookiefile $URL
+Example: -b cookiefile -c cookiefile $URL
 ---
 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

docs/cmdline-opts/create-dirs.d

@@ -1,6 +1,7 @@
 Long: create-dirs
 Help: Create necessary local directory hierarchy
 Category: curl
+Example: --create-dirs --output local/dir/file $URL
 ---
 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

@@ -5,6 +5,7 @@ Protocols: SFTP SCP FILE
 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
 ---
 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

docs/cmdline-opts/crlf.d

@@ -2,6 +2,7 @@ Long: crlf
 Help: Convert LF to CRLF in upload
 Protocols: FTP SMTP
 Category: ftp smtp
+Example: --crlf -T file ftp://example.com/
 ---
 Convert LF to CRLF in upload. Useful for MVS (OS/390).
 

docs/cmdline-opts/crlfile.d

@@ -1,9 +1,10 @@
 Long: crlfile
 Arg: <file>
 Protocols: TLS
-Help: Get a CRL list in PEM format from the given file
+Help: Use this CRL list
 Added: 7.19.7
 Category: tls
+Example: --crlfile rejects.txt $URL
 ---
 Provide a file using PEM format with a Certificate Revocation List that may
 specify peer certificates that are to be considered revoked.

docs/cmdline-opts/curves.d

@@ -4,6 +4,7 @@ Help: (EC) TLS key exchange algorithm(s) to request
 Protocols: TLS
 Added: 7.73.0
 Category: tls
+Example: --curves X25519 $URL
 ---
 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

@@ -3,5 +3,6 @@ Arg: <data>
 Help: HTTP POST ASCII data
 Protocols: HTTP
 Category: http post upload
+Example: --data-ascii @file $URL
 ---
 This is just an alias for --data.

docs/cmdline-opts/data-binary.d

@@ -3,6 +3,7 @@ Arg: <data>
 Help: HTTP POST binary data
 Protocols: HTTP
 Category: http post upload
+Example: --data-binary @filename $URL
 ---
 This posts data exactly as specified with no extra processing whatsoever.
 

docs/cmdline-opts/data-raw.d

@@ -5,6 +5,8 @@ Help: HTTP POST data, '@' allowed
 Added: 7.43.0
 See-also: data
 Category: http post upload
+Example: --data-raw "hello" $URL
+Example: --data-raw "@at@at@" $URL
 ---
 This posts data similarly to --data but without the special
 interpretation of the @ character.

docs/cmdline-opts/data-urlencode.d

@@ -5,6 +5,10 @@ Protocols: HTTP
 See-also: data data-raw
 Added: 7.18.0
 Category: http post upload
+Example: --data-urlencode name=val $URL
+Example: --data-urlencode =encodethis $URL
+Example: --data-urlencode name@file $URL
+Example: --data-urlencode @fileonly $URL
 ---
 This posts data, similar to the other --data options with the exception
 that this performs URL-encoding.

docs/cmdline-opts/data.d

@@ -6,6 +6,9 @@ Protocols: HTTP MQTT
 See-also: data-binary data-urlencode data-raw
 Mutexed: form head upload-file
 Category: important http post upload
+Example: -d "name=curl" $URL
+Example: -d "name=curl" -d "tool=cmdline" $URL
+Example: -d @filename $URL
 ---
 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

@@ -3,6 +3,7 @@ Arg: <LEVEL>
 Help: GSS-API delegation permission
 Protocols: GSS/kerberos
 Category: auth
+Example: --delegation "none" $URL
 ---
 Set LEVEL to tell the server what it is allowed to delegate when it
 comes to user credentials.

docs/cmdline-opts/digest.d

@@ -4,6 +4,7 @@ Protocols: HTTP
 Mutexed: basic ntlm negotiate
 See-also: user proxy-digest anyauth
 Category: proxy auth http
+Example: -u name:password --digest $URL
 ---
 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

docs/cmdline-opts/disable-eprt.d

@@ -2,6 +2,7 @@ Long: disable-eprt
 Help: Inhibit using EPRT or LPRT
 Protocols: FTP
 Category: ftp
+Example: --disable-eprt ftp://example.com/
 ---
 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

@@ -2,6 +2,7 @@ Long: disable-epsv
 Help: Inhibit using EPSV
 Protocols: FTP
 Category: ftp
+Example: --disable-epsv ftp://example.com/
 ---
 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

@@ -2,6 +2,7 @@ Long: disable
 Short: q
 Help: Disable .curlrc
 Category: curl
+Example: -q $URL
 ---
 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

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

docs/cmdline-opts/dns-interface.d

@@ -6,6 +6,7 @@ See-also: dns-ipv4-addr dns-ipv6-addr
 Added: 7.33.0
 Requires: c-ares
 Category: dns
+Example: --dns-interface eth0 $URL
 ---
 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

@@ -6,6 +6,7 @@ See-also: dns-interface dns-ipv6-addr
 Added: 7.33.0
 Requires: c-ares
 Category: dns
+Example: --dns-ipv4-addr 10.1.2.3 $URL
 ---
 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

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

@@ -6,6 +6,7 @@ See-also: dns-interface dns-ipv4-addr
 Added: 7.33.0
 Requires: c-ares
 Category: dns
+Example: --dns-ipv6-addr 2a04:4e42::561 $URL
 ---
 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

docs/cmdline-opts/dns-servers.d

@@ -4,6 +4,7 @@ Help: DNS server addrs to use
 Requires: c-ares
 Added: 7.33.0
 Category: dns
+Example: --dns-servers 192.168.0.1,192.168.0.2 $URL
 ---
 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

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

@@ -3,5 +3,6 @@ Help: Verify the status of the DoH server cert via OCSP-staple
 Protocols: all
 Added: 7.76.0
 Category: dns tls
+Example: --doh-cert-status --doh-url https://doh.example $URL
 ---
 Same as --cert-status but used for DoH (DNS-over-HTTPS).

docs/cmdline-opts/doh-insecure.d

@@ -3,5 +3,6 @@ Help: Allow insecure DoH server connections
 Protocols: all
 Added: 7.76.0
 Category: dns tls
+Example: --doh-insecure --doh-url https://doh.example $URL
 ---
 Same as --insecure but used for DoH (DNS-over-HTTPS).

docs/cmdline-opts/doh-url.d

@@ -4,6 +4,7 @@ Help: Resolve host names over DoH
 Protocols: all
 Added: 7.62.0
 Category: dns
+Example: --doh-url https://doh.example $URL
 ---
 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.

docs/cmdline-opts/dump-header.d

@@ -5,6 +5,7 @@ Help: Write the received headers to <filename>
 Protocols: HTTP FTP
 See-also: output
 Category: http ftp
+Example: --dump-header store.txt $URL
 ---
 Write the received protocol headers to the specified file. If no headers are
 received, the use of this option will create an empty file.

docs/cmdline-opts/egd-file.d

@@ -4,6 +4,7 @@ Help: EGD socket path for random data
 Protocols: TLS
 See-also: random-file
 Category: tls
+Example: --egd-file /random/here $URL
 ---
 Specify the path name to the Entropy Gathering Daemon socket. The socket is
 used to seed the random engine for SSL connections.

docs/cmdline-opts/engine.d

@@ -3,6 +3,7 @@ Arg: <name>
 Help: Crypto engine to use
 Protocols: TLS
 Category: tls
+Example: --engine flavor $URL
 ---
 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

@@ -4,6 +4,7 @@ Help: Pass an ETag from a file as a custom header
 Protocols: HTTP
 Added: 7.68.0
 Category: http
+Example: --etag-compare etag.txt $URL
 ---
 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

@@ -4,6 +4,7 @@ Help: Parse ETag from a request and save it to a file
 Protocols: HTTP
 Added: 7.68.0
 Category: http
+Example: --etag-save storetag.txt $URL
 ---
 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

@@ -5,6 +5,7 @@ Protocols: HTTP
 Added: 7.47.0
 See-also: connect-timeout
 Category: http
+Example: --expect100-timeout 2.5 -T file $URL
 ---
 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

@@ -2,6 +2,7 @@ Long: fail-early
 Help: Fail on first transfer error, do not continue
 Added: 7.52.0
 Category: curl
+Example: --fail-early $URL https://two.example
 ---
 Fail and exit on the first detected transfer error.
 

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

@@ -4,6 +4,7 @@ Help: Fail on HTTP errors but save the body
 Category: http output
 Added: 7.76.0
 See-also: fail
+Example: --fail-with-body $URL
 ---
 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

@@ -4,6 +4,7 @@ Protocols: HTTP
 Help: Fail silently (no output at all) on HTTP errors
 See-also: fail-with-body
 Category: important http
+Example: --fail $URL
 ---
 Fail silently (no output at all) on server errors. This is mostly done to
 enable scripts etc to better deal with failed attempts. In normal cases

docs/cmdline-opts/false-start.d

@@ -3,6 +3,7 @@ Help: Enable TLS False Start
 Protocols: TLS
 Added: 7.42.0
 Category: tls
+Example: --false-start $URL
 ---
 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-string.d

@@ -4,6 +4,7 @@ Protocols: HTTP SMTP IMAP
 Arg: <name=string>
 See-also: form
 Category: http upload
+Example: --form-string "data" $URL
 ---
 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

@@ -5,6 +5,7 @@ Help: Specify multipart MIME data
 Protocols: HTTP SMTP IMAP
 Mutexed: data head upload-file
 Category: http upload
+Example: --form "name=curl" --form "file=@loadthis" $URL
 ---
 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

docs/cmdline-opts/ftp-account.d

@@ -4,6 +4,7 @@ Help: Account data string
 Protocols: FTP
 Added: 7.13.0
 Category: ftp auth
+Example: --ftp-account "mr.robot" ftp://example.com/
 ---
 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.

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

@@ -4,6 +4,7 @@ Help: String to replace USER [name]
 Protocols: FTP
 Added: 7.15.5
 Category: ftp
+Example: --ftp-alternative-to-user "U53r" ftp://example.com
 ---
 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

@@ -3,6 +3,7 @@ Protocols: FTP SFTP
 Help: Create the remote dirs if not present
 See-also: create-dirs
 Category: ftp sftp curl
+Example: --ftp-create-dirs -T file ftp://example.com/remote/path/file
 ---
 When an FTP or SFTP URL/operation uses a path that doesn't currently exist on
 the server, the standard behavior of curl is to fail. Using this option, curl

docs/cmdline-opts/ftp-method.d

@@ -4,6 +4,9 @@ Help: Control CWD usage
 Protocols: FTP
 Added: 7.15.1
 Category: ftp
+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
 ---
 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

@@ -4,6 +4,7 @@ Protocols: FTP
 Added: 7.11.0
 See-also: disable-epsv
 Category: ftp
+Example: --ftp-pasv ftp://example.com/
 ---
 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

docs/cmdline-opts/ftp-port.d

@@ -5,6 +5,9 @@ Short: P
 Protocols: FTP
 See-also: ftp-pasv disable-eprt
 Category: ftp
+Example: -P - ftp:/example.com
+Example: -P eth0 ftp:/example.com
+Example: -P 192.168.0.2 ftp:/example.com
 ---
 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

docs/cmdline-opts/ftp-pret.d

@@ -3,6 +3,7 @@ Help: Send PRET before PASV
 Protocols: FTP
 Added: 7.20.0
 Category: ftp
+Example: --ftp-pret ftp://example.com/
 ---
 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

@@ -4,6 +4,7 @@ Protocols: FTP
 Added: 7.14.2
 See-also: ftp-pasv
 Category: ftp
+Example: --ftp-skip-pasv-ip ftp://example.com/
 ---
 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

@@ -5,6 +5,7 @@ Protocols: FTP
 Added: 7.16.2
 See-also: ftp-ssl-ccc
 Category: ftp tls
+Example: --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
 ---
 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

@@ -4,6 +4,7 @@ Protocols: FTP
 See-also: ssl ftp-ssl-ccc-mode
 Added: 7.16.1
 Category: ftp tls
+Example: --ftp-ssl-ccc ftps://example.com/
 ---
 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

@@ -3,6 +3,7 @@ Help: Require SSL/TLS for FTP login, clear for transfer
 Protocols: FTP
 Added: 7.16.0
 Category: ftp tls
+Example: --ftp-ssl-control ftp://example.com
 ---
 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

@@ -138,8 +138,11 @@ sub single {
     my $requires;
     my $category;
     my $seealso;
+    my @examples; # there can be more than one
     my $magic; # cmdline special option
+    my $line;
     while(<F>) {
+        $line++;
         if(/^Short: *(.)/i) {
             $short=$1;
         }
@@ -173,6 +176,9 @@ sub single {
         elsif(/^Category: *(.*)/i) {
             $category=$1;
         }
+        elsif(/^Example: *(.*)/i) {
+            push @examples, $1;
+        }
         elsif(/^Help: *(.*)/i) {
             ;
         }
@@ -185,6 +191,10 @@ sub single {
                 print STDERR "ERROR: no 'Category:' in $f\n";
                 exit 2;
             }
+            if(!$examples[0]) {
+                print STDERR "$f:$line:1:ERROR: no 'Example:' present\n";
+                exit 2;
+            }
             last;
         }
         else {
@@ -276,6 +286,16 @@ sub single {
         }
         push @foot, overrides($standalone, "This option overrides $mstr. ");
     }
+    if($examples[0]) {
+        my $s ="";
+        $s="s" if($examples[1]);
+        print "\nExample$s:\n.nf\n";
+        foreach my $e (@examples) {
+            $e =~ s!\$URL!https://example.com!g;
+            print " curl $e\n";
+        }
+        print ".fi\n";
+    }
     if($added) {
         push @foot, added($standalone, $added);
     }

docs/cmdline-opts/get.d

@@ -2,6 +2,7 @@ Long: get
 Short: G
 Help: Put the post data in the URL and use GET
 Category: http upload
+Example: --get $URL
 ---
 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

docs/cmdline-opts/globoff.d

@@ -2,6 +2,7 @@ Long: globoff
 Short: g
 Help: Disable URL sequences and ranges using {} and []
 Category: curl
+Example: -g "https://example.com/{[]}}}}"
 ---
 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

@@ -3,6 +3,7 @@ Arg: <milliseconds>
 Help: Time for IPv6 before trying IPv4
 Added: 7.59.0
 Category: connection
+Example: --happy-eyeballs-timeout-ms 500 $URL
 ---
 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

docs/cmdline-opts/haproxy-protocol.d

@@ -3,10 +3,11 @@ Help: Send HAProxy PROXY protocol v1 header
 Protocols: HTTP
 Added: 7.60.0
 Category: http proxy
+Example: --haproxy-protocol $URL
 ---
-Send a HAProxy PROXY protocol v1 header at the beginning of the connection. This
-is used by some load balancers and reverse proxies to indicate the client's
-true IP address and port.
+Send a HAProxy PROXY protocol v1 header at the beginning of the
+connection. This is used by some load balancers and reverse proxies to
+indicate the client's true IP address and port.
 
 This option is primarily useful when sending test requests to a service that
 expects this header.

docs/cmdline-opts/head.d

@@ -3,6 +3,7 @@ Short: I
 Help: Show document info only
 Protocols: HTTP FTP FILE
 Category: http ftp file
+Example: -I $URL
 ---
 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

@@ -5,6 +5,9 @@ Help: Pass custom header(s) to server
 Protocols: HTTP
 Category: http
 See-also: user-agent referer
+Example: -H "X-First-Name: Joe" $URL
+Example: -H "User-Agent: yes-please/2000" $URL
+Example: -H "Host:" $URL
 ---
 Extra header to include in the request when sending HTTP to a server. You may
 specify any number of extra headers. Note that if you should add a custom
@@ -32,10 +35,6 @@ proxy. Added in 7.37.0.
 Passing on a "Transfer-Encoding: chunked" header when doing a HTTP request
 with a request body, will make curl send the data using chunked encoding.
 
-Example:
-
- curl -H "X-First-Name: Joe" http://example.com/
-
 **WARNING**: headers set with this option will be set in all requests - even
 after redirects are followed, like when told with --location. This can lead to
 the header being sent to other hosts than the original host, so sensitive

docs/cmdline-opts/help.d

@@ -3,6 +3,7 @@ Arg: <category>
 Short: h
 Help: Get help for commands
 Category: important curl
+Example: --help all
 ---
 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

@@ -4,6 +4,7 @@ Help: Acceptable MD5 hash of the host public key
 Protocols: SFTP SCP
 Added: 7.17.1
 Category: sftp scp
+Example: --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/
 ---
 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/hsts.d

@@ -4,9 +4,8 @@ Protocols: HTTPS
 Help: Enable HSTS with this cache file
 Added: 7.74.0
 Category: http
+Example: --hsts cache.txt $URL
 ---
-WARNING: this option is experimental. Do not use in production.
-
 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
 cache will be saved to the file name again if it has been modified.

docs/cmdline-opts/http0.9.d

@@ -4,6 +4,7 @@ Protocols: HTTP
 Added:
 Help: Allow HTTP 0.9 responses
 Category: http
+Example: --http0.9 $URL
 ---
 Tells curl to be fine with HTTP version 0.9 response.
 

docs/cmdline-opts/http1.0.d

@@ -6,6 +6,7 @@ Added:
 Mutexed: http1.1 http2
 Help: Use HTTP 1.0
 Category: http
+Example: --http1.0 $URL
 ---
 Tells curl to use HTTP version 1.0 instead of using its internally preferred
 HTTP version.

docs/cmdline-opts/http1.1.d

@@ -5,5 +5,6 @@ Added: 7.33.0
 Mutexed: http1.0 http2
 Help: Use HTTP 1.1
 Category: http
+Example: --http1.1 $URL
 ---
 Tells curl to use HTTP version 1.1.

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

@@ -6,6 +6,7 @@ Mutexed: http1.1 http1.0 http2
 Requires: HTTP/2
 Help: Use HTTP 2 without HTTP/1.1 Upgrade
 Category: http
+Example: --http2-prior-knowledge $URL
 ---
 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

@@ -8,5 +8,12 @@ See-also: no-alpn
 Help: Use HTTP 2
 See-also: http1.1 http3
 Category: http
+Example: --http2 $URL
 ---
 Tells curl to use HTTP version 2.
+
+For HTTPS, this means curl will attempt to negotiate HTTP/2 in the TLS
+handshake. curl does this by default.
+
+For HTTP, this means curl will attempt to upgrade the request to HTTP/2 using
+the Upgrade: request header.

docs/cmdline-opts/http3.d

@@ -7,8 +7,9 @@ Requires: HTTP/3
 Help: Use HTTP v3
 See-also: http1.1 http2
 Category: http
+Example: --http3 $URL
 ---
-WARNING: this option is experimental. Do not use in production.
+**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

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

@@ -2,6 +2,7 @@ Long: ignore-content-length
 Help: Ignore the size of the remote resource
 Protocols: FTP HTTP
 Category: http ftp
+Example: --ignore-content-length $URL
 ---
 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

@@ -3,6 +3,7 @@ Short: i
 Help: Include protocol response headers in the output
 See-also: verbose
 Category: important verbose
+Example: -i $URL
 ---
 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

@@ -4,6 +4,7 @@ Help: Allow insecure server connections when using SSL
 Protocols: TLS
 See-also: proxy-insecure cacert
 Category: tls
+Example: --insecure $URL
 ---
 By default, every SSL connection curl makes is verified to be secure. This
 option allows curl to proceed and operate even for server connections
@@ -14,3 +15,5 @@ contains the right name and verifies successfully using the cert store.
 
 See this online resource for further details:
  https://curl.se/docs/sslcerts.html
+
+**WARNING**: this makes the transfer insecure.

docs/cmdline-opts/interface.d

@@ -3,6 +3,7 @@ Arg: <name>
 Help: Use network INTERFACE (or address)
 See-also: dns-interface
 Category: connection
+Example: --interface eth0 $URL
 ---
 
 Perform an operation using a specified interface. You can enter interface

docs/cmdline-opts/ipv4.d

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

docs/cmdline-opts/ipv6.d

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

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

@@ -4,6 +4,7 @@ Help: Ignore session cookies read from file
 Protocols: HTTP
 See-also: cookie cookie-jar
 Category: http
+Example: --junk-session-cookies -b cookies.txt $URL
 ---
 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

@@ -3,6 +3,7 @@ Arg: <seconds>
 Help: Interval time for keepalive probes
 Added: 7.18.0
 Category: connection
+Example: --keepalive-time 20 $URL
 ---
 This option sets the time a connection needs to remain idle before sending
 keepalive probes and the time between individual keepalive probes. It is

docs/cmdline-opts/key-type.d

@@ -3,6 +3,7 @@ Arg: <type>
 Help: Private key file type (DER/PEM/ENG)
 Protocols: TLS
 Category: tls
+Example: --key-type DER --key here $URL
 ---
 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.

docs/cmdline-opts/key.d

@@ -3,6 +3,7 @@ Arg: <key>
 Protocols: TLS SSH
 Help: Private key file name
 Category: tls ssh
+Example: --cert certificate --key here $URL
 ---
 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:

docs/cmdline-opts/krb.d

@@ -4,6 +4,7 @@ Help: Enable Kerberos with security <level>
 Protocols: FTP
 Requires: Kerberos
 Category: ftp
+Example: --krb clear ftp://example.com/
 ---
 Enable Kerberos authentication and use. The level must be entered and should
 be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a

docs/cmdline-opts/libcurl.d

@@ -3,6 +3,7 @@ Arg: <file>
 Help: Dump libcurl equivalent code of this command line
 Added: 7.16.1
 Category: curl
+Example: --libcurl client.c $URL
 ---
 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

docs/cmdline-opts/limit-rate.d

@@ -2,6 +2,9 @@ Long: limit-rate
 Arg: <speed>
 Help: Limit transfer speed to RATE
 Category: connection
+Example: --limit-rate 100K $URL
+Example: --limit-rate 1000 $URL
+Example: --limit-rate 10M $URL
 ---
 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'd like

docs/cmdline-opts/list-only.d

@@ -4,6 +4,7 @@ Protocols: FTP POP3
 Help: List only mode
 Added: 4.0
 Category: ftp pop3
+Example: --list-only ftp://example.com/dir/
 ---
 (FTP)
 When listing an FTP directory, this switch forces a name-only view. This is

docs/cmdline-opts/local-port.d

@@ -3,6 +3,7 @@ Arg: <num/range>
 Help: Force use of RANGE for local port numbers
 Added: 7.15.2
 Category: connection
+Example: --local-port 1000-3000 $URL
 ---
 Set a preferred single number or range (FROM-TO) of local port numbers to use
 for the connection(s).  Note that port numbers by nature are a scarce resource

docs/cmdline-opts/location-trusted.d

@@ -3,6 +3,7 @@ Help: Like --location, and send auth to other hosts
 Protocols: HTTP
 See-also: user
 Category: http auth
+Example: --location-trusted -u user:password $URL
 ---
 Like --location, but will allow sending the name + password to all hosts that
 the site may redirect to. This may or may not introduce a security breach if

docs/cmdline-opts/location.d

@@ -3,6 +3,7 @@ Short: L
 Help: Follow redirects
 Protocols: HTTP
 Category: http
+Example: -L $URL
 ---
 If the server reports that the requested page has moved to a different
 location (indicated with a Location: header and a 3XX response code), this