Label list and note list styling should be different

[nevans]

In #1157

• Enhance table and list styling for improved readability

First off, I love the attention that's been given to rdoc over the last several months. It's looking pretty nice! I'm very much looking forward to the next release. 🤩

The only new issue I can think of is this: label lists and note lists now render the exact same way. Was that intentional? IMO, it's useful to have the two different definition list styles, even though I'd love for one or both of them to be updated from what they were in v6.7.0.

Here's what they look like in v6.7.0:

And here's what they look like today at https://ruby.github.io/rdoc/ExampleRDoc_rdoc.html

Obviously, we can apply our own stylesheets, but IMO they should be slightly different out-of-the-box. The float style that was previously used only for "note" lists is the one that is now used for both.

Personally, between the two I like the default styling on "note" lists less than v6.7.0's "label" lists. IMO, the left margin's unindentation after more than two lines of text is visually jarring.

[nevans]

If I have time, I'll try to submit a PR with updated styles for both lists soon. But what do you think? Do you agree that they should be styled differently? Should they just be returned to their 6.7.0 styles, or should they be updated to something (subjectively) nicer?

[drbrain]

I don't think they need to look different when presented as HTML.

These are two types of markup that allow you to choose the most convenient way to create an HTML description list based on the keys.

[drbrain]

… for example, describing a set of constants like Foo::BAR, Foo::BAZ with the [Foo::BAR] markup is more visually apparent than the Foo::BAR:: markup (someone else might wonder if the trailing :: is a mistake).

[nevans]

@drbrain I suppose that's fair. I can see that it's useful to have alternative representations for the exact same thing, with the only distinction that one reads more nicely in the source comments. And I do appreciate that rdoc has prioritized nice looking human-readable source comments over syntax-heavy comments-metadata. Also, I hadn't realized (until your comments, when I tried it out and looked at the source) that ri already formatted them both the same (and always has?).

That said, since I've mostly focused on making the HTML presentation look nice, I'd definitely conceptualized them as intentionally different in semantics, presentation, or both. Both created description lists, but the classes and styling were different. The classes are still different, so I can still apply my own styles.

Anyway, I do think that:

1. There's a subtle but useful semantic distinction between the two types. It's not hugely important, but it's maybe nice to have.

2. It's useful to have two different description list presentations.

3. Following from 1 & 2, maybe ri should also format them each slightly differently. 😉

4. But, maybe all of the above is less important than the goal you gave: two different ways to express the same thing, based on which is most convenient for the content.

   If we are going to continue styling them the same, IMO we should use to the original "label" presentation style. I've always found the "note" style's bouncing float left margin to be jarring, although that can be fixed! Even if it is fixed, I still think the old "label" style is more appropriate in most contexts. It's the style that ri uses for both types of description list.)

I've already been adding my own stylesheet and monkey-patching Markup::ToHtml to override list_type == :NOTE and LIST_TYPE_TO_HTML[:NOTE] to make them even more distinct (with code I originally copied from hanna). When I saw the style changes from #1157 and other commits, I was going to convert my ToHtml changes into pure CSS, and update it to fit in better with the rest of the updated darkfish theme. And obviously I can still do that. But losing the distinction seemed like it may have been more oversight than intentional. (Any thoughts from @st0012?)

(Side note, I'd somehow missed that HTML 5 renamed dd from "definition list" to "description list"... it makes sense, but I'd missed that change until reading your comment. 🙂)

[st0012]

It's indeed an oversight in my change cause I didn't even realize there is such a difference. But looking at Eric's comment, it also doesn't feel like an intentional distinction in the first place?
Anyway, if you want to change the style back, I'm open to accept it 🙂

[nevans]

@st0012 @drbrain Any thoughts on #1208, #1209, and #1226?

[drbrain]

I've not been active in Ruby development for some time so I'm not sure I'm the best person to weigh in on what's best, especially not on what the community wants

I do like the ::after style to add the comma, it's a nice touch