[GNUnet-SVN] [gnurl] 137/256: docs: curl_mime_*.3 man page formatting edits

[gnunet]

This is an automated email from the git hooks/post-receive script.

ng0 pushed a commit to branch master
in repository gnurl.

commit 2e4074c953e96cadc3182454fd437f9a348e37ce
Author: Daniel Stenberg <address@hidden>
AuthorDate: Mon Sep 4 09:20:24 2017 +0200

    docs: curl_mime_*.3 man page formatting edits
---
 docs/libcurl/curl_mime_addpart.3     |  8 +++-----
 docs/libcurl/curl_mime_data.3        |  8 ++++----
 docs/libcurl/curl_mime_data_cb.3     | 26 +++++++++++++++-----------
 docs/libcurl/curl_mime_filedata.3    | 11 ++++++-----
 docs/libcurl/curl_mime_filename.3    | 13 ++++++-------
 docs/libcurl/curl_mime_free.3        |  8 ++++----
 docs/libcurl/curl_mime_headers.3     | 10 +++++-----
 docs/libcurl/curl_mime_init.3        |  9 +++++----
 docs/libcurl/curl_mime_name.3        | 18 ++++++++++--------
 docs/libcurl/curl_mime_subparts.3    |  9 ++++-----
 docs/libcurl/curl_mime_type.3        | 13 +++++++------
 docs/libcurl/opts/CURLOPT_MIMEPOST.3 |  6 +++---
 12 files changed, 72 insertions(+), 67 deletions(-)

diff --git a/docs/libcurl/curl_mime_addpart.3 b/docs/libcurl/curl_mime_addpart.3
index 4a86f3813..7bdd43d72 100644
--- a/docs/libcurl/curl_mime_addpart.3
+++ b/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
-returns a handle to it.
-The returned part can be subsequently filled using functions from the mime API.
+\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given
+mime structure and returns a handle to it.  The returned part handle can
+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),"
diff --git a/docs/libcurl/curl_mime_data.3 b/docs/libcurl/curl_mime_data.3
index 85aee65e4..c458f2d38 100644
--- a/docs/libcurl/curl_mime_data.3
+++ b/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)"
diff --git a/docs/libcurl/curl_mime_data_cb.3 b/docs/libcurl/curl_mime_data_cb.3
index 64e5c7dc0..d0a0c14b1 100644
--- a/docs/libcurl/curl_mime_data_cb.3
+++ b/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
-a data read callback function.
+\fIcurl_mime_data_cb(3)\fP sets the data source of a mime part's body content
+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.
-\fIseekfunc\fP is a pointer to a seek callback function, with a
-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,
-in which case a resend is not possible.
+
+\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.
+
+\fIseekfunc\fP is a pointer to a seek callback function, with a 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, 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,
-it may safely be set to NULL. This function will be called upon mime
-structure freeing.
+a signature as shown by the above prototype. If no resource is to be freed, it
+may safely be set to NULL. This function will be called upon mime structure
+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
diff --git a/docs/libcurl/curl_mime_filedata.3 
b/docs/libcurl/curl_mime_filedata.3
index 71562edd0..e70e3b269 100644
--- a/docs/libcurl/curl_mime_filedata.3
+++ b/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
-contents.
+\fIcurl_mime_filedata(3)\fP sets a mime part's body content from the named
+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.
-Filename storage can be safely be reused after this call.
+be NULL to detach previous part contents settings.  Filename storage can be
+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.
diff --git a/docs/libcurl/curl_mime_filename.3 
b/docs/libcurl/curl_mime_filename.3
index 4c09402aa..db4482cdd 100644
--- a/docs/libcurl/curl_mime_filename.3
+++ b/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
-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
-the associated Content-Disposition generated header.
+\fIcurl_mime_filename(3)\fP sets a mime part's remote file name. When remote
+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 the
+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) "
diff --git a/docs/libcurl/curl_mime_free.3 b/docs/libcurl/curl_mime_free.3
index 87fea127b..9394b5748 100644
--- a/docs/libcurl/curl_mime_free.3
+++ b/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_addpart(3)\fP and other mime-handling functions.
-This must be called when the data has been used, which
-typically means after \fIcurl_easy_perform(3)\fP has been called.
+\fIcurl_mime_free(3)\fP is used to clean up data previously built/appended
+with \fIcurl_mime_addpart(3)\fP and other mime-handling functions.  This must
+be called when the data has been used, which typically means after
+\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
diff --git a/docs/libcurl/curl_mime_headers.3 b/docs/libcurl/curl_mime_headers.3
index 368c4d26c..34e623ae0 100644
--- a/docs/libcurl/curl_mime_headers.3
+++ b/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)"
diff --git a/docs/libcurl/curl_mime_init.3 b/docs/libcurl/curl_mime_init.3
index 601123c41..031c62b65 100644
--- a/docs/libcurl/curl_mime_init.3
+++ b/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
-used with \fIeasy_handle\fP. This mime structure can be subsequently filled
-using the mime API, then attached to \fIeasy_handle\fP using option
-\fICURLOPT_MIMEPOST\fP within a \fIcurl_easy_setopt\fP() call.
+\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure
+intended to be used with \fIeasy_handle\fP. This mime structure can be
+subsequently filled using the mime API, then attached to \fIeasy_handle\fP
+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.
diff --git a/docs/libcurl/curl_mime_name.3 b/docs/libcurl/curl_mime_name.3
index 25b4b35c6..71c9d8a1e 100644
--- a/docs/libcurl/curl_mime_name.3
+++ b/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
-named.
+\fIcurl_mime_name(3)\fP sets a mime part's name. This is the way HTTP form
+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
-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"
-a part by setting \fIname\fP to NULL.
+\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 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" a
+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)"
diff --git a/docs/libcurl/curl_mime_subparts.3 
b/docs/libcurl/curl_mime_subparts.3
index 3c607c586..13d34c361 100644
--- a/docs/libcurl/curl_mime_subparts.3
+++ b/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
-by subsequent calls to mime API functions.
+multipart part and must not be freed explicitly. It may however be updated by
+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)"
diff --git a/docs/libcurl/curl_mime_type.3 b/docs/libcurl/curl_mime_type.3
index 0c6cd3d6b..6907b9462 100644
--- a/docs/libcurl/curl_mime_type.3
+++ b/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
-storage may safely be released or reused after call. Setting a part's type
-twice is valid: only the value set by the last call is retained.
+The mime type string is copied into the part, thus the associated storage may
+safely be released or reused after call. Setting a part's type twice 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:
@@ -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)"
diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 
b/docs/libcurl/opts/CURLOPT_MIMEPOST.3
index a3a964f7f..dd64c4b17 100644
--- a/docs/libcurl/opts/CURLOPT_MIMEPOST.3
+++ b/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
-and extending the deprecated \fICURLOPT_HTTPPOST\fP option.
+This option is the preferred way of posting an HTTP form, replacing and
+extending the deprecated \fICURLOPT_HTTPPOST(3)\fP option.
 .SH PROTOCOLS
 HTTP, SMTP, IMAP.
 .SH AVAILABILITY

-- 
To stop receiving notification emails like this one, please contact
address@hidden