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

Docs should use monospace font rather than italics for command syntaxes and help strings #62

Closed
Zarthus opened this issue Jun 14, 2015 · 15 comments
Assignees
Milestone

Comments

@Zarthus
Copy link
Contributor

Zarthus commented Jun 14, 2015

for example: https://docs.korobi.io/channel/commands/removing.html

Usage: .<delcmd|unsetcmd> [-i ]

Should be:

Usage: .<delcmd|unsetcmd> [-i <index>] <name>

And

so to remove the first value of the hit command you could use .delcmd -i 0 hit.

Could similarily become:

so to remove the first value of the hit command you could use .delcmd -i 0 hit.

@jamierocks
Copy link
Contributor

This seems to be an issue with Sphinx as it uses < cite> and not < code>. I will speak about this in IRC as we can change the style from code { -> cite {. this would fix the problem, but preferably we want to see if we can get sphinx to use < code> in the first place.

@jamierocks jamierocks self-assigned this Jun 14, 2015
@bendem
Copy link
Member

bendem commented Jun 14, 2015

as I said, semantic. From the spec: "The cite element represents the cited title of a work; for example, the title of a book mentioned within the main text flow of a document."

@jamierocks
Copy link
Contributor

It's understandable from the above description why it is using < cite>. We wouldn't be going too far of it's definition by using it.

@lol768
Copy link
Member

lol768 commented Jun 14, 2015

I'm not sure how you got to that conclusion :/

is not for quotes per the standard, it's explicitly for the cited title of a work. Example:

<p>The <cite>HTML Living Standard</cite> describes how to use HTML elements correctly.</p>

.<delcmd|unsetcmd> [-i <index>] <name> is not the title of a work. Nor is it a reference to a particular work. It's just some usage information.

Why's it matter, you might ask? We can just style it with CSS and nobody will care!

The meaning of the tag is important for accessibility - people using screenreaders and other assistive technologies. These sorts of software might decide to treat citations differently. Search engines might decide to treat the content inside the tags as references to other works.

@jamierocks
Copy link
Contributor

Eh, I will try get this done ASAP.

@jamierocks
Copy link
Contributor

The thing is - Sphinx has these cool things called code-blocks... the issue is it kind of requires a language.

My guess would be 'bash' if it is supported.

@bendem
Copy link
Member

bendem commented Jun 16, 2015

Doc seems to say you can use none tho

@jamierocks
Copy link
Contributor

Well there we go :D

@jamierocks
Copy link
Contributor

Will fix tomorrow - going to sleep soon

@lol768
Copy link
Member

lol768 commented Jun 16, 2015

bendem to the rescue!

@lol768 lol768 added this to the 1.0.1 milestone Jun 17, 2015
@lol768
Copy link
Member

lol768 commented Jun 17, 2015

Any updates on this one @jamierocks?

@jamierocks
Copy link
Contributor

@lol768 I will start working on this now :D

@lol768
Copy link
Member

lol768 commented Jun 17, 2015

Great!

@lol768
Copy link
Member

lol768 commented Jun 20, 2015

@jamierocks is this fixed? Can this be closed?

@bendem
Copy link
Member

bendem commented Jun 20, 2015

OK, it seems like the solution would be to use .. code-block:: none instead of .. code:: for code blocks. Then styling .highlight pre a bit and all should go along nicely.

@bendem bendem closed this as completed Jun 22, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants