FYI, even now, I hesitate to change links in my Phobos fork
because I kinda want to remain ddoc compatible... and I can never
remember what macro it is. And I've been kinda deep in this the
whole last week.
Anyway, let's get into this:
On Sunday, 3 January 2016 at 23:16:30 UTC, Andrei Alexandrescu
wrote:
Do the projected advantages of Adam's project do not include
ease of contribution? If so, how?
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.
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.
I'll also make a web form to upload new pages and probably entire
projects for automatic processing too.
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.)
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.
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.
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.
