cut off the description to prevent people from using this!

docs/curl_formparse.3

@@ -2,7 +2,7 @@
 .\" nroff -man [file]
 .\" $Id$
 .\"
-.TH curl_formparse 3 "21 May 2001" "libcurl 7.7.4" "libcurl Manual"
+.TH curl_formparse 3 "17 Dec 2001" "libcurl 7.9.2" "libcurl Manual"
 .SH NAME
 curl_formparse - add a section to a multipart/formdata HTTP POST:
 deprecated (use curl_formadd instead)
@@ -13,75 +13,6 @@ deprecated (use curl_formadd instead)
 .BI "struct HttpPost ** " lastitem ");"
 .ad
 .SH DESCRIPTION
-curl_formparse() is used to append sections when building a multipart/formdata
+This has been removed deliberately. The \fBcurl_formadd\fP has been introduced
-HTTP POST (sometimes refered to as rfc1867-style posts). Append one section at
+to replace this function. Do not use this. Convert to the new function
-a time until you've added all the sections you want included and then you pass
+now. curl_formparse() will be removed from a future version of libcurl.
-the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP.
-\fIlastitem\fP is set after each call and on repeated invokes it should be
-left as set to allow repeated invokes to find the end of the list in a faster
-way.  \fIstring\fP must be a zero terminated string abiding to the syntax
-described in a section below
-
-The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to
-NULL in the first call to this function. All list-data will be allocated by
-the function itself. You must call \fIcurl_formfree\fP after the form post has
-been done to free the resources again.
-
-This function will copy all input data and keep its own version of it
-allocated until you call \fIcurl_formfree\fP. When you've passed the pointer
-to \fIcurl_easy_setopt\fP, you must not free the list until after you've
-called \fIcurl_easy_cleanup\fP for the curl handle.
-
-See example below.
-.SH "FORM PARSE STRINGS"
-The
-.I string 
-parameter must be using one of the following patterns. Note that the []
-letters should not be included in the real-life string.
-.TP 0.8i
-.B [name]=[contents]
-Add a form field named 'name' with the contents 'contents'. This is the
-typcial contents of the HTML tag <input type=text>.
-.TP
-.B [name]=@[filename]
-Add a form field named 'name' with the contents as read from the local file
-named 'filename'. This is the typcial contents of the HTML tag <input
-type=file>.
-.TP
-.B [name]=@[filename1,filename2,...]
-Add a form field named 'name' with the contents as read from the local files
-named 'filename1' and 'filename2'. This is identical to the upper, except that
-you get the contents of several files in one section.
-.TP
-.B [name]=@[filename];[type=<content-type>]
-Whenever you specify a file to read from, you can optionally specify the
-content-type as well. The content-type is passed to the server together with
-the contents of the file. curl_formparse() will guess content-type for a
-number of well-known extensions and otherwise it will set it to binary. You
-can override the internal decision by using this option.
-.TP
-.B [name]=@[filename1,filename2,...];[type=<content-type>]
-When you specify several files to read the contents from, you can set the
-content-type for all of them in the same way as with a single file.
-.PP
-.SH RETURN VALUE
-Returns non-zero if an error occurs.
-.SH EXAMPLE
-
- HttpPost* post = NULL;
- HttpPost* last = NULL;
-
- /* Add an image section */
- curl_formparse("picture=@my-face.jpg", &post, &last);
- /* Add a normal text section */
- curl_formparse("name=FooBar", &post, &last);
- /* Set the form info */
- curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
-
-.SH "SEE ALSO"
-.BR curl_easy_setopt "(3), "
-.BR curl_formadd "(3), "
-.BR curl_formfree "(3)
-.SH BUGS
-Surely there are some, you tell me!
-