cURL / Mailing Lists / curl-users / Single Mail

curl-users

Re: man curl review

From: Anthony Bryan <anthonybryan_at_gmail.com>
Date: Tue, 7 Aug 2012 13:39:22 -0400

On Tue, Aug 7, 2012 at 6:00 AM, <curl-users-request_at_cool.haxx.se> wrote:
> Date: Mon, 6 Aug 2012 13:50:11 +0200 (CEST)
> From: Daniel Stenberg <daniel_at_haxx.se>
> To: the curl tool <curl-users_at_cool.haxx.se>
> Subject: Re: man curl review
> Message-ID: <alpine.DEB.2.00.1208061337000.5752_at_tvnag.unkk.fr>
> Content-Type: text/plain; charset="utf-8"; Format="flowed"
>
> On Mon, 6 Aug 2012, Anthony Bryan wrote:
>
> Thanks for the work on this Anthony!
>
>> versions (which it is if it is IPv6-capable), this option tells
>> libcurl to resolve names to IPv6 addresses only. default sta?
>> tistics.
>>
>> ---should "default statistics." be at the end there?
>
> No. And I have no idea how it got there! =)
>
>> If this option is used several times, the last one will be used. IP
>> "--data-ascii <data>" See \fI-d, --data\fP.
>>
>> ---looks like this should be like this so it formats correctly when the man
>> page is generated.
>>
>> If this option is used several times, the last one will be used.
>>
>> .IP "--data-ascii <data>" See \fI-d, --data\fP.
>
> Yeps!
>
>> --digest
>> (HTTP) Enables HTTP Digest authentication. This is a authentica?
>> tion that prevents the password from being sent over the wire in
>> ---"This is an authentication..." (method? scheme?)
>
> I would say "method", but RFC2617 says "scheme" so I figure that makes the
> most sense.
>
>> If this option is used several times, the following occurrences
>> make no difference.
>>
>> ---"If this option is used several times, only the first one is used." ?
>
> Yes, we should use the same way of phrasing for all the options that work the
> same way.

it looks like these are the variations. I didn't change all of them
because some seem more specific than others, so I will leave that to
you to decide if you want them like that or changed.

If this option is used several times, only the first one is used.

If this option is used several times, the last one will override the others.

If this option is used twice, the second will override the previous use.

If this option is used several times, the last one will be used.

If this option is used multiple times, the last occurrence sets the amount.

>> "an FTP" -> "a FTP"
>
> I believe I was taught in school that the initial sound was the important part
> when considering 'a' vs 'an'. So since we say eff tee pee it begins with a
> vowel and hence it should be 'an'.

right, I always forget that one :)

>> --metalink & --include should be underlined
>
> Yes. For that to happen they should be written \fI--metalink\fP etc. That
> makes it fine nroff syntax for the man page and roffit will convert that to a
> link in the html version of the document. Every time we mention options in the
> descriptions we should put them within \fI \fP pairs.

I changed this in a few other places, please check to make sure it is correct.

>> some commands show which protocol they concern at the beginning (HTTP) etc,
>> while others state in prose at the end ("This option is only for SCP and
>> SFTP transfers."):
>
> ...
>
>> could we do this a uniform way? I like the protocol at the beginning myself.
>
> I like in the beginning myself too. It would be really nice to have this
> cleaned up, yes.

ok, I added this in all the spots I could see to make it consistent.

should these be updated?

.TH curl 1 "16 February 2012" "Curl 7.25.0" "Curl Manual"

.TH curl-config 1 "25 Oct 2007" "Curl 7.17.1" "curl-config manual"

-- 
(( Anthony Bryan ... Metalink [ http://www.metalinker.org ]
  )) Easier, More Reliable, Self Healing Downloads


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

Received on 2012-08-07