On Tuesday, 21 February 2017 at 22:58:57 UTC, Seb wrote:
>
> Unfortunately it reverts the writeln magic as the false positive rate was too high - at some point we really should come up with something better :/
> However the fact that ddoc and ddox emit different, fully built synax-highlighted HTML doesn't make it easier. Maybe the compiler can help out here (?) or we can run a libdparse-based formatter before running ddoc/ddox?
> (at least for ddox there is also the intermediate json output of DMD, but for now it seems that the switch to ddox doesn't happen as soon as anticipated)


Okay I just couldn't let this sit on myself. So I went ahead and proposed a more "sophisticated" assert -> writeln rewrite tool that is based on Hackerpilot's excellent libdparse:

https://github.com/dlang/dlang.org/pull/1582

On Saturday, 18 February 2017 at 16:57:33 UTC, Seb wrote:
> As imho the border doesn't look that bad and for the same reason as above I didn't remove the border. See a visual comparison here:
>
> http://imgur.com/a/pElAu
>
> Are you or others still in favor of removing the border?

I like the first version in the screenshot (with a border).

On Wednesday, 22 February 2017 at 19:14:14 UTC, Seb wrote:
>
>
> Okay I just couldn't let this sit on myself. So I went ahead and proposed a more "sophisticated" assert -> writeln rewrite tool that is based on Hackerpilot's excellent libdparse:
>
> https://github.com/dlang/dlang.org/pull/1582

So is everything working as advertised? Is it redditable?

On Monday, 27 February 2017 at 14:12:30 UTC, Mike Parker wrote:
> On Wednesday, 22 February 2017 at 19:14:14 UTC, Seb wrote:
>>
>>
>> Okay I just couldn't let this sit on myself. So I went ahead and proposed a more "sophisticated" assert -> writeln rewrite tool that is based on Hackerpilot's excellent libdparse:
>>
>> https://github.com/dlang/dlang.org/pull/1582
>
> So is everything working as advertised?

Yes, thanks to a lot of support from CyberShadow [1] and Hackerpilot's immediate review of my libdparse fixes [2, 3], the new assert -> writeln logic is now live, e.g.

Ddox: https://dlang.org/library-prerelease/std/algorithm/comparison/among.html
Ddoc: https://dlang.org/phobos/std_algorithm_searching.html#.minElement

It's based on a AST transformation of the AssertExpressions. For more details one can have a look at [4].

> Is it redditable?

Yes, finally :)

[1] https://github.com/dlang/dlang.org/pull/1582
[2] https://github.com/Hackerpilot/libdparse/pull/128
[3] https://github.com/Hackerpilot/libdparse/pull/130
[4] https://github.com/dlang/dlang.org/blob/master/assert_writeln_magic.d

On Monday, 27 February 2017 at 15:41:18 UTC, Seb wrote:
>> Is it redditable?
>
> Yes, finally :)

Can we fix the fact that the docs are duplicated for template functions before any big announcements? See e.g. https://dlang.org/library-prerelease/std/algorithm/comparison/among.html from above. This leaves quite the bad impression, as it makes the page look like an unstructured mess at first glance.

 - David

On Monday, 27 February 2017 at 16:49:13 UTC, David Nadlinger wrote:
> On Monday, 27 February 2017 at 15:41:18 UTC, Seb wrote:
>>> Is it redditable?
>>
>> Yes, finally :)
>
> Can we fix the fact that the docs are duplicated for template functions before any big announcements? See e.g. https://dlang.org/library-prerelease/std/algorithm/comparison/among.html from above.

That's one of the disadvantages of running two documentation engines.

Related pointers:

https://github.com/dlang/dlang.org/pull/1526 (making ddox the default)
https://github.com/rejectedsoftware/ddox/issues

>  This leaves quite the bad impression, as it makes the page look like an unstructured mess at first glance.

A solution for the moment is to point people at the ddoc version, e.g.

https://dlang.org/phobos/std_algorithm_comparison.html#.among

On Monday, 27 February 2017 at 16:49:13 UTC, David Nadlinger wrote:
> See e.g. https://dlang.org/library-prerelease/std/algorithm/comparison/among.html from above. This leaves quite the bad impression, as it makes the page look like an unstructured mess at first glance.

What's up with the bullet point list at the top of the page? I'd understand it if they were links to the specific overloads, but just being text it seems silly to have it there.

Even repeating the ditto wouldn't bother me if it was linked or something...

And ddoc fails to display that sanely too, it shows the outer template, but not the inner function you'd actually use. Thankfully, the examples cover it, but IMO neither ddoc nor ddox actually do a good job on this.

BTW, this is how my doc site renders that:
http://dpldocs.info/experimental-docs/std.algorithm.comparison.among.1.html

I also do a list of overloads, but present them as an accordian-style list of links with an argument summary so you can see at a glance what one might be which. (I'm not 100% in love with my doc here either, but I do like it better than either option on dlang.org. Y'all should start stealing my ideas.)

On Monday, 27 February 2017 at 17:13:24 UTC, Seb wrote:
> A solution for the moment is to point people at the ddoc version, e.g.
>
> https://dlang.org/phobos/std_algorithm_comparison.html#.among

Sure, linking only that would definitely work. — David

On Monday, 27 February 2017 at 15:41:18 UTC, Seb wrote:

>> Is it redditable?
>
> Yes, finally :)

I'm thinking it might be better to do a blog post about it and reddit that instead of posting a link to the docs or this announcement directly. Something describing the implementation and the "writeln transformation magic". Up for it?