Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

On 12/30/2015 08:32 PM, Adam D. Ruppe wrote:
> ~2010: I had just written this awesome dom.d library and wanted to
> document it and release it to the world. I write stuff like:
>
> /// Returns the text in the element. For example, innerText of
> <span>foo<span> is "foo" (without quotes)
> string innerText();
>
> And it came out mangled because of ddocs embedded HTML "feature" which
> doesn't encode the output. I proposed a fix, using ddoc's existing
> ESCAPES macro, and wrote the patch for dmd. Embedded html would be
> automatically encoded, but you can still define it in macro definitions,
> which can be inline with the comment, so it isn't hard to use when you
> want it.
>
> It was rejected. Walter didn't see what the problem was and I was told
> to just write $(LT)span$(GT)foo$(LT)/span$(GT). Seriously.

Could you please post a link to your proposed fix?

> The idea (and working program) was rejected because the team felt a
> post-processor was the wrong way to do it.

Do you have a link to that proposal and discussion?

> We got another website redesign in these years, and moved to dlang.org.
> The build process finally got documented after I and others complained
> for a while, but it was never actually cleaned up.

What steps do we need to take to clean the build process up?

> I just got sidetracked doing a quick paragraph fix for Andrei... and
> then wanted to see how far I could go. I got it working, despite the
> obstacles that ddoc's freeform macros bring, and surprise, it was
> rejected.

For reference: https://github.com/D-Programming-Language/dmd/pull/5319. 
I don't think it should have been accepted. It's not a good PR.

> Even the simpler patch that just collapses blank lines sits
> unanswered.

Sorry, the holiday period is not very productive what with the kids on 
vacation and whatnot. I'll pull your PR to my patch and will move 
forward with it. Thanks. Or did you work that into something standalone 
that I've missed?

> A tool to look for broken links sits unanswered. There's
> always a call to contributions, but when you do push through the painful
> process to get the code up (and the tester, the f$^%$^ing tester),
> nobody seems to care.

I agree and I'm sorry we're not moving faster with reviews, but really 
that's not ddo(c|x)'s fault.

> The combined experience over these last six years tells me that the
> website sucks and it keeps sucking because changing it sucks even more
> than using it. A new strategy was required.
>
> And here we are.

I hear your frustration, and for a good part I agree with it. Again: all 
I want is to make sure you have the right motivation and that you are 
fully informed of what's currently going on.


Andrei