On Sun, 28 Dec 2008, Anthony Bryan wrote:

> from curl_easy_setopt
>
> Note the CURLOPT_USERNAME option is an alternative way to set the user name.
> There is no meaning to use it together with the CURLOPT_USERPWD option.
>
> what does this 2nd sentence mean?

They both pass on a user name to libcurl (to use in authentication), but
CURLOPT_USERPWD also passes on a password. Thus you should not use both of
these, just one of them. And in fact CURLOPT_USERNAME (and CURLOPT_PASSWORD)
are meant to replace CURLOPT_USERPWD...

But yeah, the phrasing of that section currently is rather strange.

> Note that libcurl will still act and assume the keyword it would use
> if you didn't set your custom
> one is the one in use and it will act according to that.
>
> a better way to phrase this?

Oh, that's so badly phrased I could hardly understand what it means! Let me
explain what's being tried to get explained there:

When speaking HTTP, libcurl acts according to what kind of request it does.
POST, PUT, GET and HEAD all imply some particular behaviors in various
aspects. They don't differ a lot, but there are some subtleties between them.
So, this text above tries to say tat when you change the request method by
seting CURLOPT_CUSTOMREQUEST to something, you don't actually change how
libcurl behaves or acts in regards to the particular request method, it will
only change the actual string sent in the request.

For example: if you tell libcurl to do a HEAD request, but then change the
request to a "GET" with CURLOPT_CUSTOMREQUEST you'll still see libcurl act as
if it sent a HEAD even when it does send a GET...

Now we only need to put that in a sensible way in the docs!

> but colons are normally used, \!, \- and \+ can be used as operators. shows
> up in the PDF as but colons are normally used, , ?and + can be used as
> operators.

Oh! I've tried to escape them better now so they should appear correctly now.

> CURLOPT_KRBLEVEL
> Pass a char * as parameter. Set the kerberos security level for FTP; this
> also enables kerberos awareness. This is a string, 'clear', 'safe', of
> these, 'private' will be used.
>
> I don't understand the last sentence...should it be:
> This is a string. 'clear', 'safe', or 'private' can be used.

The ouput is broken due to a malformat error in the nroff file. I've corrected
it now. That last sentence should read:

   This is a string, 'clear', 'safe', 'confidential' or 'private'. If the
   string is set but doesn't match one of these, 'private' will be used.

> You can control what data your function get in the forth argument by
> setting another property:
> curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct);
>
> is this a typo of 'fourth' or do you mean "...in the following
> argument ? also, should be "...function gets..."

Indeed two errors. I've now changed it to:

   You can control what data your callback function gets in the fourth argument
   by setting another property:

> Unfortunately, c-ares does not yet fully support IPv6. On
> some platforms, libcurl simply will not
> function properly multi-threaded unless this option is set.
>
> is that still accurate? from the c-ares page it seems to suggest IPv6
> support, but maybe not fully supported?

It's a question of definition, but I think I'll just cut out that from that
section.

> Set header file to read cookies from
> with CURLOPT_COOKIEFILE.
>
> Set the header file to read cookies from
> with CURLOPT_COOKIEFILE.
> ?

Yes!

> Note that the file you specify to CURLOPT_COOKIEFILE doesn't have to exist
> to enable the parser, so a common way to just enable the parser and not read
> able might be to use a file name you know doesn't exist.
>
> I don't understand the end - "and not read able might be to use a file
> name you know doesn't exist."

It looks completely broken. I changed it to:

   Note that the file you specify to CURLOPT_COOKIEFILE doesn't have to exist
   to enable the parser, so a common way to just enable the parser and not read
   any cookies is to use a the name of a file you know doesn't exist.

> HTTP Digest authentication allows this too, but isn't supported
> by libcurl as of this writing.
>
> does libcurl now support digest? if yes, should this be removed?

It should indeed. I rewrote that particular section to reflect the current
status.

Thanks a lot! I value getting the documentation clearer and easier to read.
Getting someone to actually reading through it and trying to decipher the
explanations is a really good way to improve.

I'll take care of the patch too asap.

-- 
  / daniel.haxx.se
-------------------------------------------------------------------
List admin: http://cool.haxx.se/cgi-bin/mailman/listinfo/curl-users
FAQ:        http://curl.haxx.se/docs/faq.html
Etiquette:  http://curl.haxx.se/mail/etiquette.html