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.

Sign up for GitHub

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

Jump to bottom

rustdoc: kbd style rules #46900

Closed
hellow554 opened this issue Dec 21, 2017 · 23 comments
Closed

rustdoc: kbd style rules #46900

hellow554 opened this issue Dec 21, 2017 · 23 comments
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@hellow554
Copy link
Contributor

Hi everyone,

I documented a struct which uses keyboard commands during runtime to do something and I noticed that it looks not as nice as it could be, so I looked around and compared different kbd styles on the internet.
I compare here the github style (A), Stackexchange and Bootstrap (v4)

compare

Which of these styles do you prefer? I would go with the github style, because it's looks nice and clean without any padding. Maybe one could increase the font size.

I would also do a PR, but I wanted to discuss the style before I do that.

So, what are your thoughts? Do you have any different style in mind? To which elements should the rule apply? To all <kbd> tags or just tags inside a docblock?
@GuillaumeGomez
Copy link
Member

What prevents you to add your own style in your crate doc? Because I'm not sure to understand why we'd want that...

@GuillaumeGomez GuillaumeGomez added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools labels Dec 21, 2017
@GuillaumeGomez
Copy link
Member

cc @rust-lang/docs

@steveklabnik
Copy link
Member

I also prefer the github style.

@GuillaumeGomez to me, this is a regular old HTML element; we should give it a decent style.

@QuietMisdreavus
Copy link
Member

👍 for the github style.

@frewsxcv
Copy link
Member

github style looks most like a keyboard key to me, so i'd be favor of that too

@hellow554
Copy link
Contributor Author

Thank you for your responses <3 what about the rule? Every <kbd> tag or just the ones inside a docblock ?

@QuietMisdreavus
Copy link
Member

I'd say to make it every <kbd> tag, so we can also change the ? help menu to use them as well.

@steveklabnik
Copy link
Member

steveklabnik commented Dec 21, 2017 via email

@hellow554 hellow554 mentioned this issue Dec 22, 2017
Merged
@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Dec 22, 2017 •
edited
Loading

I extend a bit my statement: I'm opposed to this add because it'll be used in too few cases to be interesting to grow the CSS files (I could bet on maximum 5 people, which is just way too low). It doesn't bring anything useful enough to justify any new content. Please remember that new content means more maintenance.

Adding a CSS rule in your own doc crate is far easier and better for everyone in most cases. If we add such a style for an element which is almost never used, should we add a style for every HTML tag as well? Of course not! This is way too specific and it's up to crates' owners, not to rustdoc.

cc @rust-lang/docs

@hellow554
Copy link
Contributor Author

I may understand your concern, but do not share your opinion.

A tag is just a tag, and kbd should be used to represent input from a keyboard and for that it should be visualized as such. It's not about adding bloat to the css, but to give a nice visual hint to the reader, that this is a keyboard input.

@QuietMisdreavus
Copy link
Member

I already mentioned a place where rustdoc can use a <kbd> style for itself - the help menu. Right now it's skinning <dt> to get it, but it can move to use <kbd> tags and get a better style for it if we add it.

@GuillaumeGomez
Copy link
Member

If the PR does the switch (aka removing dt tag and style). Then it's good for me. As long as it's used by rustdoc, no problem.

@hellow554
Copy link
Contributor Author

hellow554 commented Jan 15, 2018 •
edited
Loading

As said, sorry for the late response, christmas, new years eve, vacation, ...
Nethertheless, I stumble upon a problem:

unbenannt
As you can see, the +/- section looks a little bit weird, because it's not 1char wide, but 3.
How to deal with this? Align all of the other parts a little bit to the right? Any other recommendations?

@GuillaumeGomez
Copy link
Member

As said, sorry for the late response, christmas, new years eve, vacation, ...

Sure, no problem. Hope you enjoyed it. :)

Nethertheless, I stumble upon a problem:

Try to move all "keys" a bit to the right so all the column seems centered. And add a bit of margin to the right of the "+/-" keys please.

@hellow554
Copy link
Contributor Author

hellow554 commented Jan 15, 2018 •
edited
Loading

I had to change the overall width of the #help box, because else wise the last line would break. I changed the height to auto (can revert that, but I thought it looks nicer) and added inner padding to the dt section.

Which one do you like more? (center or right aligned)

unbenannt

@steveklabnik
Copy link
Member

steveklabnik commented Jan 15, 2018 via email

@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Jan 16, 2018 •
edited
Loading

I have a slight preference for the second one.

What about you @QuietMisdreavus?

@QuietMisdreavus
Copy link
Member

I think i like the second one (the centered one) a little more.

@hellow554
Copy link
Contributor Author

hellow554 commented Jan 16, 2018 •
edited
Loading

One could also split the + and - keys into different lines

+ Expand all sections
- collaps all sections

And we wouldn't have the problem with different width of dt tags

@GuillaumeGomez
Copy link
Member

@hellow554: Indeed, great suggestions!

@hellow554
Copy link
Contributor Author

hellow554 commented Jan 17, 2018 •
edited
Loading

Latest commit makes it looks like this, I hope you like it :)

unbenannt

@GuillaumeGomez
Copy link
Member

Yep, looks great! With this design: 👍

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Jan 19, 2018
@GuillaumeGomez
Rollup merge of rust-lang#46938 - hellow554:rustdoc-kbd-style, r=Guil…
6e9cbac 
…laumeGomez

add kbd style tag to main.css in rustdoc

Added css style for kbd tags so they actually look like keys.
Result preview and discussion was going on in rust-lang#46900 .
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Jan 20, 2018
@GuillaumeGomez
Rollup merge of rust-lang#46938 - hellow554:rustdoc-kbd-style, r=Guil…
fe811eb 
…laumeGomez

add kbd style tag to main.css in rustdoc

Added css style for kbd tags so they actually look like keys.
Result preview and discussion was going on in rust-lang#46900 .
@jkordish jkordish added the C-enhancement Category: An issue proposing an enhancement or a PR with one. label Jan 31, 2018
@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Feb 4, 2018 •
edited
Loading

It got merged so it can get closed now.

For reference: #46938

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@steveklabnik @jkordish @frewsxcv @hellow554 @GuillaumeGomez @QuietMisdreavus