docs: curl_mime_*.3 man page formatting edits

docs/libcurl/curl_mime_addpart.3

@@ -28,18 +28,16 @@ curl_mime_addpart - append a new empty part to a mime structure
 .BI "curl_mimepart * curl_mime_addpart(curl_mime * " mime ");"
 .ad
 .SH DESCRIPTION
-curl_mime_addpart() appends a new empty part to the given mime structure and
+\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given
-returns a handle to it.
+mime structure and returns a handle to it.  The returned part handle can
-The returned part can be subsequently filled using functions from the mime API.
+subsequently be populated using functions from the mime API.
 
 \fImime\fP is the handle of the mime structure in which the new part must be
 appended.
-
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
 A mime part structure handle, or NULL upon failure.
-
 .SH "SEE ALSO"
 .BR curl_mime_init "(3),"
 .BR curl_mime_name "(3),"

docs/libcurl/curl_mime_data.3

@@ -29,7 +29,7 @@ curl_mime_data - set a mime part's body data from memory
 .BI ", size_t " datasize ");"
 .ad
 .SH DESCRIPTION
-curl_mime_data() sets a mime part's body content from memory data.
+\fIcurl_mime_data(3)\fP sets a mime part's body content from memory data.
 
 \fIdata\fP points to the data bytes: those are copied to the part and their
 storage may safely be reused after call.
@@ -43,13 +43,13 @@ is retained. It is possible to unassign part's contents by setting
 \fIdata\fP to NULL.
 
 Setting very large data is memory consuming: one might consider using
-\fIcurl_mime_data_cb\fP() in such a case.
+\fIcurl_mime_data_cb(3)\fP in such a case.
-
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
 CURLE_OK or a CURL error code upon failure.
-
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_data_cb "(3)"
+.BR curl_mime_name "(3)"
+.BR curl_mime_type "(3)"

docs/libcurl/curl_mime_data_cb.3

@@ -38,20 +38,24 @@ void freefunc(void *arg);
 .BI "        curl_free_callback " freefunc ", void * " arg ");"
 .ad
 .SH DESCRIPTION
-curl_mime_data_cb() sets the data source of a mime part's body content from
+\fIcurl_mime_data_cb(3)\fP sets the data source of a mime part's body content
-a data read callback function.
+from a data read callback function.
 
 \fIpart\fP is the part's to assign contents to.
-\fIreadfunc\fP is a pointer to a data read callback function, with a
+
-signature as shown by the above prototype. It may not be set to NULL.
+\fIreadfunc\fP is a pointer to a data read callback function, with a signature
-\fIseekfunc\fP is a pointer to a seek callback function, with a
+as shown by the above prototype. It may not be set to NULL.
-signature as shown by the above prototype. This function will be used upon
+
-resending data (i.e.: after a redirect); this pointer may be set to NULL,
+\fIseekfunc\fP is a pointer to a seek callback function, with a signature as
-in which case a resend is not possible.
+shown by the above prototype. This function will be used upon resending data
+(i.e.: after a redirect); this pointer may be set to NULL, in which case a
+resend is not possible.
+
 \fIfreefunc\fP is a pointer to a user resource freeing callback function, with
-a signature as shown by the above prototype. If no resource is to be freed,
+a signature as shown by the above prototype. If no resource is to be freed, it
-it may safely be set to NULL. This function will be called upon mime
+may safely be set to NULL. This function will be called upon mime structure
-structure freeing.
+freeing.
+
 \fIarg\fP is a user defined argument to callback functions.
 
 The read callback function gets called by libcurl as soon as it needs to

docs/libcurl/curl_mime_filedata.3

@@ -29,17 +29,18 @@ curl_mime_filedata - set a mime part's body data from a file contents
 .BI " const char * " filename ");"
 .ad
 .SH DESCRIPTION
-curl_mime_filedata() sets a mime part's body content from the named file's
+\fIcurl_mime_filedata(3)\fP sets a mime part's body content from the named
-contents.
+file's contents.
 
 \fIpart\fP is the part's to assign contents to.
+
 \fIfilename\fP points to the nul-terminated file's path name. The pointer can
-be NULL to detach previous part contents settings.
+be NULL to detach previous part contents settings.  Filename storage can be
-Filename storage can be safely be reused after this call.
+safely be reused after this call.
 
 As a side effect, the part's remote file name is set to the base name of the
 given \fIfilename\fP if it is a valid named file. This can be undone or
-overriden by a subsequent call to \fIcurl_mime_filename\fP().
+overriden by a subsequent call to \fIcurl_mime_filename(3)\fP.
 
 Setting a part's contents twice is valid: only the value set by the last call
 is retained.

docs/libcurl/curl_mime_filename.3

@@ -29,10 +29,10 @@ curl_mime_filename - set a mime part's remote file name
 .BI "const char * " filename ");"
 .ad
 .SH DESCRIPTION
-curl_mime_filename() sets a mime part's remote file name. When remote file
+\fIcurl_mime_filename(3)\fP sets a mime part's remote file name. When remote
-name is set, content data is processed as a file, whatever is the part's
+file name is set, content data is processed as a file, whatever is the part's
-content source. A part's remote file name is transmitted to the server in
+content source. A part's remote file name is transmitted to the server in the
-the associated Content-Disposition generated header.
+associated Content-Disposition generated header.
 
 \fIpart\fP is the part's handle to assign the remote file name to.
 \fIfilename\fP points to the nul-terminated file name string; it may be set to
@@ -41,11 +41,10 @@ NULL to remove a previously attached remote file name.
 The remote file name string is copied into the part, thus the associated
 storage may safely be released or reused after call. Setting a part's file
 name twice is valid: only the value set by the last call is retained.
-
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
 CURLE_OK or a CURL error code upon failure.
-
 .SH "SEE ALSO"
-.BR curl_mime_addpart "(3)"
+.BR curl_mime_addpart "(3) "
+.BR curl_mime_filedata "(3) "

docs/libcurl/curl_mime_free.3

@@ -28,10 +28,10 @@ curl_mime_free - free a previously built mime structure
 .BI "void curl_mime_free(curl_mime *" mime);
 .ad
 .SH DESCRIPTION
-curl_mime_free() is used to clean up data previously built/appended with
+\fIcurl_mime_free(3)\fP is used to clean up data previously built/appended
-\fIcurl_mime_addpart(3)\fP and other mime-handling functions.
+with \fIcurl_mime_addpart(3)\fP and other mime-handling functions.  This must
-This must be called when the data has been used, which
+be called when the data has been used, which typically means after
-typically means after \fIcurl_easy_perform(3)\fP has been called.
+\fIcurl_easy_perform(3)\fP has been called.
 
 The handle to free is the one you passed to
 the \fICURLOPT_MIMEPOST(3)\fP option: attached subparts mime structures must

docs/libcurl/curl_mime_headers.3

@@ -29,22 +29,22 @@ curl_mime_headers - set a mime part's custom headers
 .BI "struct curl_slist * " headers ", int " take_ownership ");"
 .ad
 .SH DESCRIPTION
-curl_mime_headers() sets a mime part's custom headers.
+\fIcurl_mime_headers(3)\fP sets a mime part's custom headers.
 
 \fIpart\fP is the part's handle to assign the custom headers list to.
-\fIheaders\fP is the head of a list of custom headers; it may be set to
+
-NULL to remove a previously attached custom header list.
+\fIheaders\fP is the head of a list of custom headers; it may be set to NULL
+to remove a previously attached custom header list.
+
 \fItake_ownership\fP: when non-zero, causes the list to be freed upon
 replacement or mime structure deletion; in this case the list must not be
 freed explicitly.
 
 Setting a part's custom headers list twice is valid: only the value set by
 the last call is retained.
-
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
 CURLE_OK or a CURL error code upon failure.
-
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3)"

docs/libcurl/curl_mime_init.3

@@ -28,10 +28,11 @@ curl_mime_init - create a mime handle
 .BI "curl_mime * curl_mime_init(CURL * " easy_handle ");"
 .ad
 .SH DESCRIPTION
-curl_mime_init() creates a handle to a new empty mime structure intended to be
+\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure
-used with \fIeasy_handle\fP. This mime structure can be subsequently filled
+intended to be used with \fIeasy_handle\fP. This mime structure can be
-using the mime API, then attached to \fIeasy_handle\fP using option
+subsequently filled using the mime API, then attached to \fIeasy_handle\fP
-\fICURLOPT_MIMEPOST\fP within a \fIcurl_easy_setopt\fP() call.
+using option \fICURLOPT_MIMEPOST(3)\fP within a \fIcurl_easy_setopt(3)\fP
+call.
 
 Using a mime handle is the recommended way to post an HTTP form, format and 
 send a multi-part e-mail with SMTP or upload such an e-mail to an IMAP server.

docs/libcurl/curl_mime_name.3

@@ -29,24 +29,26 @@ curl_mime_name - set a mime part's name
 .BI ", size_t " namesize ");"
 .ad
 .SH DESCRIPTION
-curl_mime_name() sets a mime part's name. This is the way HTTP form fields are
+\fIcurl_mime_name(3)\fP sets a mime part's name. This is the way HTTP form
-named.
+fields are named.
 
 \fIname\fP points to the name byte string; the string may contain nul bytes
 unless \fInamesize\fP is -1.
+
 \fInamesize\fP is the name length: it can be set to \fICURL_ZERO_TERMINATED\fP
 to indicate \fIname\fP is a nul-terminated string.
+
 \fIpart\fP is the part's handle to assign a name to.
 
-The name string is copied into the part, thus the associated storage may safely
+The name string is copied into the part, thus the associated storage may
-be released or reused after call. Setting a part's name twice is valid:
+safely be released or reused after call. Setting a part's name twice is valid:
-only the value set by the last call is retained. It is possible to "unname"
+only the value set by the last call is retained. It is possible to "unname" a
-a part by setting \fIname\fP to NULL.
+part by setting \fIname\fP to NULL.
-
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
 CURLE_OK or a CURL error code upon failure.
-
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3)"
+.BR curl_mime_data "(3)"
+.BR curl_mime_type "(3)"

docs/libcurl/curl_mime_subparts.3

@@ -29,24 +29,23 @@ curl_mime_subparts - set subparts of a multipart mime part
 .BI "curl_mime * " subparts ");"
 .ad
 .SH DESCRIPTION
-curl_mime_subparts() sets a multipart mime part's content from a mime
+\fIcurl_mime_subparts(3)\fP sets a multipart mime part's content from a mime
 structure.
 
 \fIpart\fP is a handle to the multipart part.
+
 \fIsubparts\fP is a mime structure handle holding the subparts. After
 \fIcurl_mime_subparts\fP succeeds, the mime structure handle belongs to the
-multipart part and must not be freed explicitly. It may however be updated
+multipart part and must not be freed explicitly. It may however be updated by
-by subsequent calls to mime API functions.
+subsequent calls to mime API functions.
 
 Setting a part's contents twice is valid: only the value set by the last call
 is retained. It is possible to unassign previous part's contents by setting
 \fIsubparts\fP to NULL.
-
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
 CURLE_OK or a CURL error code upon failure.
-
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_init "(3)"

docs/libcurl/curl_mime_type.3

@@ -29,15 +29,16 @@ curl_mime_type - set a mime part's content type
 .BI "const char * " mimetype ");"
 .ad
 .SH DESCRIPTION
-curl_mime_type() sets a mime part's content type.
+\fIcurl_mime_type(3)\fP sets a mime part's content type.
 
 \fIpart\fP is the part's handle to assign the content type to.
+
 \fImimetype\fP points to the nul-terminated file mime type string; it may be
 set to NULL to remove a previously attached mime type.
 
-The mime type string is copied into the part, thus the associated
+The mime type string is copied into the part, thus the associated storage may
-storage may safely be released or reused after call. Setting a part's type
+safely be released or reused after call. Setting a part's type twice is valid:
-twice is valid: only the value set by the last call is retained.
+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:
@@ -52,11 +53,11 @@ extension, or application/octet-stream by default.
 - For a multipart part, multipart/mixed.
 .br
 - text/plain in other cases.
-
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
 CURLE_OK or a CURL error code upon failure.
-
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3)"
+.BR curl_mime_name "(3)"
+.BR curl_mime_data "(3)"

docs/libcurl/opts/CURLOPT_MIMEPOST.3

@@ -31,13 +31,13 @@ curl_mime *mime;
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIMEPOST, mime);
 .SH DESCRIPTION
-Pass a mime handle previously obtained from \fIcurl_mime_init()\fP.
+Pass a mime handle previously obtained from \fIcurl_mime_init(3)\fP.
 
 This setting is supported by the HTTP protocol to post forms and by the
 SMTP and IMAP protocols to provide the e-mail data to send/upload.
 
-This option is the preferred way of posting an HTTP form, replacing
+This option is the preferred way of posting an HTTP form, replacing and
-and extending the deprecated \fICURLOPT_HTTPPOST\fP option.
+extending the deprecated \fICURLOPT_HTTPPOST(3)\fP option.
 .SH PROTOCOLS
 HTTP, SMTP, IMAP.
 .SH AVAILABILITY