Was just looking over these:

https://dlang.org/library-prerelease/std/experimental/checkedint.html
https://dlang.org/phobos-prerelease/std_experimental_checkedint.html
http://dpldocs.info/experimental-docs/std.experimental.checkedint.html

There are a few issues I found with the ddox-based library:

* There's code coloring in inline code, which is a bit distracting. Syntax highlighting should be ideally limited to code blocks.

* For some reason tables have the wrong penalties set up because they hyphenate type names in their left column (e.g. Pro-erCom-pare) which makes all tables look comically bad.

* Sometimes there is a space between "Checked" and "!" when the combination appears in running text. Other type names (such as Abort) also have an extra space following them in running text.

* The second table not only hyphenates its left column awkardly, but also overlays onOverflow on top of text in the next column.

* The headers "Author" and "License" appear even though they have no content. Clearly this could be fixed easily, but my understanding is that a great advantage of ddox over ddoc is its programmability, which should make it easy to make such adjustments.

The ddox documentation with its page-per-artifact approach continues to hold good promise, but it has been one week of work away from becoming the default for literally years now. It really needs some TLC. Who wants to volunteer?


Thanks,

Andrei

On Sunday, 5 March 2017 at 01:47:24 UTC, Andrei Alexandrescu wrote:
> * There's code coloring in inline code, which is a bit distracting. Syntax highlighting should be ideally limited to code blocks.

Yeah, I am coming around to agree with you on that too. I have been playing with my highlight colors for the inline stuff... and I'm not loving it. It *is* sometimes nice though, so before I completely give up, I'm going to try changing to more subdued colors in my generator (dpldocs.info), but I might just remove the inline highlighter too.

I'm actually somewhat happy with the ddoc page style of just bolding it...

> * Sometimes there is a space between "Checked" and "!" when the combination appears in running text. Other type names (such as Abort) also have an extra space following them in running text.

This is a css bug:

table.book tbody a
{
    padding-right: .6em;
}

Firefox tells me it is `style.css` line 1,000. Surely the intent of that was to pad out submodule tables on

https://dlang.org/phobos-prerelease/std_algorithm.html

for example. But the same declaration also affects those ddox links, and some ddoc links as well, such as:

https://dlang.org/phobos-prerelease/std_algorithm_sorting.html

See the chain () space near the top, same thing.


That css rule is WAY too general.

On 3/4/17 10:01 PM, Adam D. Ruppe wrote:
> Yeah, I am coming around to agree with you on that too.

Best. Sentence. Written. In. A. Forum. Ever.

> This is a css bug:
>
> table.book tbody a
> {
>     padding-right: .6em;
> }
>
> Firefox tells me it is `style.css` line 1,000. Surely the intent of that
> was to pad out submodule tables on
>
> https://dlang.org/phobos-prerelease/std_algorithm.html
>
> for example. But the same declaration also affects those ddox links, and
> some ddoc links as well, such as:
>
> https://dlang.org/phobos-prerelease/std_algorithm_sorting.html
>
> See the chain () space near the top, same thing.
>
>
> That css rule is WAY too general.

A pull request for "the competition" would be very much appreciated! I can't tell a general css rule from a sergeant css rule.


Andrei

On Sunday, 5 March 2017 at 01:47:24 UTC, Andrei Alexandrescu wrote:
> * For some reason tables have the wrong penalties set up because they hyphenate type names in their left column (e.g. Pro-erCom-pare) which makes all tables look comically bad.

I see what happened here too: ddox detected "Abort" to be an in-scope name and tried to wrap it in a `<a href...>` link tag... but it was already a link thanks to the `$(LREF)` macro.

So it illegally nested a link inside a link, which the browser interpreted as two adjacent links... and both got that padding-right from the rule I quoted in my last email, thus getting some blank space on the first row.

Fixing the css bug would help the appearance, but ddox should ideally detect if the word is already a link, and not link it again. (My generator does this, but it also works as a context-aware DOM instead of a string macro substitution engine so it was very easy for me. I doubt it will be quite as easy a fix in ddox.)

> * The second table not only hyphenates its left column awkardly, but also overlays onOverflow on top of text in the next column.

The hyphenation is a major disaster, I'd remove that entirely and let the table reflow itself naturally. The left column shouldn't be broken up into lines at all, that kills the readability, and there's plenty of space for it to simply expand to fit the contents.

IIRC, ddox does it because dlang.org used to do it with dog-slow javascript, but really it just shouldn't be done at all.

On Sunday, 5 March 2017 at 03:14:14 UTC, Adam D. Ruppe wrote:
> So it illegally nested a link inside a link, which the browser interpreted as two adjacent links... and both got that padding-right from the rule I quoted in my last email, thus getting some blank space on the first row.


On second thought, yes, ddox shouldn't output invalid HTML if it can help it, but this is actually an antipattern I see a lot in Phobos and hate:

$(D $(LREF Abort)))

That's an unnecessary repetition! If it is an LREF in a D source file, then you *already know* it is a D symbol, so the `$(D)` macro is redundant anyway.

I'd simplify that to just be `$(LREF ...)` in all cases it appears in the Phobos source, and then if you want it to be styled in the monospace font, do a css rule for *that*.

so while ddox could be better, I take back blaming it.

On 3/4/17 10:19 PM, Adam D. Ruppe wrote:
> $(D $(LREF Abort)))

A great point, yah this should be never encountered. A referenced symbol is always in code font. Where's the PR? :O) -- Andrei

On Sunday, 5 March 2017 at 03:13:46 UTC, Andrei Alexandrescu wrote:
> A pull request for "the competition" would be very much appreciated!

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

that should be an improvement, though I didn't actually test it... is there an online preview for that?

On Sunday, 5 March 2017 at 03:38:49 UTC, Andrei Alexandrescu wrote:
> On 3/4/17 10:19 PM, Adam D. Ruppe wrote:
>> $(D $(LREF Abort)))
>
> A great point, yah this should be never encountered. A referenced symbol is always in code font. Where's the PR? :O) -- Andrei

On the closed list, e.g.:

https://github.com/dlang/phobos/pull/5185/commits/c092ce4fcd9e9a45961c41cf44676e76319b9c14

Phobos is full of the $(D $(LREF Foo)) "pattern".

On Sunday, 5 March 2017 at 04:26:01 UTC, Seb wrote:
> https://github.com/dlang/phobos/pull/5185/commits/c092ce4fcd9e9a45961c41cf44676e76319b9c14

Ah, I actually commented on that one too! Yeah, neither $(D) or `` is desired on those. LREF alone should do it. (or $(D) alone does it on ddox and adrdox, but I prefer LREF regardless, it gives the most semantic meaning, and working in ddoc too is just a nice bonus)

> Phobos is full of the $(D $(LREF Foo)) "pattern".

Yeah, I know. That's one of the reasons why the diff between master and my dpldocs fork is now over 5,000 lines long.

We should be able to automate that replacement though as a separate pr and bring my diff down a bit in size. but i need to get to bed.

On Sunday, 5 March 2017 at 01:47:24 UTC, Andrei Alexandrescu wrote:
> The ddox documentation with its page-per-artifact approach

Still not sold on this :/

I guess it comes down to preference, but I don't see the advantage of splitting up the docs across a ton of different pages.

I've also enumerated some of my gripes with the current ddox pages here: https://github.com/dlang/dlang.org/pull/1526#pullrequestreview-23296238