Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use distinct styles for note lists and label lists #1209

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

nevans
Copy link
Contributor

@nevans nevans commented Nov 15, 2024

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

Additionally, this PR:

  • Sets the dt line-height to match main p. Otherwise, the dt has a larger line-height than the p tag inside the dd, which causes the second line to have the same indentation as the first but different from the third. IMO, the second line and every line after it should share the same indentation.
  • Adds closing </dt> tags, in order to avoid any whitespace at the end of the dt text node.
  • Adds commas between note list terms (which is why we need to avoid whitespace after the dt text).

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

As a default for all description lists, the original "label" style is
more readable.

This is slightly different from the original `label` dl though:
* slightly increased left margin for `dd` (to 1em)
* removed right margin on `dd`
* removed `dt` bottom margin and `dd` top margin, to reduce the gap
  between the term and its description (to only the standard line-height
  gap).
Unlike the original note list styles, this version sets the line-height
for all `dt` elements to be the same as the `p` elements contained
inside the `dd`, so that the second line has the same indentation as all
subsequent lines.
Without the closing tags, the dt elements contain whitespace after the
text.  This normally isn't a big deal, but it messes some things up,
e.g: using `::after` and `content: ", "` in the stylesheets.
@nevans
Copy link
Contributor Author

nevans commented Nov 15, 2024

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 nevans changed the title Use different styles for note lists and label lists Use distinct styles for note lists and label lists Nov 15, 2024
@nevans
Copy link
Contributor Author

nevans commented Nov 15, 2024

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
Copy link
Contributor Author

nevans commented Nov 18, 2024

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

Label list and note list styling should be different
1 participant