docs: make curldown do angle brackets like markdown

Make sure we use \< and \> in markdown all over so that it renders
correctly, on GitHub and elsewhere. cd2nroff now outputs a warning if it
finds an unescaled angle bracket.

Ref: #12854
Closes #12869

docs/CURLDOWN.md

@@ -115,6 +115,11 @@ When generating the nroff output, the tooling will remove superfluous newlines,
 meaning they can be used freely in the source file to make the text more
 readable.
 
+To make sure curldown documents render correctly as markdown, all literal
+occurrences of `<` or `>` need to be escaped by a leading backslash.
+
+## symbols
+
 All mentioned curl symbols that have their own man pages, like
 `curl_easy_perform(3)` will automatically be rendered using italics in the
 output without having to enclose it with asterisks. This helps ensuring that

docs/libcurl/curl_easy_perform.md

@@ -78,6 +78,6 @@ Always
 # RETURN VALUE
 
 CURLE_OK (0) means everything was OK, non-zero means an error occurred as
-*<curl/curl.h>* defines - see libcurl-errors(3). If the CURLOPT_ERRORBUFFER(3)
-was set with curl_easy_setopt(3) there is a readable error message stored in
-the error buffer when non-zero is returned.
+*\<curl/curl.h\>* defines - see libcurl-errors(3). If CURLOPT_ERRORBUFFER(3)
+was set with curl_easy_setopt(3) there is an error message stored in the error
+buffer when non-zero is returned.

docs/libcurl/curl_easy_setopt.md

@@ -267,7 +267,7 @@ Fail on HTTP 4xx errors. CURLOPT_FAILONERROR(3)
 
 ## CURLOPT_KEEP_SENDING_ON_ERROR
 
-Keep sending on HTTP >= 300 errors. CURLOPT_KEEP_SENDING_ON_ERROR(3)
+Keep sending on HTTP \>= 300 errors. CURLOPT_KEEP_SENDING_ON_ERROR(3)
 
 # NETWORK OPTIONS
 
@@ -826,7 +826,7 @@ Client CSEQ number. See CURLOPT_RTSP_CLIENT_CSEQ(3)
 
 ## CURLOPT_RTSP_SERVER_CSEQ
 
-CSEQ number for RTSP Server->Client request. See CURLOPT_RTSP_SERVER_CSEQ(3)
+CSEQ number for RTSP Server-\>Client request. See CURLOPT_RTSP_SERVER_CSEQ(3)
 
 ## CURLOPT_AWS_SIGV4
 
@@ -1366,8 +1366,8 @@ Always
 # RETURN VALUE
 
 *CURLE_OK* (zero) means that the option was set properly, non-zero means an
-error occurred as *<curl/curl.h>* defines. See the libcurl-errors(3) man page
-for the full list with descriptions.
+error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
+page for the full list with descriptions.
 
 Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise
 curl_easy_setopt(3) returns **CURLE_BAD_FUNCTION_ARGUMENT** (added in 7.65.0).

docs/libcurl/curl_formadd.md

@@ -308,6 +308,5 @@ double quotes in field and file names are now escaped before transmission.
 
 # RETURN VALUE
 
-0 means everything was OK, non-zero means an error occurred corresponding
-to a CURL_FORMADD_* constant defined in
-*<curl/curl.h>*
+0 means everything was OK, non-zero means an error occurred corresponding to a
+CURL_FORMADD_* constant defined in *\<curl/curl.h\>*.

docs/libcurl/curl_global_init_mem.md

@@ -92,4 +92,4 @@ Added in 7.12.0
 # RETURN VALUE
 
 CURLE_OK (0) means everything was OK, non-zero means an error occurred as
-*<curl/curl.h>* defines - see libcurl-errors(3).
+*\<curl/curl.h\>* defines - see libcurl-errors(3).

docs/libcurl/curl_share_cleanup.md

@@ -49,6 +49,6 @@ Added in 7.10
 # RETURN VALUE
 
 CURLSHE_OK (zero) means that the option was set properly, non-zero means an
-error occurred as *<curl/curl.h>* defines. See the libcurl-errors(3)
-man page for the full list with descriptions. If an error occurs, then the
-share object is not deleted.
+error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
+page for the full list with descriptions. If an error occurs, then the share
+object is not deleted.

docs/libcurl/curl_share_setopt.md

@@ -67,5 +67,5 @@ Added in 7.10
 # RETURN VALUE
 
 CURLSHE_OK (zero) means that the option was set properly, non-zero means an
-error occurred as *<curl/curl.h>* defines. See the libcurl-errors(3)
-man page for the full list with descriptions.
+error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
+page for the full list with descriptions.

docs/libcurl/curl_version_info.md

@@ -112,8 +112,8 @@ that you have a matching struct for in the header, as you tell libcurl your
 
 *version* is just an ascii string for the libcurl version.
 
-*version_num* is a 24 bit number created like this: <8 bits major number>
-| <8 bits minor number> | <8 bits patch number>. Version 7.9.8 is therefore
+*version_num* is a 24 bit number created like this: \<8 bits major number\> |
+\<8 bits minor number\> | \<8 bits patch number\>. Version 7.9.8 is therefore
 returned as 0x070908.
 
 *host* is an ascii string showing what host information that this libcurl

docs/libcurl/curl_ws_send.md

@@ -116,5 +116,5 @@ Added in 7.86.0.
 # RETURN VALUE
 
 *CURLE_OK* (zero) means that the data was sent properly, non-zero means an
-error occurred as *<curl/curl.h>* defines. See the libcurl-errors(3)
-man page for the full list with descriptions.
+error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
+page for the full list with descriptions.

docs/libcurl/libcurl-errors.md

@@ -145,8 +145,8 @@ indicated unsuccessful completion of the command.
 
 ## CURLE_HTTP_RETURNED_ERROR (22)
 
-This is returned if CURLOPT_FAILONERROR(3) is set TRUE and the HTTP
-server returns an error code that is >= 400.
+This is returned if CURLOPT_FAILONERROR(3) is set TRUE and the HTTP server
+returns an error code that is \>= 400.
 
 ## CURLE_WRITE_ERROR (23)
 

docs/libcurl/libcurl-tutorial.md

@@ -461,7 +461,7 @@ proper way. This chapter thus includes examples using both different versions
 of HTTP POST that libcurl supports.
 
 The first version is the simple POST, the most common version, that most HTML
-pages using the <form> tag uses. We provide a pointer to the data and tell
+pages using the \<form\> tag uses. We provide a pointer to the data and tell
 libcurl to post it all to the remote site:
 
 ~~~c

docs/libcurl/libcurl-url.md

@@ -24,7 +24,7 @@ The URL interface provides functions for parsing and generating URLs.
 
 # INCLUDE
 
-You still only include <curl/curl.h> in your code.
+You still only include \<curl/curl.h\> in your code.
 
 # CREATE
 

docs/libcurl/libcurl-ws.md

@@ -25,7 +25,7 @@ data.
 
 # INCLUDE
 
-You still only include <curl/curl.h> in your code.
+You still only include \<curl/curl.h\> in your code.
 
 # SETUP
 

docs/libcurl/opts/CURLOPT_FAILONERROR.md

@@ -12,7 +12,7 @@ See-also:
 
 # NAME
 
-CURLOPT_FAILONERROR - request failure on HTTP response >= 400
+CURLOPT_FAILONERROR - request failure on HTTP response \>= 400
 
 # SYNOPSIS
 

docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md

@@ -12,7 +12,7 @@ See-also:
 
 # NAME
 
-CURLOPT_KEEP_SENDING_ON_ERROR - keep sending on early HTTP response >= 300
+CURLOPT_KEEP_SENDING_ON_ERROR - keep sending on early HTTP response \>= 300
 
 # SYNOPSIS
 

docs/libcurl/opts/CURLOPT_MAIL_AUTH.md

@@ -34,10 +34,10 @@ server acting in such an environment. If the application is operating as such
 and the AUTH address is not known or is invalid, then an empty string should
 be used for this parameter.
 
-Unlike CURLOPT_MAIL_FROM(3) and CURLOPT_MAIL_RCPT(3), the address
-should not be specified within a pair of angled brackets (<>). However, if an
-empty string is used then a pair of brackets are sent by libcurl as required
-by RFC 2554.
+Unlike CURLOPT_MAIL_FROM(3) and CURLOPT_MAIL_RCPT(3), the address should not
+be specified within a pair of angled brackets (\<\>). However, if an empty
+string is used then a pair of brackets are sent by libcurl as required by RFC
+2554.
 
 The application does not have to keep the string around after setting this
 option.

docs/libcurl/opts/CURLOPT_MAIL_FROM.md

@@ -26,7 +26,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_FROM, char *from);
 Pass a pointer to a null-terminated string as parameter. This should be used
 to specify the sender's email address when sending SMTP mail with libcurl.
 
-An originator email address should be specified with angled brackets (<>)
+An originator email address should be specified with angled brackets (\<\>)
 around it, which if not specified are added automatically.
 
 If this parameter is not specified then an empty address is sent to the SMTP

docs/libcurl/opts/CURLOPT_MAIL_RCPT.md

@@ -26,13 +26,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT,
 
 Pass a pointer to a linked list of recipients to pass to the server in your
 SMTP mail request. The linked list should be a fully valid list of
-**struct curl_slist** structs properly filled in. Use
-curl_slist_append(3) to create the list and curl_slist_free_all(3)
-to clean up an entire list.
+**struct curl_slist** structs properly filled in. Use curl_slist_append(3) to
+create the list and curl_slist_free_all(3) to clean up an entire list.
 
 When performing a mail transfer, each recipient should be specified within a
-pair of angled brackets (<>), however, should you not use an angled bracket as
-the first character libcurl assumes you provided a single email address and
+pair of angled brackets (\<\>), however, should you not use an angled bracket
+as the first character libcurl assumes you provided a single email address and
 encloses that address within brackets for you.
 
 When performing an address verification (**VRFY** command), each recipient
@@ -40,8 +39,8 @@ should be specified as the user name or user name and domain (as per Section
 3.5 of RFC 5321).
 
 When performing a mailing list expand (**EXPN** command), each recipient
-should be specified using the mailing list name, such as "Friends" or
-"London-Office".
+should be specified using the mailing list name, such as `Friends` or
+`London-Office`.
 
 # DEFAULT
 

docs/libcurl/opts/CURLOPT_NETRC.md

@@ -76,7 +76,7 @@ and end with double quotes and support the escaped special letters ", n,
 r, and t. Quoted strings are the only way a space character can be used in
 a user name or password.
 
-## machine <name>
+## machine \<name\>
 
 Provides credentials for a host called **name**. libcurl searches the .netrc
 file for a machine token that matches the hostname specified in the URL. Once
@@ -85,25 +85,25 @@ file is reached or another "machine" is encountered.
 
 ## default
 
-This is the same as "machine" name except that default matches any name. There
+This is the same as machine name except that default matches any name. There
 can be only one default token, and it must be after all machine tokens. To
 provide a default anonymous login for hosts that are not otherwise matched,
 add a line similar to this in the end:
 
     default login anonymous password user@domain
 
-## login <name>
+## login \<name\>
 
 The user name string for the remote machine.
 
-## password <secret>
+## password \<secret\>
 
 Supply a password. If this token is present, curl supplies the specified
 string if the remote server requires a password as part of the login process.
 Note that if this token is present in the .netrc file you really should make
 sure the file is not readable by anyone besides the user.
 
-## macdef <name>
+## macdef \<name\>
 
 Define a macro. This feature is not supported by libcurl. In order for the
 rest of the .netrc to still work fine, libcurl properly skips every definition

docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md

@@ -71,7 +71,7 @@ int main(void)
 # AVAILABILITY
 
 Added in 7.61.0.
-Available when built with OpenSSL >= 1.1.1.
+Available when built with OpenSSL \>= 1.1.1.
 
 # RETURN VALUE
 

docs/libcurl/opts/CURLOPT_QUOTE.md

@@ -57,7 +57,7 @@ path. e.g. rename with sftp using a quote command like this:
 ## 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
@@ -89,7 +89,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/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md

@@ -24,8 +24,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SERVER_CSEQ, long cseq);
 
 # DESCRIPTION
 
-Pass a long to set the CSEQ number to expect for the next RTSP Server->Client
-request. **NOTE**: this feature (listening for Server requests) is
+Pass a long to set the CSEQ number to expect for the next RTSP Server to
+Client request. **NOTE**: this feature (listening for Server requests) is
 unimplemented.
 
 # DEFAULT

docs/libcurl/opts/CURLOPT_SSLCERT.md

@@ -25,25 +25,26 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT, char *cert);
 # DESCRIPTION
 
 Pass a pointer to a null-terminated string as parameter. The string should be
-the filename of your client certificate. The default format is "P12" on Secure
-Transport and "PEM" on other engines, and can be changed with
+the filename of your client certificate. The default format is `P12` on Secure
+Transport and `PEM` on other engines, and can be changed with
 CURLOPT_SSLCERTTYPE(3).
 
 With Secure Transport, this can also be the nickname of the certificate you
 wish to authenticate with as it is named in the security database. If you want
-to use a file from the current directory, please precede it with "./" prefix,
+to use a file from the current directory, please precede it with `./` prefix,
 in order to avoid confusion with a nickname.
 
 (Schannel only) Client certificates can be specified by a path expression to a
 certificate store. (You can import *PFX* to a store first). You can use
-"<store location>\\<store name>\\<thumbprint>" to refer to a certificate in the
-system certificates store, for example,
-**"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"**. The thumbprint is 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**. Schannel also support P12 certificate file, with
-the string "P12" specified with CURLOPT_SSLCERTTYPE(3).
+"\<store location\>\\\<store name\>\\\<thumbprint\>" to refer to a certificate
+in the system certificates store, for example,
+**"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"**. The thumbprint is 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**. Schannel also support
+P12 certificate file, with the string `P12` specified with
+CURLOPT_SSLCERTTYPE(3).
 
 When using a client certificate, you most likely also need to provide a
 private key with CURLOPT_SSLKEY(3).

docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md

@@ -25,9 +25,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TELNETOPTIONS,
 # DESCRIPTION
 
 Provide a pointer to a curl_slist with variables to pass to the telnet
-negotiations. The variables should be in the format <option=value>. libcurl
-supports the options **TTYPE**, **XDISPLOC** and **NEW_ENV**. See the
-TELNET standard for details.
+negotiations. The variables should be in the format \<option=value\>. libcurl
+supports the options **TTYPE**, **XDISPLOC** and **NEW_ENV**. See the TELNET
+standard for details.
 
 # DEFAULT
 

docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md

@@ -71,7 +71,7 @@ int main(void)
 
 # AVAILABILITY
 
-Added in 7.61.0 for OpenSSL. Available when built with OpenSSL >= 1.1.1.
+Added in 7.61.0 for OpenSSL. Available when built with OpenSSL \>= 1.1.1.
 
 Added in 7.85.0 for Schannel.
 

scripts/cd2nroff

@@ -243,11 +243,20 @@ sub single {
             next;
         }
 
+        # remove single line HTML comments
+        $d =~ s/<!--.*?-->//g;
+
         # **bold**
         $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g;
         # *italics*
         $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g;
 
+        if($d =~ /[^\\][\<\>]/) {
+            print STDERR "$f:$line:1:WARN: un-escaped < or > used\n";
+        }
+        # convert backslash-'<' or '> to just the second character
+        $d =~ s/\\([<<])/$1/g;
+
         # mentions of curl symbols with man pages use italics by default
         $d =~ s/((lib|)curl([^ ]*\(3\)))/\\fI$1\\fP/gi;
 
@@ -307,9 +316,6 @@ sub single {
             $blankline = 0;
             $header = 0;
 
-            # remove single line HTML comments
-            $d =~ s/<!--.*?-->//g;
-
             # quote minuses in the output
             $d =~ s/([^\\])-/$1\\-/g;
             # replace single quotes