On Mon, Dec 29, 2008 at 6:00 AM, <curl-users-request_at_cool.haxx.se> wrote:
> Date: Sun, 28 Dec 2008 22:46:42 +0100 (CET)
> From: Daniel Stenberg <daniel_at_haxx.se>
> Subject: Re: man pages
> To: the curl tool <curl-users_at_cool.haxx.se>
> Message-ID: <alpine.LRH.2.00.0812282216150.19534_at_yvahk3.pbagnpgbe.fr>
> Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII
>
> 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.

what you've explained just now sounds good. if you don't want to be
that verbose, use

You should not use this option together with the CURLOPT_USERPWD option.

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

what you wrote makes sense to me, where the previous text is not
clear. I think it will fit in fine w/ the current docs...

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.

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

that's better! you can remove the "a" at the end so it reads "...use
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.

thanks! glad I can contribute something even tho I can't code.

I'd like to offer to review any changes to English text for future
releases in a diff, now that I've read thru all of it once. I'd do it
for other projects too that need it.

happy holidays,

-- 
(( Anthony Bryan ... Metalink [ http://www.metalinker.org ]
  )) Easier, More Reliable, Self Healing Downloads
-------------------------------------------------------------------
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