[Markdown] Decide what to do about <var>

[wbamberg]

We haven't had a conversation about this one yet. We use <var> a lot on MDN. Since there's no exact equivalent of this in GFM we need to know how to handle it.

On MDN we:

• often use it inside <code> in the description lists for parameters and similar:

  content/files/en-us/web/javascript/reference/global_objects/function/apply/index.html

  Line 28 in 52d05d5

  <dt><code><var>thisArg</var></code></dt>

  .

• often use it inside code blocks:

  content/files/en-us/web/javascript/reference/functions/method_definitions/index.html

  Lines 23 to 25 in 52d05d5

  	<pre class="brush: js">const obj = {
  	get <var>property</var>() {},
  	set <var>property</var>(<var>value</var>) {},

• sometimes use just in prose:

  content/files/en-us/web/javascript/reference/global_objects/promise/any/index.html

  Line 56 in 52d05d5

  <li>If an empty <var>iterable</var> is passed, then the promise returned by this method is rejected synchronously. The rejected reason is an <code>AggregateError</code> object whose <code>errors</code> property is an empty array.</li>

It is my understanding that in Yari, inside code blocks (<pre class="brush">), any internal markup is removed, so removing it from these in conversion to Markdown seems like an obvious choice.

For the other usages, we have some choices.

1. Replace <var> with <em> by mapping <var>thing</var> to GFM *thing*. This would need special handling for <code><var>thing</var></code>, to generate *`thing`* instead of `*thing*`. We already do this though for <code><strong>thing</strong></code>, so I guess that wouldn't be too hard.

2. Remove <var> when it's inside <code>, otherwise replace it with <em>.

3. Remove it in all cases. I think this would look odd in cases where it's on its own.

4. Keep the HTML <var> (I don't think we should do this).

Other opinions?

[hamishwillee]

I like 2, but would also mention "pre".

Remove <var> when it's inside <code> or <pre>, otherwise replace it with <em>.

Re "3" I don't think they look "odd" but IMO the highlighting is there in the first place because it makes the docs more useful/readable. FYI in GFM can be either done as _italic_ or *italic* (I prefer underscore because asterisk gets overloaded for bold and bullets).

[wbamberg]

Yeah, I like 2 best as well but would be OK with 3.

[Blakelist7]

@wbamberg Hey, can I help with the issue?

[wbamberg]

Hey @Blakelist7 ! Not really, this is more of a "decide what we are going to do" type of issue. But I wonder if you would like to have a look at #5438 - this is an issue where I'd love to have some help.

[sideshowbarker]

I’m going ahead and taking the liberty of closing this, since it seems some decision must have ended up getting made about this prior to when the markdown conversion got completed last October. But if I’m missing something and there’s some reason this needs to be kept open, let’s re-open it.