Skip to content

rustdoc: kbd style rules #46900

Closed
Closed
@hellow554

Description

@hellow554
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?

Activity

GuillaumeGomez

GuillaumeGomez commented on Dec 21, 2017

@GuillaumeGomez
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...

added
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
on Dec 21, 2017
GuillaumeGomez

GuillaumeGomez commented on Dec 21, 2017

@GuillaumeGomez
Member

cc @rust-lang/docs

steveklabnik

steveklabnik commented on Dec 21, 2017

@steveklabnik
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

QuietMisdreavus commented on Dec 21, 2017

@QuietMisdreavus
Member

👍 for the github style.

frewsxcv

frewsxcv commented on Dec 21, 2017

@frewsxcv
Member

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

hellow554

hellow554 commented on Dec 21, 2017

@hellow554
ContributorAuthor

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

QuietMisdreavus

QuietMisdreavus commented on Dec 21, 2017

@QuietMisdreavus
Member

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

steveklabnik

steveklabnik commented on Dec 21, 2017

@steveklabnik
Member
GuillaumeGomez

GuillaumeGomez commented on Dec 22, 2017

@GuillaumeGomez
Member

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

hellow554 commented on Dec 22, 2017

@hellow554
ContributorAuthor

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

QuietMisdreavus commented on Dec 22, 2017

@QuietMisdreavus
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

GuillaumeGomez commented on Dec 23, 2017

@GuillaumeGomez
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

hellow554 commented on Jan 15, 2018

@hellow554
ContributorAuthor

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

GuillaumeGomez commented on Jan 15, 2018

@GuillaumeGomez
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

hellow554 commented on Jan 15, 2018

@hellow554
ContributorAuthor

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

steveklabnik commented on Jan 15, 2018

@steveklabnik
Member
GuillaumeGomez

GuillaumeGomez commented on Jan 16, 2018

@GuillaumeGomez
Member

I have a slight preference for the second one.

What about you @QuietMisdreavus?

QuietMisdreavus

QuietMisdreavus commented on Jan 16, 2018

@QuietMisdreavus
Member

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

hellow554

hellow554 commented on Jan 16, 2018

@hellow554
ContributorAuthor

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

GuillaumeGomez commented on Jan 16, 2018

@GuillaumeGomez
Member

@hellow554: Indeed, great suggestions!

hellow554

hellow554 commented on Jan 17, 2018

@hellow554
ContributorAuthor

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

unbenannt

GuillaumeGomez

GuillaumeGomez commented on Jan 17, 2018

@GuillaumeGomez
Member

Yep, looks great! With this design: 👍

added 2 commits that reference this issue on Jan 19, 2018

Rollup merge of rust-lang#46938 - hellow554:rustdoc-kbd-style, r=Guil…

Rollup merge of rust-lang#46938 - hellow554:rustdoc-kbd-style, r=Guil…

added
C-enhancementCategory: An issue proposing an enhancement or a PR with one.
on Jan 31, 2018
GuillaumeGomez

GuillaumeGomez commented on Feb 4, 2018

@GuillaumeGomez
Member

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-enhancementCategory: An issue proposing an enhancement or a PR with one.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @steveklabnik@jkordish@frewsxcv@hellow554@GuillaumeGomez

        Issue actions

          rustdoc: kbd style rules · Issue #46900 · rust-lang/rust