Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.