search

ruby / rdoc

RDoc produces HTML and online documentation for Ruby projects.
https://ruby.github.io/rdoc/
Other
843 stars 438 forks source link

Label list and note list styling should be different #1199

Open nevans opened 2 days ago

nevans commented 2 days ago

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: Screenshot 2024-11-05 at 12-33-04 rdoc 6.7.0 definition lists

And here's what they look like today at https://ruby.github.io/rdoc/ExampleRDoc_rdoc.html Screenshot 2024-11-05 at 12-34-17 rdoc new definition lists

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 commented 2 days ago

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 commented 2 days ago

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 commented 2 days ago

… 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).