From: Daniel Stenberg Date: Mon, 5 Feb 2024 22:23:56 +0000 (+0100) Subject: docs: make curldown do angle brackets like markdown X-Git-Tag: curl-8_7_0~220 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=d94733b4478a08a9ae9f9e60a1ee9148a867f6c5;p=thirdparty%2Fcurl.git 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 --- diff --git a/docs/CURLDOWN.md b/docs/CURLDOWN.md index 2e89eed6a8..1eb3d8f481 100644 --- a/docs/CURLDOWN.md +++ b/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 diff --git a/docs/libcurl/curl_easy_perform.md b/docs/libcurl/curl_easy_perform.md index ff65a82ee7..4f0989b9b6 100644 --- a/docs/libcurl/curl_easy_perform.md +++ b/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 -** 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. +*\* 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. diff --git a/docs/libcurl/curl_easy_setopt.md b/docs/libcurl/curl_easy_setopt.md index 5724b09cb1..76404ed243 100644 --- a/docs/libcurl/curl_easy_setopt.md +++ b/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 ** defines. See the libcurl-errors(3) man page -for the full list with descriptions. +error occurred as *\* 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). diff --git a/docs/libcurl/curl_formadd.md b/docs/libcurl/curl_formadd.md index 3793df8fa3..479f7f626c 100644 --- a/docs/libcurl/curl_formadd.md +++ b/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 -** +0 means everything was OK, non-zero means an error occurred corresponding to a +CURL_FORMADD_* constant defined in *\*. diff --git a/docs/libcurl/curl_global_init_mem.md b/docs/libcurl/curl_global_init_mem.md index 3bf468f18d..96af23b05f 100644 --- a/docs/libcurl/curl_global_init_mem.md +++ b/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 -** defines - see libcurl-errors(3). +*\* defines - see libcurl-errors(3). diff --git a/docs/libcurl/curl_share_cleanup.md b/docs/libcurl/curl_share_cleanup.md index 59126a145b..f4220566da 100644 --- a/docs/libcurl/curl_share_cleanup.md +++ b/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 ** 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 *\* 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. diff --git a/docs/libcurl/curl_share_setopt.md b/docs/libcurl/curl_share_setopt.md index 5ab95503be..8caaaea9ad 100644 --- a/docs/libcurl/curl_share_setopt.md +++ b/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 ** defines. See the libcurl-errors(3) -man page for the full list with descriptions. +error occurred as *\* defines. See the libcurl-errors(3) man +page for the full list with descriptions. diff --git a/docs/libcurl/curl_version_info.md b/docs/libcurl/curl_version_info.md index 9fc764e184..45e46a1b9e 100644 --- a/docs/libcurl/curl_version_info.md +++ b/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 diff --git a/docs/libcurl/curl_ws_send.md b/docs/libcurl/curl_ws_send.md index a5a056c9da..e521ff20aa 100644 --- a/docs/libcurl/curl_ws_send.md +++ b/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 ** defines. See the libcurl-errors(3) -man page for the full list with descriptions. +error occurred as *\* defines. See the libcurl-errors(3) man +page for the full list with descriptions. diff --git a/docs/libcurl/libcurl-errors.md b/docs/libcurl/libcurl-errors.md index 2a7c8bf715..eb75753b0f 100644 --- a/docs/libcurl/libcurl-errors.md +++ b/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) diff --git a/docs/libcurl/libcurl-tutorial.md b/docs/libcurl/libcurl-tutorial.md index 2bf5f05474..de110bb30f 100644 --- a/docs/libcurl/libcurl-tutorial.md +++ b/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
tag uses. We provide a pointer to the data and tell +pages using the \ tag uses. We provide a pointer to the data and tell libcurl to post it all to the remote site: ~~~c diff --git a/docs/libcurl/libcurl-url.md b/docs/libcurl/libcurl-url.md index a2948001ae..c7a9ca2bb0 100644 --- a/docs/libcurl/libcurl-url.md +++ b/docs/libcurl/libcurl-url.md @@ -24,7 +24,7 @@ The URL interface provides functions for parsing and generating URLs. # INCLUDE -You still only include in your code. +You still only include \ in your code. # CREATE diff --git a/docs/libcurl/libcurl-ws.md b/docs/libcurl/libcurl-ws.md index 40f7c039c6..5ba05d8fae 100644 --- a/docs/libcurl/libcurl-ws.md +++ b/docs/libcurl/libcurl-ws.md @@ -25,7 +25,7 @@ data. # INCLUDE -You still only include in your code. +You still only include \ in your code. # SETUP diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.md b/docs/libcurl/opts/CURLOPT_FAILONERROR.md index 7ea5cedc68..5eedf840f5 100644 --- a/docs/libcurl/opts/CURLOPT_FAILONERROR.md +++ b/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 diff --git a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md index 090a8fc2d2..e8471957ab 100644 --- a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md +++ b/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 diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md index a5dbc7d79f..172656defa 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md +++ b/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. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md index c4984b056a..5e83dbab3b 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md +++ b/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 diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md index ce57074f01..e1b3f1555a 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md +++ b/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 diff --git a/docs/libcurl/opts/CURLOPT_NETRC.md b/docs/libcurl/opts/CURLOPT_NETRC.md index 89a55b4d9b..d5acdd5df3 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.md +++ b/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 +## machine \ 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 + default login anonymous password user@domain -## login +## login \ The user name string for the remote machine. -## password +## password \ 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 +## macdef \ 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 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md index f3c5448f0a..fd59de469e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md +++ b/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 diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.md b/docs/libcurl/opts/CURLOPT_QUOTE.md index f57b45eec1..9ba912ba65 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.md +++ b/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 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 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 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md index 521084388a..819ea07d48 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md +++ b/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 diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.md b/docs/libcurl/opts/CURLOPT_SSLCERT.md index 8400e6e2a8..e145083531 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.md +++ b/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 -"\\\\" 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). +"\\\\\\\" 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). diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md index e1db12ed8d..5fa6348381 100644 --- a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md +++ b/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 . libcurl -supports the options **TTYPE**, **XDISPLOC** and **NEW_ENV**. See the -TELNET standard for details. +negotiations. The variables should be in the format \. libcurl +supports the options **TTYPE**, **XDISPLOC** and **NEW_ENV**. See the TELNET +standard for details. # DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md index add1f2f8ea..d7c7a35106 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md +++ b/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. diff --git a/scripts/cd2nroff b/scripts/cd2nroff index 17a83b49cb..decaeca0a8 100755 --- a/scripts/cd2nroff +++ b/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