ruby / rdoc

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

Use distinct styles for note lists and label lists #1209

Open nevans opened 1 week ago

nevans commented 1 week ago

In addition to the changes in #1208, this brings back the float: left style, for note lists only. This fixes #1199.

Additionally, this PR:

Note that #1208 removes margin-bottom from dt, which is also necessary for the second indentation to match subsequent lines.

nevans commented 1 week ago

For the screenshot, I added an extra <dt> for every <dd> to demonstrate how that looks in various line wrapping situations.

Screenshot 2024-11-15 at 17-40-13 ExampleRDoc - rdoc Documentation

nevans commented 1 week ago

For what it's worth, here are a few times the styles for these have been updated:

Anyway, this does not mean we need to style them differently by default. If we add the closing </dt> tag and continue to give them different classes, then I can use my own local stylesheets. But I do think it means that I'm not the only one who appreciates having distinct styles for the two list types. 🙂

If this PR is accepted, I'm willing to create a PR for similar styling for ri, so they match.

nevans commented 5 days ago

FWIW, I've experimented with four different styles.

The "label" style restored by #1208:

First described term
  Description starts on a new line below the term and is indented.  Lorem ipsum dolor
  sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore
  et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
  laboris nisi ut aliquip ex ea commodo consequat.
Second described term
Riker Ipsum
  We finished our first sensor sweep of the neutral zone.  Yesterday I did not know
  how to eat gagh. And blowing into maximum warp speed, you appeared for an instant
  to be in two places at once.  They were just sucked into space.  Mr. Worf, you do
  remember how to fire phasers?

The "note" style in this PR:

First described term    Description starts on same line as its term.  Subsequent
  lines are indented by one em.  Lorem ipsum dolor sit amet, consectetur adipiscing
  elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
  minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
  commodo consequat.
Second described term, Riker Ipsum    Indentation levels are independent of the
  length of the terms.  Every description indents only one level.  We finished our
  first sensor sweep of the neutral zone.  Yesterday I did not know how to eat gagh.
  And blowing into maximum warp speed, you appeared for an instant to be in two
  places at once.  They were just sucked into space.  Mr. Worf, you do remember how
  to fire phasers?

Before making these PRs, I was considering a more table-like style for "notes" (e.g. as used by hanna). This can be accomplished with dl by using display: grid. But, while that is nice for some description lists, I think it's less generically applicable. Also, it would've needed extra styling to be responsive to smaller screen widths.

First described term    Definition starts on same line as its term.  All descriptions
                        share the same indentation.  This is easy to achieve with
                        display: grid.  But it does not work well with wide terms or
                        nested lists.  Lorem ipsum dolor sit amet, consectetur
                        adipiscing elit, sed do eiusmod tempor incididunt ut labore  
                        et dolore magna aliqua.
Second described term
Riker Ipsum             I chose to style this so that the description text starts on
                        the same line as the final description term.  Every
                        description indents only one level.  We finished our first
                        sensor sweep of the neutral zone.  Yesterday I did not know
                        how to eat gagh.  And blowing into maximum warp speed, you
                        appeared for an instant to be in two places at once.  They
                        were just sucked into space.  Mr. Worf, you do remember how
                        to fire phasers?

Another reasonable approach would be to mimic how rdoc allows the comments to be formatted, indenting each dd independently, based on its corresponding terms' widths. This still doesn't work well with wide terms or nested lists, and the alternating indentations can be slightly jarring, IMO.

First term    Definition starts on same line as its term.  Each description has its
              own indentation, based on its term(s).  This still doesn't work well
              with wide terms or nested lists.  And I personally find the different
              indentation of each description to be jarring.  Lorem ipsum dolor sit
              amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
              labore et dolore magna aliqua.
Second described term
Riker Ipsum              Indented according to its widest term.  We finished our
                         first sensor sweep of the neutral zone.  Yesterday I did
                         not know how to eat gagh. And blowing into maximum warp
                         speed, you appeared for an instant to be in two places at
                         once.  They were just sucked into space.  Mr. Worf, you do
                         remember how to fire phasers?