On Sun, Jun 5, 2016 at 9:35 AM, Laeeth Isharc via Digitalmars-d < digitalmars-d@puremagic.com> wrote:


> PyD is not a recent project.  Nor is LuaD.  Or bachmeier's work on R integration.
>

I've learned about the last one only from this thread, and the first two are listed only on http://wiki.dlang.org/Scripting_Libraries, thus I draw the conclusion that's how they are used most often.


> PyD is only barely alive
>>
> Really?  You have submitted pull requests and nobody has looked at them ? Seemed alive enough to me when I looked a few months back.  It's normal activity diminishes as a project reaches maturity.


You are right in that it's well maintained. I say 'barely' because for such kind of project I'd expect to see at least one user per each platform (Linux/OS X/Win), and I couldn't find that many. I ran a global search 'pyd std.range' on Github to get an idea of usage, and the outcome was rather disappointing for a mature project. I'm not a Win user so I can't help on this one.


> What a great opportunity to give something back!  Why not sketch out a vision for what this should look like, as John has done with dlangscience.


I'm afraid vision is also not going to help a lot, but here you go:

- LDC starts to provide libphobos2.a compiled with -fPIC
- PyD:
1) Links druntime dynamically and Phobos statically (with -Bsymbolic to
avoid symbol clashes between different Phobos versions)
2) Prepares a tiny libdruntime.so wrapper as a Python package, such that
'import druntime' in Python code initializes D runtime; all PyD packages
start to use this import.
3) Someone should help to sort out multithreading-related gotchas, if any
crop up
- D Language Foundation registers an official account on PyPI and publishes
the aforementioned package
- Finally, someone makes a useful PyD-based extension, publishes it, makes
sure his colleagues can use it with a single `pip install`, and puts a link
to reddit/hackernews


> Yes it has a unique advantage.  But it isn't realistic to expect others to do the work for you at this stage in the development of the ecosystem...


Well, it's not for me, I'm mostly out already, back to C++14/Python, after careful weighing of offerings w.r.t. infrastructure/pain of coding. The ideal people for these kind of tasks are students, imho. I've read on this forum about some magic place where D is being taught at a university, that's where I'd try to get an influx from.

As someone who recently tried D and dropped it to learn Python I can tell you, tooling was not an issue for me. I worked on a windows computer (which it seems a lot of this community are linux users based on the examples I see in the documentation...very *nix type examples) I will say I had dmd + codeblocks up and running and a hello world programming printing to the console in < 20 minutes.

D's major issue is it doesn't have much of a presence on sites like stackoverflow (or at least they don't appear to show up well in my google searches) and the documentation google does give me links to are poorly done. Two main issues I saw? Broken links and poor examples. Also occasionally I get pages that look like a different a style from google searches than the main documentation pages, which makes me feel one is outdated. I ended up actually just going to dlang.org itself to be sure...

But I should probably show some examples, because this post is meant to be productive not just critical.

Looking at the std.algorithm module page we get a description of functions that...well aren't really descriptions. For instance:

clamp	clamp(1, 3, 6) returns 3. clamp(4, 3, 6) returns 4.

Yeah...that does not explain anything. Definition writing 101 tells you to never use the word you are trying to define in the sentence defining it. In fact, most of the descriptions for the functions in std.algorithm should probably come with better descriptions. D doesn't offer a lot of return on investment for learning it, so you could at least make it easy to learn...

isPermutation	isPermutation([1, 2], [2, 1]) returns true.

^^^ How is that helpful? BTW, I'm getting this from this page:

https://dlang.org/library/std/algorithm/comparison.html

Now, if I click on each function I get a little bit better of an explanation (in some cases), but why have a useless description? It serves nothing and just distracts. You might as well as not have a description column on std.algorithm, and just provide links.

The other beef I see, is that examples for functions seem like they are just ripped from random unittests and frequently reference other standard library calls without context of what they are doing.

For example readText:

https://dlang.org/library/std/file/read_text.html

It provides an example of this:

import std.string;
write("someUniqueFilename", "abc\n");
scope(exit)
{
    assert(exists("someUniqueFilename"));
    remove("someUniqueFilename");
}

enforce(chomp(readText("someUniqueFilename")) == "abc");

So reading it, it looks like we crate a file with "abc" in it, then do some scope(exit) thingy, then assert the file exists, then remove it? Odd...

Then we move down and it looks like "after" we delete it we read the file using "readText" and make sure it's contents are equal to what we wrote to the file? So first thing I had to do is look up what the hell scope(exit) was doing and found that it gets called when the scope gets killed not inline where it was. Ok fine. That sounds useful. So by the time we get to the readText line we still have a file. But what the hell is chomp? Do I need chomp to use readText? Turns out...no...I read a file literally by doing auto text = readText(fileName). So yeah...

To understand this example I had to a lot more work than I should of had to just understand how to use readText correctly, and it turns out I didn't need to do 90% of the code for my purposes, which means the rest is really more of just a distraction. Sure, I learned what scope(exit) does and what chomp did, but I didn't need them.

On 06/05/2016 02:58 PM, David wrote:
> D's major issue is it doesn't have much of a presence on sites like
> stackoverflow (or at least they don't appear to show up well in my
> google searches) and the documentation google does give me links to are
> poorly done. Two main issues I saw? Broken links and poor examples. Also
> occasionally I get pages that look like a different a style from google
> searches than the main documentation pages, which makes me feel one is
> outdated. I ended up actually just going to dlang.org itself to be sure...

The different style pages are most probably dlang.org/phobos/ pages and dlang.org/library/ pages. They are built from the same source, so they should contain the same information. Neither of them should be outdated.

We're actively working on bringing the new style (/library/) up to speed. If you've hit broken links recently (in the last few days), it would help us if you could point them out.

[...]
> clamp    clamp(1, 3, 6) returns 3. clamp(4, 3, 6) returns 4.
>
> Yeah...that does not explain anything. Definition writing 101 tells you
> to never use the word you are trying to define in the sentence defining
> it. In fact, most of the descriptions for the functions in std.algorithm
> should probably come with better descriptions. D doesn't offer a lot of
> return on investment for learning it, so you could at least make it easy
> to learn...
>
> isPermutation    isPermutation([1, 2], [2, 1]) returns true.
>
> ^^^ How is that helpful? BTW, I'm getting this from this page:
>
> https://dlang.org/library/std/algorithm/comparison.html
>
> Now, if I click on each function I get a little bit better of an
> explanation (in some cases), but why have a useless description? It
> serves nothing and just distracts. You might as well as not have a
> description column on std.algorithm, and just provide links.

Interesting. We've been thinking about this exact thing lately [1]. So from your fresh experience, the "Cheat Sheet" is not very helpful.

If you scroll down on that documentation page you get to another table under the heading "Functions". It looks very similar to the cheat sheet, but the descriptions are different. (Having two almost identical tables like that is the problem we're trying to fix.) Would you consider the description in the "Functions" table more helpful than the ones in the "Cheat Sheet"?


[1] http://forum.dlang.org/post/niv2hc$2l7k$1@digitalmars.com

On Sunday, 5 June 2016 at 13:35:18 UTC, ag0aep6g wrote:
> On 06/05/2016 02:58 PM, David wrote:
>> [...]
>
> The different style pages are most probably dlang.org/phobos/ pages and dlang.org/library/ pages. They are built from the same source, so they should contain the same information. Neither of them should be outdated.
>
> We're actively working on bringing the new style (/library/) up to speed. If you've hit broken links recently (in the last few days), it would help us if you could point them out.
>
> [...]
>> [...]
>
> Interesting. We've been thinking about this exact thing lately [1]. So from your fresh experience, the "Cheat Sheet" is not very helpful.
>
> If you scroll down on that documentation page you get to another table under the heading "Functions". It looks very similar to the cheat sheet, but the descriptions are different. (Having two almost identical tables like that is the problem we're trying to fix.) Would you consider the description in the "Functions" table more helpful than the ones in the "Cheat Sheet"?
>
>
> [1] http://forum.dlang.org/post/niv2hc$2l7k$1@digitalmars.com

Yes those descriptions below are much better. I guess I glossed over them. I focused too much on the cheat sheet, because I assumed the cheat sheet was the quick link to function main pages (which seems to be the case). Perhaps this is a case where 'more' isn't better? I'm not quite sure what the cheat sheet really is providing...

I mean if it was an example of common uses of the function that would be one thing. But I guess I'm not sure what information one is supposed to get from the 'cheat' sheet.

On Sunday, 5 June 2016 at 13:35:18 UTC, ag0aep6g wrote:
> On 06/05/2016 02:58 PM, David wrote:
>> [...]
>
> The different style pages are most probably dlang.org/phobos/ pages and dlang.org/library/ pages. They are built from the same source, so they should contain the same information. Neither of them should be outdated.
>
> [...]

I encountered quite a few broken links. One I recall was the std.container link at the top of this page:

https://dlang.org/library/std/container/array.html

I don't remember the rest.

On Sunday, 5 June 2016 at 13:35:18 UTC, ag0aep6g wrote:
> On 06/05/2016 02:58 PM, David wrote:
>> [...]
>
> The different style pages are most probably dlang.org/phobos/ pages and dlang.org/library/ pages. They are built from the same source, so they should contain the same information. Neither of them should be outdated.
>
> [...]

FYI, I think I encountered a broken link on most of the pages I visited.

On 06/05/2016 03:52 PM, David wrote:
> Yes those descriptions below are much better. I guess I glossed over
> them. I focused too much on the cheat sheet, because I assumed the cheat
> sheet was the quick link to function main pages (which seems to be the
> case). Perhaps this is a case where 'more' isn't better? I'm not quite
> sure what the cheat sheet really is providing...

The cheat sheet comes from the older style documentation which has all functions on one page and no generated listing of them. The cheat sheet provides a quick overview there, so that you don't have to scroll so much to find something.

For example, see the same page in the older style:

https://dlang.org/phobos/std_algorithm_comparison.html

In the newer style documentation, the cheat sheets don't really make sense. We're in the process of figuring out what to do about it.

> I mean if it was an example of common uses of the function that would be
> one thing. But I guess I'm not sure what information one is supposed to
> get from the 'cheat' sheet.

Maybe it's just a case of bad documentation. Do you think that all descriptions in the the cheat sheet are bad, or are some acceptable? For example, `either`'s description is this:

Return first parameter p that passes an if (p) test, e.g. either(0, 42, 43) returns 42.

Is that good/bad/acceptable?

On Sunday, 5 June 2016 at 13:56:55 UTC, David wrote:
> On Sunday, 5 June 2016 at 13:35:18 UTC, ag0aep6g wrote:
>> On 06/05/2016 02:58 PM, David wrote:
>>> [...]
>>
>> The different style pages are most probably dlang.org/phobos/ pages and dlang.org/library/ pages. They are built from the same source, so they should contain the same information. Neither of them should be outdated.
>>
>> [...]
>
> I encountered quite a few broken links. One I recall was the std.container link at the top of this page:
>
> https://dlang.org/library/std/container/array.html
>
> I don't remember the rest.

Fixed in master:

https://dlang.org/library-prerelease/std/container/array.html

On 06/05/2016 04:14 PM, Vladimir Panteleev wrote:
> Fixed in master:
>
> https://dlang.org/library-prerelease/std/container/array.html

Heh. I've been starting to question my sanity.

On Sunday, 5 June 2016 at 12:58:56 UTC, David wrote:
> D doesn't offer a lot of return on investment for learning it,

That sort of sets the tone for the rest of your post, doesn't it...

> ^^^ How is that helpful?

Replied to this on GitHub: https://github.com/dlang/phobos/pull/4397#issuecomment-223813719

> The other beef I see, is that examples for functions seem like they are just ripped from random unittests and frequently reference other standard library calls without context of what they are doing.

Yes, many examples are actually unit tests, to verify that the displayed examples actually work. Most examples are written in the style that the result of the documented function is `assert`ed or `enforce`d to be correct, which may be unusual at first. The chomp call does seem unnecessary in that example, though.