On Sun, May 08, 2016 at 10:45:51PM +0300, Andrei Alexandrescu via Digitalmars-d-announce wrote:
> On 5/8/16 8:19 PM, qznc wrote:
> >On Sunday, 8 May 2016 at 06:05:36 UTC, Iain Buclaw wrote:
> >>http://blog.tenstral.net/2016/05/adventures-in-d-programming.html
> >
> >Thanks, I missed that post until now.
> >
> >
> >"the documentation not matching the actual code is a bad experience for someone new to the language"
> >
> >I would interpret that as a sign that we want multiple versions of documentation available on the website. For example, Python does that.
> >
> >https://docs.python.org/3.4/contents.html
> >
> >You see the "3.4" version in the URL and on the page top-left is a dropdown menu to switch between versions.
> >
> >Has this been discussed for Phobos yet?
> 
> No, but it's been on my mind for a while. -- Andrei

AFAICT, it shouldn't be super hard to do this. We're already building Phobos docs in phobos-prerelease/, and IIRC the dlang.org repo already downloads the last official release and installs it in phobos/. So it's just a matter of extending this to install multiple doc builds in phobos-x.y.z/.


T

-- 
This sentence is false.

On 5/9/16 1:33 AM, H. S. Teoh via Digitalmars-d-announce wrote:
> AFAICT, it shouldn't be super hard to do this. We're already building
> Phobos docs in phobos-prerelease/, and IIRC the dlang.org repo already
> downloads the last official release and installs it in phobos/. So it's
> just a matter of extending this to install multiple doc builds in
> phobos-x.y.z/.

That is correct. -- Andrei

On Sunday, 8 May 2016 at 22:22:08 UTC, Peter Häggman wrote:
> On Sunday, 8 May 2016 at 17:19:05 UTC, qznc wrote:
>> On Sunday, 8 May 2016 at 06:05:36 UTC, Iain Buclaw wrote:
>>> http://blog.tenstral.net/2016/05/adventures-in-d-programming.html
>>
>> Thanks, I missed that post until now.
>>
>>
>> "the documentation not matching the actual code is a bad experience for someone new to the language"
>>
>> I would interpret that as a sign that we want multiple versions of documentation available on the website. For example, Python does that.
>
> You've quoted the wrong part of the paragraph. The real problem he encountered was not the doc, it was the phobos bugs in the older version shipped with GDC/LDC:
>
> "For GDC, which I used to compile my code due to LDC having bugs at that time, this means that it is shipping with a very outdated copy of Phobos"
>
> The the doc thing is "just" a symptom. Older offline doc is always available in the release archive, it's easy to understand that so it's not the actual problem.

You are correct, but can this be solved? Newer Phobos versions fix bugs. GDC needs a newer Phobos? Well, this is translated into GDC needs more manpower. Everything does. Nothing new.

On Monday, 9 May 2016 at 09:29:36 UTC, qznc wrote:
> On Sunday, 8 May 2016 at 22:22:08 UTC, Peter Häggman wrote:
>> [...]
>>
>> You've quoted the wrong part of the paragraph. The real problem he encountered was not the doc, it was the phobos bugs in the older version shipped with GDC/LDC:
>>
>> "For GDC, which I used to compile my code due to LDC having bugs at that time, this means that it is shipping with a very outdated copy of Phobos"
>>
>> The the doc thing is "just" a symptom. Older offline doc is always available in the release archive, it's easy to understand that so it's not the actual problem.
>
> You are correct, but can this be solved? Newer Phobos versions fix bugs. GDC needs a newer Phobos? Well, this is translated into GDC needs more manpower. Everything does. Nothing new.

First of all, that blogpost generated way more buzz than I expected - looks like D is highly interesting to people, which is great news :-)

To elaborate a bit more on the version incompatibilities thing: E.g. me as a new user reads about std.concurrency.Generator, wants to use it, and it turns out that the standard library doesn't contain it yet (in GDC). Same for std.experimental.logger.
Okay, means I can't use these.
Then, I wanted to use std.getopt - turns out the semantics have changed and new stuff has been added there too, which I can't use. Meh, if the docs would have at least told me that.

Then, I want to use D-YAML, which depends on std.stream. But std.stream is completely deprecated, with no clear path for me to see to replace it. That's really bad, and it also means I can't compile my code with making the use of deprecated stuff fail the compilation.

That was by far the most frustrating things I experienced in D. So ideally the docs would be split for different Phobos versions, that would already be a great help. Then, when deprecating stuff, showing a thing that replaces it or the proper way to write code using it would also be really nice.
E.g. wile I welcome the deprecation of std.net.curl in principle (having to link against an external library in the standard lib is odd), announcing to drop it before any replacement which offers feature-parity is written is bad (sidenote: IMHO the advanced net stuff shouldn't be in the standard library, because it's harder to update in case of security updates and bad crypto).

It would actually be really awesome if Phobos wasn't tied to a compiler, and all D compilers which are standard-compliant could compile it. Then, one could assume that people have the most recent Phobos. But it looks like it will take a longer time to get there, if at all.


Another thing that I didn't mention in the blogpost, but which might be interesting is that D - unlike Rust and Go - doesn't have a way that lets developers do a shallow-dive into the language by giving practical examples.
For example, Go has the really awesome Go Tour[1] which lets you explore and learn the basic concepts of the language by example.
For me, going through the tour was enough to actually start writing Go code, and while it certainly isn't complete, it is a nice way to show off the language and give people a taste of how it looks like. Rust has something similar with its tutorial[2].

For D, I haven't found an "in a nutshell" tutorial, and needed to read a bit more documentation and employ my existing C/C++ knowledge in some cases.
Having something like the Go tour for D would IMHO be an wesome way to attract people to try D.

Cheers,
    Matthias


[1]: https://tour.golang.org/welcome/1
[2]: https://doc.rust-lang.org/book/guessing-game.html

On 05/12/2016 11:08 PM, Matthias Klumpp wrote:
> Then, I want to use D-YAML, which depends on std.stream. But std.stream
> is completely deprecated, with no clear path for me to see to replace
> it. That's really bad, and it also means I can't compile my code with
> making the use of deprecated stuff fail the compilation.

Deprecations are warnings by default. Using deprecated stuff shouldn't fail compilation unless you're using `-de` (dmd flag).

> E.g. wile I welcome the deprecation of std.net.curl in principle (having
> to link against an external library in the standard lib is odd),
> announcing to drop it before any replacement which offers feature-parity
> is written is bad

I don't think that has been announced. It's only been discussed, no?

> For D, I haven't found an "in a nutshell" tutorial, and needed to read a
> bit more documentation and employ my existing C/C++ knowledge in some
> cases.
> Having something like the Go tour for D would IMHO be an wesome way to
> attract people to try D.

That's being worken on: http://tour.dlang.io/

On Sunday, 8 May 2016 at 22:22:08 UTC, Peter Häggman wrote:
> "[…] due to LDC having bugs at that time […]"

Are there any bug reports for this, by the way? Thanks!

 — David

Dne 12.5.2016 v 23:08 Matthias Klumpp via Digitalmars-d-announce napsal(a):

> First of all, that blogpost generated way more buzz than I expected - looks like D is highly interesting to people, which is great news :-)
>
> To elaborate a bit more on the version incompatibilities thing: E.g. me as a new user reads about std.concurrency.Generator, wants to use it, and it turns out that the standard library doesn't contain it yet (in GDC). Same for std.experimental.logger.
> Okay, means I can't use these.

This is something I do not like. It would be awesome if I could use new version of phobos (dub package for eg.) in a dmd, ldc or gdc. Having language which is so unstable so is almost impossible to use standard library with older frontend is really anoying.

> Then, I wanted to use std.getopt - turns out the semantics have changed and new stuff has been added there too, which I can't use. Meh, if the docs would have at least told me that.

I knew it :). I end up with same problem with std.getopt. It was a reason for this post: http://forum.dlang.org/post/srhttrxrqawhspibdlrj@forum.dlang.org

std.getopt has been backward compatible but it was not forward compatible. So because there is only latest docs available you are doomed :(.
>
> Then, I want to use D-YAML, which depends on std.stream. But std.stream is completely deprecated, with no clear path for me to see to replace it. That's really bad, and it also means I can't compile my code with making the use of deprecated stuff fail the compilation.

I am not sure what exactly this deprecation message say, but you definitely should not used std.stream at all in a first place ;-).

> That was by far the most frustrating things I experienced in D. So ideally the docs would be split for different Phobos versions, that would already be a great help. 

Yes this would help a lot.
> Then, when deprecating stuff, showing a thing that replaces it or the proper way to write code using it would also be really nice.
> E.g. wile I welcome the deprecation of std.net.curl in principle (having to link against an external library in the standard lib is odd), announcing to drop it before any replacement which offers feature-parity is written is bad (sidenote: IMHO the advanced net stuff shouldn't be in the standard library, because it's harder to update in case of security updates and bad crypto).
>
> It would actually be really awesome if Phobos wasn't tied to a compiler, and all D compilers which are standard-compliant could compile it. Then, one could assume that people have the most recent Phobos. But it looks like it will take a longer time to get there, if at all.

I hope it would not take so much time. This is really important if D want to succeed.

> Another thing that I didn't mention in the blogpost, but which might be interesting is that D - unlike Rust and Go - doesn't have a way that lets developers do a shallow-dive into the language by giving practical examples.
> For example, Go has the really awesome Go Tour[1] which lets you explore and learn the basic concepts of the language by example.
> For me, going through the tour was enough to actually start writing Go code, and while it certainly isn't complete, it is a nice way to show off the language and give people a taste of how it looks like. Rust has something similar with its tutorial[2]. For D, I haven't found an "in a nutshell" tutorial, and needed to read a bit more documentation and employ my existing C/C++ knowledge in some cases.
> Having something like the Go tour for D would IMHO be an wesome way to attract people to try D.
There is already http://tour.dlang.io, but I do not have yet time to try it so I can't speak about maturity and so on. Other problem is with complexity of D. I believe even I can write book about D, which make people able to write almost anything in D. But they will not be able to read all D code. Go is OTOH really easy language so you need book with around 200 pages to explain everything. But with D I am not sure that even 1000 of pages would be enough :(.
>
> Cheers,
>     Matthias
>
>
> [1]: https://tour.golang.org/welcome/1
> [2]: https://doc.rust-lang.org/book/guessing-game.html

On Thursday, 12 May 2016 at 22:01:04 UTC, David Nadlinger wrote:
> Are there any bug reports for this, by the way? Thanks!

I believe, it was the atomicOp bug. You can see the link to discussion there.

On Thursday, 12 May 2016 at 21:08:58 UTC, Matthias Klumpp wrote:
> To elaborate a bit more on the version incompatibilities thing: E.g. me as a new user reads about std.concurrency.Generator, wants to use it, and it turns out that the standard library doesn't contain it yet (in GDC). Same for std.experimental.logger.
> Okay, means I can't use these.

I haven't tried myself for these, but it might turn out to be not so much work just to copy the relevant files over and clean up the rough edges if you want to use these in GDC/LDC.  But I know that it's harder and a nuisance if you aren't that familiar with the language and just want to get your job done.

> Then, I want to use D-YAML, which depends on std.stream. But std.stream is completely deprecated, with no clear path for me to see to replace it. That's really bad, and it also means I can't compile my code with making the use of deprecated stuff fail the compilation.

https://github.com/DigitalMars/undeaD/blob/master/src/undead/stream.d

You might want to submit a pull request so D-YAML depends on this (where removed parts of Phobos go to live) rather than std.stream.

> That was by far the most frustrating things I experienced in D. So ideally the docs would be split for different Phobos versions, that would already be a great help. Then, when deprecating stuff, showing a thing that replaces it or the proper way to write code using it would also be really nice.

I agree.

> It would actually be really awesome if Phobos wasn't tied to a compiler, and all D compilers which are standard-compliant could compile it. Then, one could assume that people have the most recent Phobos. But it looks like it will take a longer time to get there, if at all.

A matter of maturity and resources.  It's quite astonishing the value that the small number of people working on LDC and GDC have been able to create.  (DMD too, but there are more people).  Maybe there ought to be a way to express concrete appreciation for their work.