RFC curl

[Jonas Drewsen]

On 10/11/11 01.24, Walter Bright wrote:
> On 11/9/2011 12:53 PM, Jonas Drewsen wrote:
>> Before sending it for official review again I would really like some
>> comments on
>> the new API and if you think it is better or worse etc.
>>
>> http://freeze.steamwinter.com/D/web/phobos/etc_curl.html
>
> Thank you so much for doing this. I think it's a nice piece of work.

Thank you.

It seems that people like this API better. I'll head on to implement the 
last common HTTP request types (head() etc.), polish and fix the stuff 
you've mentioned below then.

/Jonas

> Some nitpicky comments:
>
> * libcurl should be a link to where people can read up on what it is.
> I suggest http://curl.haxx.se/libcurl
> Point out that the user will need libcurl installed on their system in
> order to use etc.curl.
>
> * Need a brief statement on why a D programmer should prefer using
> etc.curl rather than directly use libcurl.
>
> * "ranges" should be a link to what a range is
>
> * examples should include
>
> import etc.curl;
>
> and any other needed, like std.stdio. In fact, they should be cut &
> paste complete examples that are compilable and runnable.
>
> * Keep comment lines under 40 characters; use multiple lines for longer
> comments. (This is so things format better for small screens.) Try to
> format code so it doesn't need more than 40 lines. I tend to indent by
> only two spaces in documentation which helps.
>
> * Remove all instances of the word "you". For example,
>
> "If you need more control than the low high level functions provide,
> you'll have to use the low level API:"
>
> rewrite as:
>
> "For more control than the low high level functions provide, use the low
> level API:"
>
> Note how much simpler and direct it is. "You" is almost always an
> unnecessary filler word, and frankly has no place in a reference work.
>
> * For the same reason, get rid of "we":
>
> "First, we create an instance" => "First, create an instance"
> "We then set" => "Then set"
>
> * derivate => derived
>
> * "Connection type used when the url should be used to auto detect
> protocol"
> .. I have no idea what this sentence means.
>
> * "HTTP/FTP upload from local file system." => Upload file from local
> file system using the HTTP or FTP protocol."
> And which protocol would be used?
>
> * "A string with the content of the resource pointer to by the url"
> Missing period. Grammar problems, how about:
> "A string containing the content of the resource pointed to by the url."
>
> Most of these apply to the rest of the documentation.
>
> Also, need more examples.
>
> I tend to like references to things in other modules to be hyperlinks.
> For example, writeln should be $(LINK2
> http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
> writeln)
>
>
>