Better docs for D (WIP)

Andrei Alexandrescu via Digitalmars-d-announce digitalmars-d-announce at puremagic.com
Tue Jan 5 06:18:32 PST 2016


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



More information about the Digitalmars-d-announce mailing list