Italicizing non-literal syntax?

[paroche]

How about, when showing syntax like:

node.append(...nodes or strings) – append nodes or strings at the end of node,
node.prepend(...nodes or strings) – insert nodes or strings into the beginning of node,

that "node" (in this case), or whatever syntax is not literal, that is, that stands for some general type of thing, be put in italics, i.e., in this case, to have instead:

node.append(...nodes or strings) – append nodes or strings at the end of node,
node.prepend(...nodes or strings) – insert nodes or strings into the beginning of node,

(From: https://javascript.info/modifying-document)

I think that would make the meaning of the syntax clearer. Also, this is what MDN does in their Syntax descriptions, e.g.:

element.appendChild(aChild);
https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild

This would also address some of my earlier concerns with the use of "str", "array", "obj", etc. from a couple months ago.

[paroche]

Or does that not work when entering code? Let me see:

attempt 1: node.append...

attempt 2: _node_.append....

Hmm. Seems to be hard to get them to work nicely together, to mix italicized and unitalicized in code block. Understandable, I guess, <code> mode being literal and unformatted and all. But maybe there's a nice elegant way?

[iliakan]

Indeed, making things italic isn't a very good idea, because it doesn't look good.

Is there a real need and confusion here?

[paroche]

I don't see why it has to not look good. It doesn't seem to work with backticks, but in regular HTML, having, for instance, <code><var>elem</var>.getElementById</code>, looks like this:

elem.getElementById

Which I think looks fine, and is also the way, for instance, Mozilla represents such things on their MDN web docs site.

And yes, I think it really helps to have the variable/shorthand portion of the code easily distinguished from the literal syntax part, especially when the syntax is being encountered for the first time and/or the reader is not accustomed to the conventions being used for variables and shorthand expressions. And that not having that can lead to confusion. This was, for instance, the case when I was having issues some time back with the use of 'var', 'arr', 'obj', etc. in code examples. I figured it out, but it slowed me down.

[Zearin]

I strongly agree with the previous comment. I think <var> is one of the most under-used elements in HTML, and it is incredibly helpful for cases like the above.

Furthermore, although I also think italics are fine, they are just a default styling. Using <var> means you can style it with CSS like any other element. You can still use <var> to distinguish the “non-literal” syntax from its surroundings, but you could do it with color, font-weight, a border-bottom: 1px dashed #eee, or whatever else you want.

It’s flexible—and semantic! :-)