On Thursday, November 10, 2011 10:27:46 Jacob Carlborg wrote:
> On 2011-11-10 03:57, Andrei Alexandrescu wrote:
> > On 11/9/11 6:24 PM, Walter Bright wrote:
> >> 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)
> > 
> > That should be XREF actually.
> > 
> > Andrei
> 
> I would be nice to have some documentation of these macros that are used through out Phobos.

Look at the bottom std.ddoc in the d-programming-language.org repository - though it may be a good idea to actually put them on a page somewhere. Still, since it really only affects Phobos devs, it's not quite as critical as a lot of other documentation.

- Jonathan M Davis

On Thursday, November 10, 2011 10:30:15 Jacob Carlborg wrote:
> On 2011-11-10 04:39, Jonathan M Davis wrote:
> > On Wednesday, November 09, 2011 18:38:48 Walter Bright wrote:
> >> On 11/9/2011 5:13 PM, Jonathan M Davis wrote:
> >>> On Wednesday, November 09, 2011 16:58 bearophile wrote:
> >>>> Is the (just) Windows compiled version present in the DMD zip? I
> >>>> don't
> >>>> remember what was the decision on this (I'd like it to be
> >>>> present).
> >>> 
> >>> Currently, no version of libcurl is included in the zip file. I
> >>> don't
> >>> believe that there has been any decision on what to do about it. But
> >>> if
> >>> we do end up including it, then that's one more reason to consider
> >>> splitting up the zip file by OS.
> >> 
> >> I don't want us to get caught in the rat race of "the version that
> >> comes
> >> with the compiler is out of date". libcurl has its own development
> >> cycle, and dmd should not be slaved to that.
> > 
> > Yeah. That's one reason why I'm not a fan of the idea of distributing it with dmd. So, it won't hurt my feelings any if it never gets put into the zip file. However, we're going to have to make it clear in the documentation on how to get your hands on an appropriate libcurl library (especially since any version of it that you're likely to find online would be in the wrong library format).
> > 
> > - Jonathan M Davis
> 
> What about distributing it from the dpl page but not in the dmd zip?

We definitely need to make it relatively easy to get the library, and I have no problem with us providing a separate download for it. But Phobos isn't tied to a particular version of libcurl, so if we provide it, we need to be providing it as a convenience rather than saying that this is the version to use. And really, we need better instructions in general about how to get a 3rd party C library to work with D code on Windows. It's obvious a bit of an ordeal for anyone who tries.

- Jonathan M Davis

On Thursday, November 10, 2011 10:58:14 Jacob Carlborg wrote:
> On 2011-11-10 09:50, Jonathan M Davis wrote:
> > On Thursday, November 10, 2011 08:27:53 Jacob Carlborg wrote:
> >> What is the actual Phobos guideline in naming things that are keywords
> >> in D. I'm thinking about Method.del, shouldn't it be Method.delete_ or
> >> something similar, don't know what the guidelines say in this case.
> >> BTW,
> >> I would really like to have more official guidelines somewhere at the
> >> dpl page.
> > 
> > Thus far, we've taken the approach of tacking an underscore on the end (so delete would be delete_), but we haven't made any kind of official decision on it. However, if it's reasonable to use a different word entirely, then that's generally better. It's stuff like std.traits.FunctionAttribute which pretty much _has_ to match the keyword where we've appended the underscore (e.g. pure_ and nothrow_).
> > 
> > - Jonathan M Davis
> 
> I agree, but this case it's not a completely different word, it's a shorting of the word.
> 
> I just like that there should be something more official when these things pop up.

Well, for better or worse, we don't have an official policy on it. In general, I think that the tact is to try and rename the item so that it doesn't pose a problem, but that's not always possible (hence FunctionAttribute.pure_). In this case, since it comes from something else, it looks like it really should be some version of delete. However, whereas FunctionAttribute pretty much _had_ to be as close to the keyword as possible since it represented the keyword, that's not the case here, and given how ugly it is to tack the _ on, del seems like a reasonable solution.

In any case, if we want something official, we'd have to discuss it, and we generally have a hard time coming to any kind of consensus on stuff like that. So, I don't generally try unless it seems particularly important.

- Jonathan M Davis

On 10/11/11 08.32, Jacob Carlborg wrote:
> On 2011-11-09 21:53, Jonas Drewsen wrote:
>> Hi,
>>
>> So after the last review of the etc.curl there were some requests for
>> making it simpler.
<snip>

> BTW, why is this "etc.culr" and not "std.curl".

I think Andrei mentioned that he wanted it to go to std.curl. Another option would be std.net.curl.

Anyone have an opinion about this?

/Jonas

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

On 10/11/11 01.25, Walter Bright wrote:
> On 11/9/2011 4:24 PM, 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.
>
> I forgot to mention: I like the cheat sheet a lot.

Me to... stole it from std.algorithm :)

/Jonas

On 10/11/11 08.27, Jacob Carlborg wrote:
> On 2011-11-09 21:53, Jonas Drewsen wrote:
>> Hi,
>>
>> So after the last review of the etc.curl there were some requests for
>> making it simpler.
<snip>

> What is the actual Phobos guideline in naming things that are keywords
> in D. I'm thinking about Method.del, shouldn't it be Method.delete_ or
> something similar, don't know what the guidelines say in this case. BTW,
> I would really like to have more official guidelines somewhere at the
> dpl page.

Yes.. it would be nice with a standard for this. I have the same problem with CurlOption.intrface which it ugly I think. But so is CurlOption.interface_

/Jonas

On 2011-11-10 11:12, Jonathan M Davis wrote:
> On Thursday, November 10, 2011 10:27:46 Jacob Carlborg wrote:
>> On 2011-11-10 03:57, Andrei Alexandrescu wrote:
>>> On 11/9/11 6:24 PM, Walter Bright wrote:
>>>> 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)
>>>
>>> That should be XREF actually.
>>>
>>> Andrei
>>
>> I would be nice to have some documentation of these macros that are used
>> through out Phobos.
>
> Look at the bottom std.ddoc in the d-programming-language.org repository -
> though it may be a good idea to actually put them on a page somewhere. Still,
> since it really only affects Phobos devs, it's not quite as critical as a lot
> of other documentation.
>
> - Jonathan M Davis

I would not consider that documentation but it's good to know where I can find them. They could be put on a "contribute" page at d-p-l.org. I have thought several times that there should be a "contribute" page at d-p-l.org that contains information like this.

-- 
/Jacob Carlborg

On 2011-11-10 11:21, Jonathan M Davis wrote:
> Well, for better or worse, we don't have an official policy on it. In general, I
> think that the tact is to try and rename the item so that it doesn't pose a
> problem, but that's not always possible (hence FunctionAttribute.pure_). In
> this case, since it comes from something else, it looks like it really should
> be some version of delete. However, whereas FunctionAttribute pretty much
> _had_ to be as close to the keyword as possible since it represented the
> keyword, that's not the case here, and given how ugly it is to tack the _ on,
> del seems like a reasonable solution.
>
> In any case, if we want something official, we'd have to discuss it, and we
> generally have a hard time coming to any kind of consensus on stuff like that.
> So, I don't generally try unless it seems particularly important.
>
> - Jonathan M Davis

I think we should write down, somewhere, what we have, what we have agreed on unofficially. It may not be complete and not contain details for everything but it would at least be something. Instead of having to explain this every time we get a new contributor to Phobos or one has to try to find this information in the newsgroup.

-- 
/Jacob Carlborg

On 2011-11-10 13:14, Jonas Drewsen wrote:
> On 10/11/11 08.32, Jacob Carlborg wrote:
>> On 2011-11-09 21:53, Jonas Drewsen wrote:
>>> Hi,
>>>
>>> So after the last review of the etc.curl there were some requests for
>>> making it simpler.
> <snip>
>
>> BTW, why is this "etc.culr" and not "std.curl".
>
> I think Andrei mentioned that he wanted it to go to std.curl. Another
> option would be std.net.curl.
>
> Anyone have an opinion about this?
>
> /Jonas

I forgot about the std.net package. I think that would be a good place.

-- 
/Jacob Carlborg