It would be nice if the devmanual and wiki had the same appearance, as well as any other Gentoo documentation. I am mostly talking about looks, CSS not the actual code. I understand the devmanual is not using HTML5, and thus is not using the <var> tag for variables, but the <code> tag instead. In the wiki <code> looks the same, but <var> shows up in italics. If you have a sentence with both a variable and something italic in the sentence or paragraph. It is difficult if not impossible for the reader to visually make a distinction. I created a Wiki example page showing this that was removed for some reason. I personally like how variables stand out in the devmanual with the gray background. Not to mention if a variable is in a sentence with one or more words in italic. You know what is a variable and what is just italic text. My opinion aside I just would like it to be consistent. I would assume the devmanual to look as it does for a reason. Even with <var> not being used. They could have created a var and code class for the <code> tag or just a var class. For what ever reason that was not done. Thus I assume they wanted variables to stand out in the devmanual as they do. It would be nice if the Wiki was the same, or vice versa. Either way just consistent in appearance, and easy for the reader to know what they are reading about and what is what. For reference on looks, specifically variables in sentences. https://devmanual.gentoo.org/ebuild-writing/variables/index.html When in italic they kinda get lost https://wiki.gentoo.org/wiki/Java_Developer_Guide I am not saying <code> tag should be used in place of <var>. Variables should be in <var> not <code> But CSS can control how <var> looks. Maybe it does not have to look like code, but something so it stands out.
The handbook also has the same format as the devmanual. In this link there are several paragraphs with words in Italics that are NOT variables. This is exactly what I am talking about. How does the reader know those are not variable, if any single word in Italics could be a variable. It is confusing, thus the <var> tag should have more styling than just Italics, to make it stand out more and differentiate from regular emphasized words in Italics. Speficially in "Definition of a USE flag" is a perfect example. https://wiki.gentoo.org/wiki/Handbook:X86/Working/USE There is a variable USE, but then also with, without, and will in Italics as well. Are with, without, and will variables? They look just like USE in that paragraph. If USE was not in all upper case it would be more confusing. Which a variable could be lower case.
This is a great example. You cannot tell a visual difference between em and var tags when reading the rendered text. while its clear N is a variable it almost seems as if the word "least" proceeding the variable N could be a variable as well. https://www.w3.org/wiki/HTML/Elements/var Even clearly if you just look at the image, rendered text https://www.w3.org/wiki/File:Var01.png I think that is why the w3 says the typical rendering is Italic but is not mandating all browsers render in Italics. http://www.w3.org/TR/html-markup/var.html Now Code on the other hand has no styling other than monospace. That it shows up on the devmanual, handbook, and wiki with a gray background is a pure choice. http://www.w3.org/TR/html-markup/code.html https://www.w3.org/wiki/HTML/Elements/code Mediawiki by default does not do the gray background on <code> tags https://www.mediawiki.org/wiki/Help:Formatting Thus the gray background is a Gentoo styling of the <code> tag. I think for consistency <var> tag should be rendered the same, with the same gray box/background. Though it could be another color if <var> tags are used next to <code> tags to differentiate. The same issue trying to be prevented by styling the <var> tag so its not just Italic :)
(In reply to William L. Thomson Jr. from comment #2) > Thus the gray background is a Gentoo styling of the <code> tag. I think for > consistency <var> tag should be rendered the same, with the same gray > box/background. Though it could be another color if <var> tags are used next > to <code> tags to differentiate. The same issue trying to be prevented by > styling the <var> tag so its not just Italic :) read: "It's fine that <var> looks like <code> but not like <em>" Yeah, no. As you were already told, your suggestions to make things appeal to your liking do not improve our markup's presentation. Introducing further formatting ("another color") is also not an improvement. Too much formatting distracts from content rather than supporting it.
var tag/element has been around for 20yrs since HTML 2.0, and has been styled as italics since then. Despite such hardly anyone is using that tag/element but now the Gentoo Wiki must... Way to stay current! November 1995 Hypertext Markup Language - 2.0 https://tools.ietf.org/html/rfc1866#section-5.7 I, CITE, EM, VAR, ADDRESS, BLOCKQUOTE { font-style: italic } http://www.w3.org/TR/REC-CSS1/ Also why bother with syntax highlighting at all if "Introducing further formatting ("another color") is also not an improvement. Too much formatting distracts from content rather than supporting it." is true? Why have colors at all? Why does code have a gray box? It does not come as such per the spec.
