897037 - Use <pre><code> for code blocks, not just <pre>

Status: RESOLVED WONTFIX

(developer.mozilla.org Graveyard :: Editing, defect)

Description

[Chris Mills [:cmills]]

What feature should be changed? Please provide the URL of the feature if possible.
==================================================================================
This is a bit of a semantic nitpick really - When marking up code blocks, I've always used <pre><code>CODE</code></pre>, as I feel it is better semantics. <pre> is for fixed width preformatted text, but not necessarily code, but it is needed for the block level effect you are trying to show, plus it helps differentiate code blocks from inline code items. <code> is needed for the semantics - to unambiguously state that this is a bit of computer code.

We currently use <pre></pre>. Would you have any problems with changing this? Am I being to anal?

What problems would this solve?
===============================
A slight semantic discrepancy.

Who would use this?
===================
everyone writing articles on MDN.

What would users see?
=====================
no difference, although it might improve things very slightly for search engines and screen reader users.

What would users do? What would happen as a result?
===================================================
slight semantic improvements.

Is there anything else we should know?
======================================
no.

Comment 1

[David Walsh :davidwalsh]

The syntax highlighter we are presently using, Prism, requires <pre><code>, so I move that content into a code tag on the client side before highlighting.

Comment 2

[John Karahalis [:openjck]]

I might be mistaken, but I think Chris means using <pre><code> for normal code blocks, even those that are not syntax-highlighted for whatever reason.

Comment 3

[David Walsh :davidwalsh]

All PRE's are syntax-highlighted, with HTML as the default if the language isn't supported.

Comment 4

[John Karahalis [:openjck]]

I might be confused. Chris, does this solve the issue you mention in comment 0?

Comment 5

[Chris Mills [:cmills]]

I hadn't found the syntax highlighter tool ;-) I have applied it to the code blocks on my page, see https://developer.mozilla.org/en-US/docs/Web/Apps/Introduction_to_open_web_apps.

I have looked at the code at runtime, and can now see that the <code></code> tags are applied inside the <pre></pre> tags. So that certainly answers most of my question.

But this does leave one more question - what about code blocks where you don't add syntax highlighting, or where there isn't an appropriate highlight option, for example, the .htaccess line on the referenced page? It would be nice for those blocks to be in <pre><code> too. The easiest way would be to add some kind of "generic" option to the syntax highlight choices, which perhaps just applies some minimal highlighting.

In the long term I reckon we could make this tool a bit more usable/intuitive. It seems to me that the pre button, and the syntax highlight button, are doing largely the same thing, except that the syntax highlighter does a better job (it adds in <pre><code> plus highlighting, not just <pre>)

So maybe we could replace these two with a code block button, which when pressed puts the block inside <pre><code> then reveals syntax highlight options to choose from?

Of course, it is possible that you may want to use <pre> without putting code inside it, but this is unlikely on MDN, and the pre button just makes it look like s code block anyway.

Comment 6

[David Walsh :davidwalsh]

Thank you for the detail Chris!  A few thoughts:

1.  All <PRE> elements are highlighted
2.  If a language is unsupported or not specified, the block gets the very basic Prism highlighting so as to keep the same style as everything else
3.  I like your ideas, though we're slightly at the mercy of CKEditor.  We should bring in :sheppy to see if he has ideas -- he originally asked for our code buttons.

Comment 7

[Chris Mills [:cmills]]

Thanks David. I appreciate that <pre> elements are highlighted anyway, but I was more concerned with the semantics - having <pre><code> is arguably better semantics than just <pre> alone. But I also appreciate the limitations of the 3rd party code, and this is a relatively minor point really. We've got bigger fish to fry ;-)

Comment 8

[Jean-Yves Perrier [:teoli]]

We have several other semantic errors in our pages, but it is rather pointless to fix them as long as we don't have the find & replace feature which was set as a priority last August.

Once we have it, we will be able to fix a lot of these. (More use of <kbd>, <var>, ...).

Once we have the F&R feature we should audit our pages for semantic errors and fix them.

Comment 9

[Chris Mills [:cmills]]

Ok, good to know - thanks J-Y ;-)

Comment 10

[Eric Shepherd [:sheppy]]

I've never personally been a fan of <pre><code>... I've always felt that <pre> means what it says, and any HTML inside should be dumped out into the text rather than parsed. That said, there seems to be a lot of consensus here, so I'm in favor of making this change.

Comment 11

[Eric Shepherd [:sheppy]]

Doesn't our style guide and/or Florian's content test add-on warn against using <code> inside <pre> blocks?

Comment 12

[Florian Scholz (Open Web Docs)]

Yes, mainly because the current syntax highlighter will fail to highlight <pre><code>. Just <pre> works, though.

Comment 13

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.