On Saturday, 29 September 2012 at 15:29:46 UTC, Mr. Anonymous
wrote:
Hi guys.
I was browsing the book "Programming in D" by Ali Çehreli. It
was pretty much clear, and then I stumbled upon this on page 89:
20.9 Exercises
1. Browse the documentations of the std.string, std.array,
std.algorithm, and std.range modules.
OK, let's open the D website and browse the documentation of
std.string:
http://dlang.org/phobos/std_string.html
What do we see? A bunch of links that look like SEO tags of a
spam website, followed by a mess of anything - structs,
classes, functions, and what not.
Do you really think somebody who learns programming can
understand anything here?
Compare this with, e.g., an msdn reference:
http://msdn.microsoft.com/en-us/library/windows/desktop/ms684852(v=vs.85).aspx
A clear division of enums, functions, macros, structs, ...
http://msdn.microsoft.com/en-us/library/windows/desktop/ms684847(v=vs.85).aspx
The functions are divided by usage, with a short explanation
next to each function.
I think documentation is really important, and something has to
be done about it. How can a newcomer get started with D when he
doesn't have a readable documentation of Phobos?
OK, I looked at it, and I saw that the links are generated by
javascript.
So I decided to try and write a better javascript function for
creating links.
Here's what I came up with:
The JS code: http://pastebin.com/Pz4fb4JR
Screenshots: http://i.imgur.com/gwxrI.png,
http://i.imgur.com/qGGQn.png
As you can see, the code works for both the website html and the
one bundled with dmd.
If my function finds nothing, it falls back to it's old version
of anchor list.
This solution is quite bad and temporary, but what we have now is
not much better, so, for a while, I think it's worth using.
P.S. I saw in the comments that Adam D. Ruppe came up with a
better solution, but it requires an external tool. My solution
requires a small javascript change, which should be very easy to
integrate.
