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