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
