From: Daniel Stenberg Date: Wed, 17 Jan 2024 13:27:16 +0000 (+0100) Subject: docs: cleanup nroff format use X-Git-Tag: curl-8_6_0~72 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6b930f1bfb31cad614d3f6f97f841d09daacdda8;p=thirdparty%2Fcurl.git docs: cleanup nroff format use - remove use of .BI for code snippet - stop using .br, just do a blank line - remove use of .PP - remove use for .sp - remove backslash in .IP - use .IP instead of .TP Closes #12731 --- diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index 395ae7df69..583092169f 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -32,13 +32,14 @@ int curl_formget(struct curl_httppost * form, void *userp, curl_formget_callback append); .fi .SH DESCRIPTION -curl_formget() is used to serialize data previously built/appended with -\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named -\fIuserp\fP which is passed as the first argument to the curl_formget_callback -function. +curl_formget() serializes data previously built with \fIcurl_formadd(3)\fP. It +accepts a void pointer as second argument named \fIuserp\fP which is passed as +the first argument to the curl_formget_callback function. -.BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf, -.BI " size_t " len ");" +.nf + typedef size_t (*curl_formget_callback)(void *userp, const char *buf, + size_t len);" +.fi The curl_formget_callback is invoked for each part of the HTTP POST chain. The character buffer passed to the callback must not be freed. The callback should diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 42dc29997e..91c55235fa 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -43,28 +43,23 @@ wrong dates, such as February 30. A "date" is a string containing several items separated by whitespace. The order of the items is immaterial. A date string may contain many flavors of items: -.TP 0.8i -.B calendar date items +.IP "calendar date items" Can be specified several ways. Month names can only be three-letter English abbreviations, numbers can be zero-prefixed and the year may use 2 or 4 digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. -.TP -.B time of the day items +.IP "time of the day items" This string specifies the time on a given day. You must specify it with 6 digits with two colons: HH:MM:SS. If there is no time given in a provided date string, 00:00:00 is assumed. Example: 18:19:21. -.TP -.B time zone items +.IP "time zone items" Specifies international time zone. There are a few acronyms supported, but in general you should instead use the specific relative time compared to UTC. Supported formats include: -1200, MST, +0100. -.TP -.B day of the week items +.IP "day of the week items" Specifies a day of the week. Days of the week may be spelled out in full (using English): `Sunday', `Monday', etc or they may be abbreviated to their first three letters. This is usually not info that adds anything. -.TP -.B pure numbers +.IP "pure numbers" If a decimal number of the form YYYYMMDD appears, then YYYY is read as the year, MM as the month number and DD as the day of the month, for the specified calendar date. diff --git a/docs/libcurl/curl_global_init_mem.3 b/docs/libcurl/curl_global_init_mem.3 index 3aa65ba934..b41087531e 100644 --- a/docs/libcurl/curl_global_init_mem.3 +++ b/docs/libcurl/curl_global_init_mem.3 @@ -57,7 +57,7 @@ To replace realloc() To replace strdup() .IP "void *calloc_callback(size_t nmemb, size_t size);" To replace calloc() -.PP + This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer to that man page for documentation. .SH CAUTION diff --git a/docs/libcurl/curl_mime_encoder.3 b/docs/libcurl/curl_mime_encoder.3 index 64c2636e31..f6eaa2ec6e 100644 --- a/docs/libcurl/curl_mime_encoder.3 +++ b/docs/libcurl/curl_mime_encoder.3 @@ -47,17 +47,17 @@ pertaining scheme and a corresponding \fI"Content-Transfer-Encoding"\fP header is added to the part. Supported encoding schemes are: -.br + "\fIbinary\fP": the data is left unchanged, the header is added. -.br + "\fI8bit\fP": header added, no data change. -.br + "\fI7bit\fP": the data is unchanged, but is each byte is checked to be a 7-bit value; if not, a read error occurs. -.br + "\fIbase64\fP": Data is converted to base64 encoding, then split in CRLF-terminated lines of at most 76 characters. -.br + "\fIquoted-printable\fP": data is encoded in quoted printable lines of at most 76 characters. Since the resulting size of the final data cannot be determined prior to reading the original data, it is left as unknown, causing diff --git a/docs/libcurl/curl_mime_type.3 b/docs/libcurl/curl_mime_type.3 index 6d0c6a8729..3e4ac822ba 100644 --- a/docs/libcurl/curl_mime_type.3 +++ b/docs/libcurl/curl_mime_type.3 @@ -44,16 +44,16 @@ is valid: only the value set by the last call is retained. In the absence of a mime type and if needed by the protocol specifications, a default mime type is determined by the context: -.br + - If set as a custom header, use this value. -.br + - application/form-data for an HTTP form post. -.br + - If a remote file name is set, the mime type is taken from the file name extension, or application/octet-stream by default. -.br + - For a multipart part, multipart/mixed. -.br + - text/plain in other cases. .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index c60ef0a812..ac746cbea3 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -112,24 +112,20 @@ string. .SH "Flag characters" The character % is followed by zero or more of the following flags: -.TP -.B # + +.IP # The value should be converted to its "alternate form". -.TP -.B 0 +.IP 0 The value should be zero padded. -.TP -.B - +.IP - The converted value is to be left adjusted on the field boundary. (The default is right justification.) The converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A '-' overrides a \&'0' if both are given. -.TP -.B ' ' +.IP ' ' (a space) A blank should be left before a positive number (or empty string) produced by a signed conversion. -.TP -.B + +.IP + A sign (+ or -) should always be placed before a number produced by a signed conversion. By default, a sign is used only for negative numbers. A '+' overrides a space if both are used. @@ -159,43 +155,35 @@ after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and \fBG\fP conversions, or the maximum number of characters to be printed from a string for \fBs\fP and \fBS\fP conversions. .SH "Length modifier" -.TP -.B h +.IP h A following integer conversion corresponds to a \fIshort\fP or \fIunsigned short\fP argument. -.TP -.B l +.IP l (ell) A following integer conversion corresponds to a \fIlong\fP or \fIunsigned long\fP argument, or a following n conversion corresponds to a pointer to a long argument -.TP -.B ll +.IP ll (ell-ell). A following integer conversion corresponds to a \fIlong long\fP or \fIunsigned long long\fP argument, or a following n conversion corresponds to a pointer to a long long argument. -.TP -.B q +.IP q A synonym for \fBll\fP. -.TP -.B L +.IP L A following a, A, e, E, f, F, g, or G conversion corresponds to a long double argument. -.TP -.B z +.IP z A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP argument. .SH "Conversion specifiers" A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are: -.TP -.B d, i +.IP "d, i" The int argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. -.TP -.B o, u, x, X +.IP "o, u, x, X" The unsigned int argument is converted to unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters \fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are @@ -203,38 +191,30 @@ used for \fBX\fP conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. -.TP -.B e, E +.IP "e, E" The double argument is rounded and output in the style \fB"[-]d.ddde±dd"\fP -.TP -.B f, F +.IP "f, F" The double argument is rounded and output to decimal notation in the style \fB"[-]ddd.ddd"\fP. -.TP -.B g, G +.IP "g, G" The double argument is converted in style f or e. -.TP -.B c +.IP "c" The int argument is converted to an unsigned char, and the resulting character is written. -.TP -.B s +.IP "s" The \fIconst char *\fP argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating null byte. If a precision is specified, no more than the number specified are written. If a precision is given, no null byte need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating null byte. -.TP -.B p +.IP "p" The \fIvoid *\fP pointer argument is printed in hexadecimal. -.TP -.B n +.IP "n" The number of characters written so far is stored into the integer pointed to by the corresponding argument. -.TP -.B % -A '%' is written. No argument is converted. +.IP "%" +A '%' symbol is written. No argument is converted. .SH EXAMPLE .nf const char *name = "John"; diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index 89eec323f5..dc21c2e3ba 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -32,15 +32,13 @@ int curl_strequal(const char *str1, const char *str2); int curl_strnequal(const char *str1, const char *str2, size_t length); .fi .SH DESCRIPTION -The -.B curl_strequal() -function compares the two strings \fIstr1\fP and \fIstr2\fP, ignoring the case -of the characters. It returns a non-zero (TRUE) integer if the strings are -identical. -.sp +The \fIcurl_strequal(3)\fP function compares the two strings \fIstr1\fP and +\fIstr2\fP, ignoring the case of the characters. It returns a non-zero (TRUE) +integer if the strings are identical. + The \fBcurl_strnequal()\fP function is similar, except it only compares the first \fIlength\fP characters of \fIstr1\fP. -.sp + These functions are provided by libcurl to enable applications to compare strings in a truly portable manner. There are no standard portable case insensitive string comparison functions. These two work on all platforms. diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index e7fb8af659..32bea8272b 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -141,153 +141,153 @@ entry. Currently defined names are: .RS .IP """alt-svc""" \fIfeatures\fP mask bit: CURL_VERSION_ALTSVC -.br + HTTP Alt-Svc parsing and the associated options (Added in 7.64.1) .IP """AsynchDNS""" \fIfeatures\fP mask bit: CURL_VERSION_ASYNCHDNS -.br + libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi interface. (added in 7.10.7) .IP """brotli""" \fIfeatures\fP mask bit: CURL_VERSION_BROTLI -.br + supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0) .IP """Debug""" \fIfeatures\fP mask bit: CURL_VERSION_DEBUG -.br + libcurl was built with debug capabilities (added in 7.10.6) .IP """gsasl""" \fIfeatures\fP mask bit: CURL_VERSION_GSASL -.br + libcurl was built with libgsasl and thus with some extra SCRAM-SHA authentication methods. (added in 7.76.0) .IP """GSS-API""" \fIfeatures\fP mask bit: CURL_VERSION_GSSAPI -.br + libcurl was built with support for GSS-API. This makes libcurl use provided functions for Kerberos and SPNEGO authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.38.0) .IP """HSTS""" \fIfeatures\fP mask bit: CURL_VERSION_HSTS -.br + libcurl was built with support for HSTS (HTTP Strict Transport Security) (Added in 7.74.0) .IP """HTTP2""" \fIfeatures\fP mask bit: CURL_VERSION_HTTP2 -.br + libcurl was built with support for HTTP2. (Added in 7.33.0) .IP """HTTP3""" \fIfeatures\fP mask bit: CURL_VERSION_HTTP3 -.br + HTTP/3 and QUIC support are built-in (Added in 7.66.0) .IP """HTTPS-proxy""" \fIfeatures\fP mask bit: CURL_VERSION_HTTPS_PROXY -.br + libcurl was built with support for HTTPS-proxy. (Added in 7.52.0) .IP """IDN""" \fIfeatures\fP mask bit: CURL_VERSION_IDN -.br + libcurl was built with support for IDNA, domain names with international letters. (Added in 7.12.0) .IP """IPv6""" \fIfeatures\fP mask bit: CURL_VERSION_IPV6 -.br + supports IPv6 .IP """Kerberos""" \fIfeatures\fP mask bit: CURL_VERSION_KERBEROS5 -.br + supports Kerberos V5 authentication for FTP, IMAP, LDAP, POP3, SMTP and SOCKSv5 proxy. (Added in 7.40.0) .IP """Largefile""" \fIfeatures\fP mask bit: CURL_VERSION_LARGEFILE -.br + libcurl was built with support for large files. (Added in 7.11.1) .IP """libz""" \fIfeatures\fP mask bit: CURL_VERSION_LIBZ -.br + supports HTTP deflate using libz (Added in 7.10) .IP """MultiSSL""" \fIfeatures\fP mask bit: CURL_VERSION_MULTI_SSL -.br + libcurl was built with multiple SSL backends. For details, see \fIcurl_global_sslset(3)\fP. (Added in 7.56.0) .IP """NTLM""" \fIfeatures\fP mask bit: CURL_VERSION_NTLM -.br + supports HTTP NTLM (added in 7.10.6) .IP """NTLM_WB""" \fIfeatures\fP mask bit: CURL_VERSION_NTLM_WB -.br + libcurl was built with support for NTLM delegation to a winbind helper. (Added in 7.22.0) .IP """PSL""" \fIfeatures\fP mask bit: CURL_VERSION_PSL -.br + libcurl was built with support for Mozilla's Public Suffix List. This makes libcurl ignore cookies with a domain that is on the list. (Added in 7.47.0) .IP """SPNEGO""" \fIfeatures\fP mask bit: CURL_VERSION_SPNEGO -.br + libcurl was built with support for SPNEGO authentication (Simple and Protected GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) .IP """SSL""" \fIfeatures\fP mask bit: CURL_VERSION_SSL -.br + supports SSL (HTTPS/FTPS) (Added in 7.10) .IP """SSPI""" \fIfeatures\fP mask bit: CURL_VERSION_SSPI -.br + libcurl was built with support for SSPI. This is only available on Windows and makes libcurl use Windows-provided functions for Kerberos, NTLM, SPNEGO and Digest authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.13.2) .IP """threadsafe""" \fIfeatures\fP mask bit: CURL_VERSION_THREADSAFE -.br + libcurl was built with thread-safety support (Atomic or SRWLOCK) to protect curl initialization. (Added in 7.84.0) See \fIlibcurl-thread(3)\fP .IP """TLS-SRP""" \fIfeatures\fP mask bit: CURL_VERSION_TLSAUTH_SRP -.br + libcurl was built with support for TLS-SRP (in one or more of the built-in TLS backends). (Added in 7.21.4) .IP """TrackMemory""" \fIfeatures\fP mask bit: CURL_VERSION_CURLDEBUG -.br + libcurl was built with memory tracking debug capabilities. This is mainly of interest for libcurl hackers. (added in 7.19.6) .IP """Unicode""" \fIfeatures\fP mask bit: CURL_VERSION_UNICODE -.br + libcurl was built with Unicode support on Windows. This makes non-ASCII characters work in filenames and options passed to libcurl. (Added in 7.72.0) .IP """UnixSockets""" \fIfeatures\fP mask bit: CURL_VERSION_UNIX_SOCKETS -.br + libcurl was built with support for Unix domain sockets. (Added in 7.40.0) .IP """zstd""" \fIfeatures\fP mask bit: CURL_VERSION_ZSTD -.br + supports HTTP zstd content encoding using zstd library (Added in 7.72.0) .IP none \fIfeatures\fP mask bit: CURL_VERSION_CONV -.br + libcurl was built with support for character conversions, as provided by the CURLOPT_CONV_* callbacks. Always 0 since 7.82.0. (Added in 7.15.4) .IP none \fIfeatures\fP mask bit: CURL_VERSION_GSSNEGOTIATE -.br + supports HTTP GSS-Negotiate (added in 7.10.6, deprecated in 7.38.0) .IP none \fIfeatures\fP mask bit: CURL_VERSION_KERBEROS4 -.br + supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0. .RE diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index d312bd5deb..f8c9edf228 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -597,13 +597,13 @@ from doing a POST. It just makes it POST without any data to send! .SH "Converting from deprecated form API to MIME API" Four rules have to be respected in building the multi-part: -.br + - The easy handle must be created before building the multi-part. -.br + - The multi-part is always created by a call to curl_mime_init(handle). -.br + - Each part is created by a call to curl_mime_addpart(multipart). -.br + - When complete, the multi-part must be bound to the easy handle using \fICURLOPT_MIMEPOST(3)\fP instead of \fICURLOPT_HTTPPOST(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 index 0cea12d02e..edc2e6afd0 100644 --- a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 @@ -33,12 +33,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); .fi .SH DESCRIPTION Provides AWS V4 signature authentication on HTTP(S) header. -.PP + Pass a char * that is the collection of specific arguments are used for creating outgoing authentication headers. The format of the \fIparam\fP option is: .IP provider1[:provider2[:region[:service]]] -.IP provider1,\ provider2 +.IP "provider1, provider2" The providers arguments are used for generating some authentication parameters such as "Algorithm", "date", "request type" and "signed headers". .IP region @@ -47,16 +47,16 @@ It is extracted from the host name specified in the URL if omitted. .IP service The argument is a function provided by a cloud. It is extracted from the host name specified in the URL if omitted. -.PP + NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4. Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same as calling this with \fB"aws:amz"\fP in parameter. -.PP + Example with "Test:Try", when curl uses the algorithm, it generates \fB"TEST-HMAC-SHA256"\fP for "Algorithm", \fB"x-try-date"\fP and \fB"X-Try-Date"\fP for "date", \fB"test4_request"\fP for "request type", \fB"SignedHeaders=content-type;host;x-try-date"\fP for "signed headers" -.PP + If you use just "test", instead of "test:try", test is used for every generated string. .SH DEFAULT @@ -94,13 +94,13 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. This option overrides the other auth types you might have set in \fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth method special. This method cannot be combined with other auth types. -.PP + A sha256 checksum of the request payload is used as input to the signature calculation. For POST requests, this is a checksum of the provided \fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer. For requests like PUT, you can provide your own checksum in an HTTP header named \fBx-provider2-content-sha256\fP. -.PP + For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request if not already present. For s3 requests with unknown payload, this header takes the special value "UNSIGNED-PAYLOAD".