On Tuesday, 5 January 2016 at 08:31:55 UTC, Jacob Carlborg wrote:
> "Address" not being cross-linked here [1] while "SocketOSException" is.

thanks! That's one I missed in the Phobos source code.

On Tuesday, 5 January 2016 at 08:12:56 UTC, Jacob Carlborg wrote:
> I suggest showing only links to inherited members, not the docs for them.

What I want to show is the links plus just the first excerpt of the docs, so you have an idea what it is aside from the name without taking up a lot of space.

My thing doesn't quite cut out the excerpt right yet though (really because so many of the Phobos docs don't follow a sane convention... I need to go back and rewrite a few of the summaries myself.)

> Anyway, it shows inherited fields and methods. For classes it shows known subclasses and for interfaces known implementations.

Yeah, "known" is good because then it demos that there can be more. I like that.

> The Scala docs [2] are pretty good as well. Separates abstract and concrete methods. Separate sections for the different protection levels and so on.

Interesting. Separating abstract is definitely a good idea since you kinda need to know that to implement.



There's so much potential for class docs! Pity Phobos doesn't use them much though :(

On 01/05/2016 12:09 AM, Adam D. Ruppe wrote:
> 1) a massively simplified build. Indeed, I'll make a web form so you
> don't even have to have dmd installed to make some docs.

Nice. The web forms sound like a great idea.

> This got posted today:
> https://issues.dlang.org/show_bug.cgi?id=15516#c2
>
> Two people whose names I recognize who have been with D for a long time
> didn't know how to add a page to the website. And what they did figure
> out was a multi step process.
>
> My system already runs a single file or an entire directory and just
> works. It will never forget a file because you didn't add it to mak/DOCS
> of win32.mak or anything else.

There's been a recent discussion with Walter and Martin about using wildcards in makefiles (which would obviate the necessity of being explicit about files).

My understanding is that build scripts (including makefiles) are recommended to include a manifest list of files that are part of the project, as opposed to picking up files with wildcards. That way there's less likelihood to pick up litter along with the legitimate files, or to produce incomplete builds if some files are missing by mistake. The underlying thesis is that that's a good kind of redundancy.

That said, in a git-controlled directory things aren't that bad. "git clean -dfx" removes uncontrolled files and "git checkout" makes sure all files are present. Would you recommend switching to wildcards in our makefiles and assume people use git to keep their directories in good shape?

Regarding the makefile complications. I think it stands to reason that in the dlang.org repo, the command "make" will produce the entire website. There are quite a few pieces to that:

* The druntime and phobos docs must be built as well.

* For these there are the docs as per last release and also the docs in the current HEAD, which are distinct.

* Each library version must be built with the same compiler version. The appropriate compiler version might be missing, so it needs to be downloaded, installed, and run on the side without affecting any existing installation.

* There are ancillary things to be build, such as the vibe docs and the language reference (ebook, pdf, chm). The ebook has ranked #26 among most downloaded files on dlang.org, the pdf is #40, and the chm is apparently not in the top 256. The most popular ddox file is http://dlang.org/library, ranking at #96.

My understanding is that your system does not do any of these things. If such functionality were to be integrated, either the system would increase in complexity correspondingly, or it would become a part of a larger build script.

The script https://github.com/D-Programming-Language/dlang.org/blob/master/posix.mak stands at 498 lines. What ways there are to make it considerably simpler and smaller?

> I'll also make a web form to upload new pages and probably entire
> projects for automatic processing too.

Indeed the web forms sound like a great idea. Would you want to work on such for the mainline website as well? It's not a contest; the better everything is, the better off everybody is.

> 2) My linking system already works better than ddoc allows. You can
> reference with a single macro: $(REF some.name). I also keep MREF, XREF,
> and a few others for legacy phobos+ddoc compatibility, but the user
> doesn't have to know a hundred obscure macros. (There's about a
> half-dozen simple ones instead, plus a few thin wrappers over HTML which
> I might kill but might not since they don't really bother me.)

Nice. What could we do in ddoc and ddox to have a similar improvement?

> Combined with the ease of adding all new files, contributors can just
> link new articles they write to go in depth without worrying about process.
>
>
>
> 3) I'm also going to make a dynamic webpage once I declare this beta
> where viewers will be given random pages and asked to eyeball it for me.
> If they flag it as buggy - with a single click on the page, no bugzilla
> signups - it'll contact me and I'll work on the bug.

How do you envision scaling it up as the system becomes more successful and you get more requests than you can handle reasonably quick?

Would you be willing to set up such a system for dlang.org as well? It would be absolutely fantastic.

> If they want to contribute to content, I can pull up the existing
> comment source code and present it right there, again likely emailed to
> me for integration, or the source location can be opened in Phobos for a
> traditional pull request.
>
> This will encourage crowd sourcing doc bug fixes.

My understanding is a lot of it hinges on you being on top of things (and the bottleneck thereof). I think it's awesome that you're able and willing to do this; the same kind of enthusiasm and dedication would definitely help fix a lot of the existing issues with ddoc and ddox.

> 4) I'll never complain about spaces vs tabs, line length, or any other
> trivial nonsense. If I don't like that stuff, I'll just fix it myself
> instead of letting the PR wither and die while letting the contributor
> feel undervalued.

Anyone could do the same today for all pull requests - just fetch them, fix them, and resubmit with credit. Additionally, team members could just pull the PR, fix it, and make an additional commit.

Regarding PRs that are not looked at, we currently have 18 PRs at https://github.com/D-Programming-Language/dlang.org/pulls, and 16 folks who have the rights to pull them (https://github.com/orgs/D-Programming-Language/teams/team-dlang-org). I'll take a look at them after this (some look really trivial); it's a bummer they aren't looked at more regularly.

I'll note that you are already a member of that team so you already had the rights to exact quite a few of the improvements you intend to make going forward. Would you please join me in taking a look at older PRs (oldest is from 2014) and pull them in?

Overall my understanding of your message is "My system would be better not for a fundamental technical reason, but because I am willing to pour in it time and talent." This is the kind of argument I have a lot of respect for.


Thanks,

Andrei

On Tuesday, 5 January 2016 at 14:18:32 UTC, Andrei Alexandrescu wrote:

> Overall my understanding of your message is "My system would be better not for a fundamental technical reason, but because I am willing to pour in it time and talent." This is the kind of argument I have a lot of respect for.

IMO it's not just his willingness to put in the time that is different. There are some critical technical differences:

- There is one person making the decision.
- You don't have to worry about unstated (and sometimes arbitrary) rules. The current system feels like your dealing with the Soup Nazi.
- You don't have to mess with Git. For me, that's a big one, because I've never used Git for a large project like this.
- You don't have to build the whole website. You don't have to do Phobos unit tests to change a broken link.

I'll give you an example. Not by coincidence, this was the last contribution I attempted to make.

I read the documentation for schwartzSort, and finding that it conveyed no information, I wanted to suggest something better. A discussion forum or email message would be the ideal way to do so, but knowing that's not how things are done here, I decided to submit a PR. After at least a couple hours (it may have been more) looking at other documentation to find ideas for how to do it better, doing several revisions to get to something I found satisfactory, checking for no trailing spaces and making sure the syntax was consistent with the other documentation, battling with Git, and battling to get the full site to build, I submitted this:

https://github.com/D-Programming-Language/phobos/pull/3831

One person reviewed it and didn't like my change, because he felt the existing documentation was better. Later, someone commented that he liked my version. And now it's sitting there. It's not going to be accepted and because nobody's in charge of the documentation it won't be closed either.

The problem is not that my PR was (for practical purposes) rejected. As an academic I deal with both sides of peer review all the time. The problem is that I was forced to put so much time into it just to make a suggestion. With Adam's project, I can send him an email with a suggested change, and he can do as he wishes with it. It will take two minutes of my time.

On 01/05/2016 10:15 AM, bachmeier wrote:
> There are some critical technical differences:
>
> - There is one person making the decision.

Not technical. -- Andrei

On Monday, 28 December 2015 at 20:15:30 UTC, Adam D. Ruppe wrote:
> Last week, I posted in the general forum my dream for better D docs. Today, about 4 days of work later, I'm about 1/4 of the way there.
>
> Still a long way to go, but I've already come so far.
>
> First, behold my old dpldocs.info site. Yes, it is still up and now it ties into my new docs! You can use it to quickly jump to a doc given its name:
>
> http://dpldocs.info/

This is awesome! I warmly welcome this approach. I just got a comment from a newbie D developer fellow who commented on the current unpleasant doc formatting of templated headers.

On Tuesday, 5 January 2016 at 15:32:52 UTC, Andrei Alexandrescu wrote:
> On 01/05/2016 10:15 AM, bachmeier wrote:
>> There are some critical technical differences:
>>
>> - There is one person making the decision.
>
> Not technical. -- Andrei

http://www.snopes.com/humor/letters/miriam.asp

On Tuesday, 5 January 2016 at 15:32:52 UTC, Andrei Alexandrescu wrote:
> On 01/05/2016 10:15 AM, bachmeier wrote:
>> There are some critical technical differences:
>>
>> - There is one person making the decision.
>
> Not technical. -- Andrei

Indeed but on the other hand is impacting the technical stuff.

JohnCK.

On Tuesday, 5 January 2016 at 15:43:30 UTC, Nordlöw wrote:
> This is awesome! I warmly welcome this approach. I just got a comment from a newbie D developer fellow who commented on the current unpleasant doc formatting of templated headers.

The mouse-over behaviour of CT- and RT-parameters is just really really cool! Thanks!

On 01/05/2016 10:15 AM, bachmeier wrote:
>
> I read the documentation for schwartzSort, and finding that it conveyed
> no information, I wanted to suggest something better. A discussion forum
> or email message would be the ideal way to do so, but knowing that's not
> how things are done here, I decided to submit a PR. After at least a
> couple hours (it may have been more) looking at other documentation to
> find ideas for how to do it better, doing several revisions to get to
> something I found satisfactory, checking for no trailing spaces and
> making sure the syntax was consistent with the other documentation,
> battling with Git, and battling to get the full site to build, I
> submitted this:
>
> https://github.com/D-Programming-Language/phobos/pull/3831
>
> One person reviewed it and didn't like my change, because he felt the
> existing documentation was better. Later, someone commented that he
> liked my version. And now it's sitting there. It's not going to be
> accepted and because nobody's in charge of the documentation it won't be
> closed either.

Thanks for submitting. The way I see it is that PR needs improvement. The bar is low seeing as pretty much any addition to the documentation is good. So all you need to do is make sure the addition is of good quality.

So the proposed final text is:

============
Returns the same output as an equivalent call to $(D sort), but it will be
faster when the sort comparison requires an expensive computation.
$(D schwartzSort) allocates a temporary array to cache the sort keys. It can
therefore be slower than $(D sort) in other cases.

Sorts a range using an algorithm akin to the $(WEB
wikipedia.org/wiki/Schwartzian_transform, Schwartzian transform), also
known as the decorate-sort-undecorate pattern in Python and Lisp. The
complexity is the same as that of the corresponding $(D sort), but
$(D schwartzSort) evaluates $(D transform) only $(D r.length) times (less than
half when compared to regular sorting). The usage can be best illustrated with
an example.
=============

The text is imprecise, e.g. an equivalent call to `sort` really is `sort!((a, b) => less(transform(a), transform(b))`. All that detail needn't be present in the first paragraph, so there's a bit of an art in how you formulate simple sentences that are at the same time correct and informative.

The second paragraph used to be the first (and only) one. Now it doesn't flow from the first one, it's jarring. Here's a possible improved text (feel free to copy, paste, adapt etc):

============
Alternative sorting method that should be used when comparing keys involves an expensive computation. Instead of using `less(a, b)` for comparing elements, `schwartzSort` uses `less(transform(a), transform(b)`. The values of the `transform` function are precomputed in a temporary array, thus saving on repeatedly computing it. Conversely, if the cost of `transform` is small compared to the cost of allocating and filling the precomputed array, `sort` may be faster and therefore preferable.

This approach to sorting is akin to the $(WEB
wikipedia.org/wiki/Schwartzian_transform, Schwartzian transform), also
known as the decorate-sort-undecorate pattern in Python and Lisp. The
complexity is the same as that of the corresponding $(D sort), but
$(D schwartzSort) evaluates $(D transform) only $(D r.length) times (less than half when compared to regular sorting). The usage can be best illustrated with an example.
=============

> The problem is not that my PR was (for practical purposes) rejected. As
> an academic I deal with both sides of peer review all the time. The
> problem is that I was forced to put so much time into it just to make a
> suggestion. With Adam's project, I can send him an email with a
> suggested change, and he can do as he wishes with it. It will take two
> minutes of my time.

I agree that the best aspect of Adam's system is Adam.


Andrei