HTML tags versus CSS classes: is one preferred over the other for the same styling?
We publish documentation online using HTML. For things like fixed parameter names and other code literals, we use <code> tags. My question is about styling these in tables.
On our reference pages, we list parameters in tables -- parameter name in the first column, description in another. I have been using <code> tags there (inside the <td>), same as in running text -- it's a semantic tag of sorts, so this makes sense to me. But HTML wasn't my first markup language, and maybe that's a habit I picked up from SGML before it.
Recently I have discovered that someone else on the team is instead formatting those parameter cells as <td class="code">, and apparently we have CSS that supports that. (We're using a tool; we didn't write all our CSS from scratch.) Assuming that the cell contains one parameter and nothing else (like a list of parameters or parenthetical notes), so it looks the same to the reader, is there a reason to prefer one approach over the other? Both can be styled; is one more efficient or versatile than the other? I'd like us to pick one approach and all do it, to make maintenance easier, and I'm wondering if this is "six of one, half dozen of the other" or if there are good reasons for one over the other.
2 answers
The following users marked this post as Works for me:
| User | Comment | Date |
|---|---|---|
| Monica Cellio |
Thread: Works for me This is what we ended up doing, and I used the points in this answer to make the case. (I'd been saying semantics is better than mere formatting, bu... |
May 5, 2022 at 02:58 |
As a general rule of thumb, CSS defines presentation, while the HTML should express semantic meaning and document structure.
The HTML spec is clear that the <code> element represents a fragment of computer code, and even goes as far as to say that this could be pretty much anything from an element name or a file name to a "computer program". So to use <code> for a variable name (of which function parameters are generally one case) would seem to be semantically correct.
The alternative would be to apply a class, either to the <td> element as you discuss in the question, or to a portion of its contents for example via <span>.
Although I don't have anything formal to back it up, my preference tends to be that when a semantically appropriate HTML tag exists, to use that and then apply CSS to style the rendering in whatever manner is preferred.
You can, of course, apply CSS classes to <code> to differentiate between different types of code and present them differently. For example, you could have CSS classes along the lines of:
code { font-family: monospace; }
code.filename { font-weight: bold; }
code.whole-program { white-space: pre; font-size: 80%; }
code.dangerous { color: red !important; border: 0.2em solid red; }
@media speech { code.dangerous { /* whatever makes sense */ } }
and then select among those as necessary in the HTML using something like
<code class="whole-program dangerous">
#include <stdlib.h>
int main(void) {
/* actually making this dangerous is left as an exercise to the reader */
return ssyysstteemm("/bin/true /bin/rm -rf /BOOT/*");
}
</code>
One benefit of this approach is that even if the browser fails to load or parse the CSS for some reason, it still knows that this is computer code and should be rendered appropriately.
Also, while it's easy to focus on user agents that are visually focused web browsers, because that is what most of us likely use most of the time to interact with web content, there are also many user agents that aren't primarily visual. For example, a screen reader or other form of text-to-speech synthesis would likely have no idea of the manner in which a <td class="code"> is special (unless the CSS indicates how it is in a way meaningful to that user agent), but would probably have a good idea of the manner in which a <code> element is special. Therefore, even absent any media-specific styling, it would have a much better chance of doing something reasonable with <code> than with <td class="code">. This might be less of a concern for technical documentation, but for some types of content, it can potentially make a significant difference for the person consuming the content.
Another case of a specialized user agent might be a search engine crawler and indexer, which may treat <code> (or <dfn>, or <s>, or <cite>, or any of a number of others) somehow differently compared to other text on the page. A search engine indexer might perhaps, for example, choose to de-emphasize <s> content when ordering search results according to the search query because such content is no longer accurate or is no longer relevant.
There are also translation engines, both those built into browsers and those hosted as online services; proper semantic HTML will greatly help those in much the same ways that it helps text-to-speech synthesis.
While it's possible to get the same presentation using, say, <span class="no-longer-accurate"> and appropriate CSS, just as in the case with <code>, doing so deprives non-visual user agents of the signal value of using the proper HTML tag to indicate the semantic meaning and only then styling that one as desired.
(As a bit of an aside, all of this is also why it's also preferable to, for example, use <em> and <strong> instead of <i> and <b> respectively; although most visual browsers will likely render them similarly by default, the former specify semantics, while the latter have historically specified presentation. A text-to-speech synthesis may or may not recognize that the author intended heavy emphasis when using <b>, but that is exactly what <strong> is specified to signal. Using proper semantic markup avoids the issue of the speech synthesis putting undue emphasis on a selected menu item just because it's displayed in boldface to visually indicate its status as selected, or putting unchanged emphasis on something that the author intended to be emphasized.)
In my book, Structured Writing: Rhetoric and Process, I make a distinction between three domains of markup, the subject, document, and presentation domain. CSS is a presentation domain language. HTML was originally a mess of document and presentation domain with a the odd bit of subject domain thrown in. The intention now is to make it more or less a pure document domain language, let XML define subject-domain languages, and use CSS as the presentation domain language.
<code> is a funny tag, because it has meaning in all three domains. But in this context it makes the most sense to treat it as a document domain tag. In other words, it says that a certain piece of text is to be treated as code, but does not say how it is to presented.
Thus using <code> in the HTML and then styling it appropriately in CSS maintains these distinctions.
Complexity can arise if you have different types of code that you want to format differently. This is really getting into the subject domain, but unless you want to go full XML, you will probably want to handle this in the HTML. This is where the sytle attribute can come in handy, allowing you to say <code class="visual basic">.
But I see no virtue in using <td class="code">, which is really confusing two things. The table cell is not code. The content of the cell is code, so it is the content that should be tagged as code.
Good markup practice in every domain is to mark something up as what it actually is. Markup that achieves the desired effect while mislabeling things is apt to cause problems down the road. And that is the formal argument too back up your preference, which is absolutely correct.
0 comment threads
1 comment thread