cmdline-docs: quote and angle bracket cleanup

- make sure angle brackets are escaped
- remove a lot of superfluous double quotes
- replace several double quotes with backticks

To make nicer-looking markdown.

Closes #12884

docs/cmdline-opts/MANPAGE.md

@@ -83,6 +83,9 @@ explicitly with an empty "header":
 
     ##
 
+Angle brackets (`<>`) need to be escaped when used in text like `\<` and
+`\>`. This, to ensure that the text renders nicely as markdown.
+
 ### Headers
 
 The `#` header can be used by non-option files and it produces produces a

docs/cmdline-opts/_OPTIONS.md

@@ -7,7 +7,7 @@ is presumed to be and treated as a URL.
 
 The short "single-dash" form of the options, -d for example, may be used with
 or without a space between it and its value, although a space is a recommended
-separator. The long "double-dash" form, --data for example, requires a space
+separator. The long double-dash form, --data for example, requires a space
 between it and its value.
 
 Short version options that do not need any additional values can be used
@@ -16,11 +16,11 @@ options *-O*, *-L* and *-v* at once as *-OLv*.
 
 In general, all boolean options are enabled with --**option** and yet again
 disabled with --**no-**option. That is, you use the same option name but
-prefix it with "no-". However, in this list we mostly only list and show the
+prefix it with `no-`. However, in this list we mostly only list and show the
 *--option* version of them.
 
 When --next is used, it resets the parser state and you start again with a
-clean option state, except for the options that are "global". Global options
+clean option state, except for the options that are global. Global options
 retain their values and meaning even after --next.
 
 The following options are global: `%GLOBALS`.

docs/cmdline-opts/_PROGRESS.md

@@ -14,12 +14,12 @@ the progress meter as otherwise it would mess up the output mixing progress
 meter and response data.
 
 If you want a progress meter for HTTP POST or PUT requests, you need to
-redirect the response output to a file, using shell redirect (>), --output or
+redirect the response output to a file, using shell redirect (\>), --output
-similar.
+or similar.
 
 This does not apply to FTP upload as that operation does not spit out any
 response data to the terminal.
 
-If you prefer a progress "bar" instead of the regular meter, --progress-bar is
+If you prefer a progress bar instead of the regular meter, --progress-bar is
 your friend. You can also disable the progress meter completely with the
 --silent option.

docs/cmdline-opts/_PROTOCOLS.md

@@ -19,14 +19,14 @@ curl supports HTTP with numerous options and variations. It can speak HTTP
 version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct
 command line options.
 ## IMAP(S)
-Using the mail reading protocol, curl can "download" emails for you. With or
+Using the mail reading protocol, curl can download emails for you. With or
 without using TLS.
 ## LDAP(S)
 curl can do directory lookups for you, with or without TLS.
 ## MQTT
-curl supports MQTT version 3. Downloading over MQTT equals "subscribe" to a
+curl supports MQTT version 3. Downloading over MQTT equals subscribe to a
-topic while uploading/posting equals "publish" on a topic. MQTT over TLS is
+topic while uploading/posting equals publish on a topic. MQTT over TLS is not
-not supported (yet).
+supported (yet).
 ## POP3(S)
 Downloading from a pop3 server means getting a mail. With or without using
 TLS.

docs/cmdline-opts/_URL.md

@@ -7,7 +7,7 @@ RFC 3986.
 If you provide a URL without a leading **protocol://** scheme, curl guesses
 what protocol you want. It then defaults to HTTP but assumes others based on
 often-used host name prefixes. For example, for host names starting with
-"ftp." curl assumes you want FTP.
+`ftp.` curl assumes you want FTP.
 
 You can specify any amount of URLs on the command line. They are fetched in a
 sequential manner in the specified order unless you use --parallel. You can

docs/cmdline-opts/_VARIABLES.md

@@ -2,14 +2,14 @@
 <!-- SPDX-License-Identifier: curl -->
 # VARIABLES
 curl supports command line variables (added in 8.3.0). Set variables with
---variable name=content or --variable name@file (where "file" can be stdin if
+--variable name=content or --variable name@file (where `file` can be stdin if
 set to a single dash (-)).
 
-Variable contents can be expanded in option parameters using "{{name}}" (without
+Variable contents can be expanded in option parameters using `{{name}}` if the
-the quotes) if the option name is prefixed with "--expand-". This gets the
+option name is prefixed with `--expand-`. This gets the contents of the
-contents of the variable "name" inserted, or a blank if the name does not
+variable `name` inserted, or a blank if the name does not exist as a
-exist as a variable. Insert "{{" verbatim in the string by prefixing it with a
+variable. Insert `{{` verbatim in the string by prefixing it with a backslash,
-backslash, like "\{{".
+like `\{{`.
 
 You an access and expand environment variables by first importing them. You
 can select to either require the environment variable to be set or you can

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

@@ -17,5 +17,5 @@ Example:
 # `--abstract-unix-socket`
 
 Connect through an abstract Unix domain socket, instead of using the network.
-Note: netstat shows the path of an abstract socket prefixed with '@', however
+Note: netstat shows the path of an abstract socket prefixed with `@`, however
-the <path> argument should not have this leading character.
+the \<path\> argument should not have this leading character.

docs/cmdline-opts/cert.md

@@ -27,28 +27,28 @@ the terminal. Note that this option assumes a certificate file that is the
 private key and the client certificate concatenated. See --cert and --key to
 specify them independently.
 
-In the <certificate> portion of the argument, you must escape the character
+In the \<certificate\> portion of the argument, you must escape the character
-":" as "\:" so that it is not recognized as the password delimiter. Similarly,
+`:` as `\:` so that it is not recognized as the password delimiter. Similarly,
 you must escape the double quote character as \" so that it is not recognized
 as an escape character.
 
 If curl is built against OpenSSL library, and the engine pkcs11 is available,
 then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in
-a PKCS#11 device. A string beginning with "pkcs11:" is interpreted as a
+a PKCS#11 device. A string beginning with `pkcs11:` is interpreted as a
 PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as
-"pkcs11" if none was provided and the --cert-type option is set as "ENG" if
+`pkcs11` if none was provided and the --cert-type option is set as `ENG` if
 none was provided.
 
 (iOS and macOS only) If curl is built against Secure Transport, then the
 certificate string can either be the name of a certificate/private key in the
 system or user keychain, or the path to a PKCS#12-encoded certificate and
 private key. If you want to use a file from the current directory, please
-precede it with "./" prefix, in order to avoid confusion with a nickname.
+precede it with `./` prefix, in order to avoid confusion with a nickname.
 
 (Schannel only) Client certificates must be specified by a path expression to
 a certificate store. (Loading *PFX* is not supported; you can import it to a
-store first). You can use "<store location>\<store name>\<thumbprint>" to
+store first). You can use "\<store location\>\\<store name\>\\<thumbprint\>"
-refer to a certificate in the system certificates store, for example,
+to refer to a certificate in the system certificates store, for example,
 *"CurrentUser\MY\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a"*. Thumbprint is
 usually a SHA-1 hex string which you can see in certificate details. Following
 store locations are supported: *CurrentUser*, *LocalMachine*,

docs/cmdline-opts/data-urlencode.md

@@ -23,8 +23,8 @@ Example:
 This posts data, similar to the other --data options with the exception
 that this performs URL-encoding.
 
-To be CGI-compliant, the <data> part should begin with a *name* followed
+To be CGI-compliant, the \<data\> part should begin with a *name* followed by
-by a separator and a content specification. The <data> part can be passed to
+a separator and a content specification. The \<data\> part can be passed to
 curl using one of the following syntaxes:
 
 ## content

docs/cmdline-opts/dns-interface.md

@@ -18,6 +18,6 @@ Example:
 
 # `--dns-interface`
 
-Tell curl to send outgoing DNS requests through <interface>. This option is a
+Tell curl to send outgoing DNS requests through the given interface. This
-counterpart to --interface (which does not affect DNS). The supplied string
+option is a counterpart to --interface (which does not affect DNS). The
-must be an interface name (not an address).
+supplied string must be an interface name (not an address).

docs/cmdline-opts/dns-servers.md

@@ -14,11 +14,11 @@ See-also:
   - dns-ipv4-addr
 Example:
   - --dns-servers 192.168.0.1,192.168.0.2 $URL
+  - --dns-servers 10.0.0.1:53 $URL
 ---
 
 # `--dns-servers`
 
-Set the list of DNS servers to be used instead of the system default.
+Set the list of DNS servers to be used instead of the system default. The list
-The list of IP addresses should be separated with commas. Port numbers
+of IP addresses should be separated with commas. Port numbers may also
-may also optionally be given as *:<port-number>* after each IP
+optionally be given, appended to the IP address separated with a colon.
-address.

docs/cmdline-opts/form-string.md

@@ -17,7 +17,7 @@ Example:
 # `--form-string`
 
 Similar to --form except that the value string for the named parameter is used
-literally. Leading '@' and '<' characters, and the ';type=' string in
+literally. Leading @ and \< characters, and the `;type=` string in the value
-the value have no special meaning. Use this in preference to --form if
+have no special meaning. Use this in preference to --form if there is any
-there is any possibility that the string value may accidentally trigger the
+possibility that the string value may accidentally trigger the @ or \<
-'@' or '<' features of --form.
+features of --form.

docs/cmdline-opts/form.md

@@ -29,13 +29,13 @@ message to transmit.
 
 This enables uploading of binary files etc. To force the 'content' part to be
 a file, prefix the file name with an @ sign. To just get the content part from
-a file, prefix the file name with the symbol <. The difference between @ and <
+a file, prefix the file name with the symbol \<. The difference between @ and
-is then that @ makes a file get attached in the post as a file upload, while
+< is then that @ makes a file get attached in the post as a file upload, while
-the < makes a text field and just get the contents for that text field from a
+the \< makes a text field and just get the contents for that text field from a
 file.
 
 Tell curl to read content from stdin instead of a file by using - as
-filename. This goes for both @ and < constructs. When stdin is used, the
+filename. This goes for both @ and \< constructs. When stdin is used, the
 contents is buffered in memory first by curl to determine its size and allow a
 possible resend. Defining a part's data from a named non-regular file (such as
 a named pipe or similar) is not subject to buffering and is instead read at

docs/cmdline-opts/ftp-port.md

@@ -23,8 +23,8 @@ Example:
 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
 to the client's specified address and port, while passive mode asks the server
-to setup an IP address and port for it to connect to. <address> should be one
+to setup an IP address and port for it to connect to. \<address\> should be
-of:
+one of:
 
 ## interface
 e.g. **eth0** to specify which interface's IP address you want to use (Unix only)

docs/cmdline-opts/gen.pl

@@ -288,11 +288,19 @@ sub render {
             }
         }
 
-        if(!$quote && ($d =~ /^(.*)  /)) {
+        if(!$quote) {
-            printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n",
+            if($d =~ /^(.*)  /) {
-                length($1);
+                printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n",
-            return 3;
+                    length($1);
+                return 3;
+            }
+            elsif($d =~ /[^\\][\<\>]/) {
+                print STDERR "$f:$line:1:WARN: un-escaped < or > used\n";
+                return 3;
+            }
         }
+        # convert backslash-'<' or '> to just the second character
+        $d =~ s/\\([<<])/$1/g;
         # quote minuses in the output
         $d =~ s/([^\\])-/$1\\-/g;
         # replace single quotes

docs/cmdline-opts/output.md

@@ -21,10 +21,10 @@ Example:
 
 # `--output`
 
-Write output to <file> instead of stdout. If you are using {} or [] to fetch
+Write output to the given file instead of stdout. If you are using globbing to
-multiple documents, you should quote the URL and you can use '#' followed by a
+fetch multiple documents, you should quote the URL and you can use `#`
-number in the <file> specifier. That variable is replaced with the current
+followed by a number in the file name. That variable is then replaced with the
-string for the URL being fetched. Like in:
+current string for the URL being fetched. Like in:
 
     curl "http://{one,two}.example.com" -o "file_#1.txt"
 

docs/cmdline-opts/quote.md

@@ -43,7 +43,7 @@ all supported SFTP quote commands:
 
 ## atime date file
 The atime command sets the last access time of the file named by the file
-operand. The <date expression> can be all sorts of date strings, see the
+operand. The date expression can be all sorts of date strings, see the
 *curl_getdate(3)* man page for date expression details. (Added in 7.73.0)
 
 ## chgrp group file
@@ -69,7 +69,7 @@ The mkdir command creates the directory named by the directory_name operand.
 
 ## mtime date file
 The mtime command sets the last modification time of the file named by the
-file operand. The <date expression> can be all sorts of date strings, see the
+file operand. The date expression can be all sorts of date strings, see the
 *curl_getdate(3)* man page for date expression details. (Added in 7.73.0)
 
 ## pwd

docs/cmdline-opts/raw.md

@@ -2,7 +2,7 @@
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: raw
-Help: Do HTTP "raw"; no transfer decoding
+Help: Do HTTP raw; no transfer decoding
 Added: 7.16.2
 Protocols: HTTP
 Category: http

docs/cmdline-opts/referer.md

@@ -20,8 +20,8 @@ Example:
 
 # `--referer`
 
-Sends the "Referrer Page" information to the HTTP server. This can also be set
+Sends the referrer URL in the HTTP request. This can also be set with the
-with the --header flag of course. When used with --location you can append
+--header flag of course. When used with --location you can append `;auto`" to
-";auto" to the --referer URL to make curl automatically set the previous URL
+the --referer URL to make curl automatically set the previous URL when it
-when it follows a Location: header. The ";auto" string can be used alone,
+follows a Location: header. The `;auto` string can be used alone, even if you
-even if you do not set an initial --referer.
+do not set an initial --referer.

docs/cmdline-opts/remote-header-name.md

@@ -32,8 +32,8 @@ specify a file name then this option has no effect.
 There is no attempt to decode %-sequences (yet) in the provided file name, so
 this option may provide you with rather unexpected file names.
 
-This feature uses the name from the "filename" field, it does not yet support
+This feature uses the name from the `filename` field, it does not yet support
-the "filename*" field (filenames with explicit character sets).
+the `filename*` field (filenames with explicit character sets).
 
 **WARNING**: Exercise judicious use of this option, especially on Windows. A
 rogue server could send you the name of a DLL or other file that could be

docs/cmdline-opts/request-target.md

@@ -16,7 +16,7 @@ Example:
 
 # `--request-target`
 
-Tells curl to use an alternative "target" (path) instead of using the path as
+Tells curl to use an alternative target (path) instead of using the path as
 provided in the URL. Particularly useful when wanting to issue HTTP requests
 without leading slash or other data that does not follow the regular URL
 pattern, like "OPTIONS *".

docs/cmdline-opts/retry-all-errors.md

@@ -26,7 +26,7 @@ script. Please read the example below.
 transfers as close as possible to how they were started, but this is not
 possible with redirected input or output. For example, before retrying it
 removes output data from a failed partial transfer that was written to an
-output file. However this is not true of data redirected to a | pipe or >
+output file. However this is not true of data redirected to a | pipe or \>
 file, which are not reset. We strongly suggest you do not parse or record
 output via redirect in combination with this option, since you may receive
 duplicate data.

docs/cmdline-opts/tftp-blksize.md

@@ -16,6 +16,6 @@ Example:
 
 # `--tftp-blksize`
 
-Set the TFTP **BLKSIZE** option (must be >512). This is the block size that
+Set the TFTP **BLKSIZE** option (must be 512 or larger). This is the block
-curl tries to use when transferring data to or from a TFTP server. By
+size that curl tries to use when transferring data to or from a TFTP
-default 512 bytes are used.
+server. By default 512 bytes are used.

docs/cmdline-opts/time-cond.md

@@ -21,10 +21,10 @@ Example:
 # `--time-cond`
 
 Request a file that has been modified later than the given time and date, or
-one that has been modified before that time. The <date expression> can be all
+one that has been modified before that time. The date expression can be all
-sorts of date strings or if it does not match any internal ones, it is taken as
+sorts of date strings or if it does not match any internal ones, it is treated
-a filename and tries to get the modification date (mtime) from <file>
+as a filename and curl tries to get the modification date (mtime) from that
-instead. See the *curl_getdate(3)* man pages for date expression details.
+file instead. See the *curl_getdate(3)* man pages for date expression details.
 
 Start the date expression with a dash (-) to make it request for a document
 that is older than the given date/time, default is a document that is newer

docs/cmdline-opts/tlsauthtype.md

@@ -16,8 +16,8 @@ Example:
 
 # `--tlsauthtype`
 
-Set TLS authentication type. Currently, the only supported option is "SRP",
+Set TLS authentication type. Currently, the only supported option is `SRP`,
 for TLS-SRP (RFC 5054). If --tlsuser and --tlspassword are specified but
---tlsauthtype is not, then this option defaults to "SRP". This option works
+--tlsauthtype is not, then this option defaults to `SRP`. This option works
 only if the underlying libcurl is built with TLS-SRP support, which requires
 OpenSSL or GnuTLS with TLS-SRP support.

docs/cmdline-opts/trace-ascii.md

@@ -19,7 +19,7 @@ Example:
 # `--trace-ascii`
 
 Enables a full trace dump of all incoming and outgoing data, including
-descriptive information, to the given output file. Use "-" as filename to have
+descriptive information, to the given output file. Use `-` as filename to have
 the output sent to stdout.
 
 This is similar to --trace, but leaves out the hex part and only shows the

docs/cmdline-opts/trace-config.md

@@ -22,7 +22,7 @@ Set configuration for trace output. A comma-separated list of components where
 detailed output can be made available from. Names are case-insensitive.
 Specify 'all' to enable all trace components.
 
-In addition to trace component names, specify "ids" and "time" to
+In addition to trace component names, specify `ids` and `time` to avoid extra
-avoid extra --trace-ids or --trace-time parameters.
+--trace-ids or --trace-time parameters.
 
 See the *curl_global_trace(3)* man page for more details.

docs/cmdline-opts/upload-file.md

@@ -33,16 +33,16 @@ When putting the local file name at the end of the URL, curl ignores what is
 on the left side of any slash (/) or backslash (\) used in the file name and
 only appends what is on the right side of the rightmost such character.
 
-Use the file name "-" (a single dash) to use stdin instead of a given file.
+Use the file name `-` (a single dash) to use stdin instead of a given file.
-Alternately, the file name "." (a single period) may be specified instead of
+Alternately, the file name `.` (a single period) may be specified instead of
-"-" to use stdin in non-blocking mode to allow reading server output while
+`-` to use stdin in non-blocking mode to allow reading server output while
 stdin is being uploaded.
 
 If this option is used with a HTTP(S) URL, the PUT method is used.
 
 You can specify one --upload-file for each URL on the command line. Each
 --upload-file + URL pair specifies what to upload and to where. curl also
-supports "globbing" of the --upload-file argument, meaning that you can upload
+supports globbing of the --upload-file argument, meaning that you can upload
 multiple files to a single URL by using the same URL globbing style supported
 in the URL.
 

docs/cmdline-opts/url.md

@@ -19,7 +19,7 @@ Example:
 Specify a URL to fetch. This option is mostly handy when you want to specify
 URL(s) in a config file.
 
-If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
+If the given URL is missing a scheme name (such as `http://` or `ftp://` etc)
 then curl makes a guess based on the host. If the outermost subdomain name
 matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol is used,
 otherwise HTTP is used. Guessing can be avoided by providing a full URL
@@ -29,5 +29,5 @@ including the scheme, or disabled by setting a default protocol (added in
 To control where this URL is written, use the --output or the --remote-name
 options.
 
-**WARNING**: On Windows, particular file:// accesses can be converted to
+**WARNING**: On Windows, particular `file://` accesses can be converted to
 network accesses by the operating system. Beware!

docs/cmdline-opts/use-ascii.md

@@ -18,5 +18,5 @@ Example:
 # `--use-ascii`
 
 Enable ASCII transfer. For FTP, this can also be enforced by using a URL that
-ends with ";type=A". This option causes data sent to stdout to be in text mode
+ends with `;type=A`. This option causes data sent to stdout to be in text mode
 for win32 systems.

docs/cmdline-opts/variable.md

@@ -15,22 +15,22 @@ Example:
 
 # `--variable`
 
-Set a variable with "name=content" or "name@file" (where "file" can be stdin
+Set a variable with `name=content` or `name@file` (where `file` can be stdin
-if set to a single dash (-)). The name is a case sensitive identifier that
+if set to a single dash (`-`)). The name is a case sensitive identifier that
 must consist of no other letters than a-z, A-Z, 0-9 or underscore. The
 specified content is then associated with this identifier.
 
 Setting the same variable name again overwrites the old contents with the new.
 
 The contents of a variable can be referenced in a later command line option
-when that option name is prefixed with "--expand-", and the name is used as
+when that option name is prefixed with `--expand-`, and the name is used as
-"{{name}}" (without the quotes).
+`{{name}}`.
 
 --variable can import environment variables into the name space. Opt to either
 require the environment variable to be set or provide a default value for the
 variable in case it is not already set.
 
---variable %name imports the variable called 'name' but exits with an error if
+--variable %name imports the variable called `name` but exits with an error if
 that environment variable is not already set. To provide a default value if
 the environment variable is not set, use --variable %name=content or
 --variable %name@content. Note that on some systems - but not all -

docs/cmdline-opts/verbose.md

@@ -21,10 +21,9 @@ Example:
 # `--verbose`
 
 Makes curl verbose during the operation. Useful for debugging and seeing
-what's going on "under the hood". A line starting with '>' means "header data"
+what's going on under the hood. A line starting with \> means header data sent
-sent by curl, '<' means "header data" received by curl that is hidden in
+by curl, \< means header data received by curl that is hidden in normal cases,
-normal cases, and a line starting with '*' means additional info provided by
+and a line starting with * means additional info provided by curl.
-curl.
 
 If you only want HTTP headers in the output, --include or --dump-header might
 be more suitable options.

docs/cmdline-opts/write-out.md

@@ -42,7 +42,7 @@ Select a specific target destination file to write the output to, by using
 output following that instruction is then written to that file. More than one
 *%output{}* instruction can be specified in the same write-out argument. If
 the file name cannot be created, curl leaves the output destination to the one
-used prior to the *%output{}* instruction. Use *%output{>>name}* to append
+used prior to the *%output{}* instruction. Use *%output{\>\>name}* to append
 data to an existing file.
 
 **NOTE:**

src/tool_listhelp.c

@@ -583,7 +583,7 @@ const struct helptxt helptext[] = {
    "Request rate for serial transfers",
    CURLHELP_CONNECTION},
   {"    --raw",
-   "Do HTTP \"raw\"; no transfer decoding",
+   "Do HTTP raw; no transfer decoding",
    CURLHELP_HTTP},
   {"-e, --referer <URL>",
    "Referrer URL",