www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - A few notes on the ddox-based documentation

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Mar 04 2017
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Mar 04 2017
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Mar 04 2017
parent Adam D. Ruppe <destructionator gmail.com> writes:
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?
Mar 04 2017
prev sibling next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Mar 04 2017
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Mar 04 2017
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Mar 04 2017
parent reply Seb <seb wilzba.ch> writes:
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".
Mar 04 2017
parent Adam D. Ruppe <destructionator gmail.com> writes:
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.
Mar 04 2017
prev sibling next sibling parent Jack Stouffer <jack jackstouffer.com> writes:
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
Mar 04 2017
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Sunday, 5 March 2017 at 01:47:24 UTC, Andrei Alexandrescu 
wrote:
 http://dpldocs.info/experimental-docs/std.experimental.checkedint.html

 * There's code coloring in inline code, which is a bit 
 distracting. Syntax highlighting should be ideally limited to 
 code blocks.
I just tried removing the syntax highlighting for inline D stuff on my site, you might have to refresh... I do think I'm happier with it that way.
Mar 05 2017
prev sibling next sibling parent =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 05.03.2017 um 02:47 schrieb Andrei Alexandrescu:
 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.
There is an option in DDOX now. Still have to open a PR against dpldocs.
 (...)

 * 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.
Has this been solved by now, or is there still an example for this? Apart from not displaying it when it's not there, it should also not be displayed as separate sections. Current DDOX renders it as a small table by default, but we could also move it below the comments section as a page footer. There are also some more improvements in the latest version: - Search result ranking algorithm has been improved - Functions in overview tables now show their argument names (kind of what the cheat sheet otherwise does) - The types for template value parameters is now cross linked - The prototype section now appears between the short and the long description so that the most important information is at the top - Links to package.d modules are now part of the package entry in the navigation tree - instead of a separate "Package members" child entry - Documentation groups (ditto) with mixed kinds of symbols are now aggregated (the description is rendered just once - The module part of fully qualified names in text sections is automatically stripped, with the full name still appearing as a tool tip - not so important for Phobos, which relies on the *REF macros - Some wrong heading levels have been fixed We should also discuss the possibility of using Diskuto [1] as the comment engine. [1]: https://github.com/rejectedsoftware/diskuto
Mar 23 2017
prev sibling parent =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 05.03.2017 um 02:47 schrieb Andrei Alexandrescu:
 * 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.
https://github.com/dlang/dlang.org/pull/1613
Mar 23 2017