Correct JavaScript syntaxbox markup

MDN
#1

What’s the correct way to markup the code in JavaScript syntax boxes? I’ve seen lots of different approaches, e.g.:

<var>str</var>.codePointAt(<var>pos</var>)
<em>myMap</em>.get(key);
<var>gen</var>.return(value)

Is em or var preferable? (em seems less technically correct, but it’s present in the editor GUI, which is very helpful.) Also, what items should get italicized?

I did some searching in the MDN guidelines, but didn’t find any info about this.

1 Like
#2

We do not use <var>. We probably should be, but we never have. Any places that do use it actually break rendering, because we do not have styling in place for <var>.

Styling should be applied to anything that the programmer names themselves:

( all the examples here should of course be in <code>, but the forum doesn’t allow it)

  • Variable storing a return value [retValueName = somefunction()]
  • Input parameter name [somefunction(parameter1, parameter2)]
  • Any variable or object instance:

foo = myDocument.setInterval(timer);

And that’s it.

1 Like
#3

Thanks, sheppy, that’s very helpful. I’ll make sure to replace <var> with <em> whenever I’m updating wiki pages in the future.

I suspect that <var> shows up in so many syntax boxes because people will often paste in code from outside of MDN.

1 Like
#4

Thank you! I’m also adding this information to our documentation style guide.

2 Likes
#5

I think we should update the Kuma base stylesheet to style the <var> element with the same style as the <em> element when contained within a <pre> block, otherwise style it like <code>.

#6

Is there perhaps a way to make the MDN editor, or MDN’s CSS styles, deal with <var> and <em> more gracefully?

Given the nature of a wiki, it’s difficult to get everyone on the same page with using one vs. the other. For example, I edited this page, replacing all the <var>s with <em>s, but then a few days later someone else went and did the opposite. Or maybe I just need to lighten up on my perfectionism? :upside_down_face:

#7

Never! :slight_smile: . Seriously though: as long as MDN is a Wiki it’s going to be impossible to make anything consistent, so it’s probably not worth worrying about. I hope that one day it won’t be a Wiki any more, and we’ll spare people from hand-formatting stuff like this.

1 Like
#8

So, unfortunately, it’s a little tricky to do anything about it. Given that we never use <var> for anything, we could consider blocking that from being used in our HTML bleaching filter.

At a minimum, yes, we could at least make it look the way we want it to. But I’m not sure I wouldn’t prefer we just block it outright.

#9

Considering how many pages use it, I’d say it might be easier to either convert it to <em> or convert all <em>s in syntax boxes to <var>.

I prefer option 2.

#10

@exe-boss: I’m curious why you feel that <var> is the way to go. They’re not variables, really. They’re placeholders… I guess that’s similar, but it’s not really the same.

#11

It’s because <var> has semantic meaning that it’s a variable, whereas <em> means that it’s meant to be emphasised:

#12

Sure, but these aren’t variables. I get that <em> isn’t really correct because emphasis isn’t what we’re looking for, but I don’t think <var> is right either.

I personally wish we had a few classes to use, like:

<code class="parameter">paramName</code>
<code class="method">methodName()</code>
<code class="property">propertyName</code>
<code class="type">typeName</code>

And so forth. That would be more… appropriate… to my mind. Not to mention giving us incredible powers when it comes to using CSS selectors to locate keywords of interest.

1 Like