RFC curl

[Walter Bright]

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.

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)