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
2024-01-17 14:27:16 +01:00 · 2024-01-17 14:27:16 +01:00 · 6b930f1bfb
commit 6b930f1bfb
parent 2462c9d594
10 changed files with 93 additions and 119 deletions
--- 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
--- 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.
--- 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
--- 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
--- 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
--- 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";
--- 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.
--- 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

--- 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.

--- 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".