# Is there a formatting guide around using code markup that must be followed?

I've taken to when I reference page numbers, using code formatting to make it more evident, but different from normal emphasis. Especially since code formatting isn't really utilized on this SE. It's not been a problem before, but today my post was edited:

https://rpg.stackexchange.com/revisions/27794/2

I wouldn't have really paid attention, except for the comment seemed like an imperative. In the vein of the rule that we don't allow signatures. So I wanted to get clarity on this.

• This discussion seems like a duplicate of meta.rpg.stackexchange.com/questions/1483/…. Anyway, there are no "rules" - I personally could care less if people put rules text in a code block or not, if people edit your responses you can bow to the rep or decide you want to revert if you have a good reason for it. – mxyzplk Aug 9 '13 at 20:39

Code formatting is for code; it is not just a different way to format your text. Don't use it for non-code text. If that means we never use code formatting, so be it. Like all HTML formatting, it actually has a purpose, and using it for non-code text is using it incorrectly.

HTML elements are incredibly meaningful. To you and I, bold text is just thicker, italicised text is just slanted, code text is just a monospace font with a grey background, and they're all just ways of making things look visually distinct. The elements used to produce that formatting, however, mean something different to a visitor's screen reader, a browser trying to handle technical terms or code in special ways, or other machines doing other special things with your HTML markup.

When you appropriate markup for purposes it wasn't intended for, you confuse those machines and give anyone working with them a hard time.

Here's the definition for the element we use for our code formatting (code for inline code, pre for code blocks):

The code element represents a fragment of computer code. This could be an XML element name, a file name, a computer program, or any other string that a computer would recognize.

The pre element represents a block of preformatted text, in which structure is represented by typographic conventions rather than by elements.

Is the text you're supplying either of these? If so, use code markup. If not, don't.

# What do we use then?

Italics and bold! Our italic and bold text are represented by the em and strong elements which also have their own definitions:

### em

The em element represents stress emphasis of its contents. (...)

The placement of stress emphasis changes the meaning of the sentence. The element thus forms an integral part of the content. The precise way in which stress is used in this way depends on the language.

The definition of em then goes on to provide examples of how usage of em can and should change the meaning of a sentence. "Cats are cute animals" means something different to "Cats are cute animals": the former is a suitable statement in a discussion about which animals are cute, the latter is a suitable reply to someone who just asserted they are cute vegetables. The two are not interchangeable without you sounding odd.

### strong

The strong element represents strong importance for its contents. (...) Changing the importance of a piece of text with the strong element does not change the meaning of the sentence.

Note for those who actually use HTML and may be unaware: b and i are still in use and have their own distinct purposes. They aren't deprecated.

## Use MathJax for formulas

Our site nowadays supports MathJax, a derived implementation of $\LaTeX$ formulas, which provides us with a means to have well-laid-out equations. You can implement MathJax inline with $...$ or in its own line, centered, with $$...$$. It can get a bit complex: see the MathJax basic tutorial and quick reference on Math.SE.

So, naturally, these are just two flavours of emphasis. Both will often be read by a screen reader in a different tone of voice to the rest of the text.

Either one works for page numbers; you might prefer italics (YW 212) or just writing your page numbers out with no formatting at all (OW 55); actually using bold may be a bit much visually (YW 209).

You could also use superscriptYW91, since that's a fairly common standard for citations. (In fact, it seems you've used it already!)

• Subscript might also be appropriate for page references. – C. Ross Aug 9 '13 at 12:33
• So, is there a good reason to use code on this site? If there's no valid reason to use it, should we remove it? – corsiKa Aug 9 '13 at 20:30
• Actually, * and ** produce <em> and <strong>, so those are generating semantic HTML as well. There are also plenty of time-tested ways of formatting page numbers in citations that we don't need to invent new ones; MLA and Chicago are both good standards for our site format. – SevenSidedDie Aug 9 '13 at 21:48
• @corsiKa We don't have the option to remove it. But anyway, there are uses: any time we want to tell someone that a piece of text can be used as input to a computer. Since we handle RPG-related software, that can potentially (if rarely) come up if there's a question about, say, editing a character-tracker's configuration files to support a particular RPG. – SevenSidedDie Aug 9 '13 at 21:49
• @SevenSidedDie Oh wow. I checked these recently and thought they produced b/i. Excellent. :) – doppelgreener Aug 9 '13 at 22:33
• And I thought b/i were deprecated, but apparently they gave them unique semantic definitions distinct from em/strong, so TIL something too. :) – SevenSidedDie Aug 9 '13 at 22:43
• @SevenSidedDie Oh, that is true. It also occurs to me that code would be convenient for expressing an algorithm (perhaps an XP formula). Also, as you illustrated in your comment before the one to me, it's useful in explaining markdown syntax!! On the other hand, if it didn't have a use, while it's true that moderators cannot remove it, administrators could if they felt the need. – corsiKa Aug 10 '13 at 2:21
• @corsiKa Using code formatting for a formula is also contrary to its definition—it's neither a computer code fragment nor structure-defined-by-typography. Formulas should just be written in prose formatting. At best, follow the conventions of math texts and put them on a separate line when they're long or the beginning and end need to be clearly marked as separate from surrounding text. – SevenSidedDie Nov 16 '14 at 19:34
• I pfrefer superscript for citations, and I prefer to use a p in frnt of a page reference... And I loath people changing my citation style. Formula have the /$and$\$ codes! – Trish May 1 '18 at 11:10
• @Trish Those are definitely personal writing preferences we ought to respect. – doppelgreener May 1 '18 at 11:28
• @Trish Yeah, I don’t think anyone here would be likely to change your citation styles so long as they don’t do something actively problematic like abusing code formatting. That kind of editing would be rejected, or reverted, if it actually did happen, and I kind of suspect it simply won’t. If it ever does, feel free to revert it, and if there’s any problem (people arguing or edit warring), use flags to alert moderators—but again, probably not going to happen over citation style. Also, note that the comments about math by corsiKa and d7 were from before we actually had MathJax on this site. – KRyan May 1 '18 at 15:50
• @KRyan actually I had to revert like 5 edits to my post due to citation style when I used supertext and someone changed to inline citation. It was by people who were above peer review necassary level. I just reverted with a nasty comment to leave the fingers off my citation style. – Trish May 1 '18 at 16:49
• @Trish I recommend rolling back but not leaving nasty comments, personally. Leave comments by all means asking them to leave your writing style in place. As a general rule of thumb: If you ever feel like you want to be nasty to someone I'd prefer you escalate a flag to moderators asking us to step in and look at the situation, rather than risk you becoming the one whose behaviour gets flagged. (Same would apply to anyone.) – doppelgreener May 1 '18 at 17:10
• @Trish [Raises hand.] I'm pretty sure one people was me, and let me take this opportunity to apologize. I am thoroughly sorry. – Hey I Can Chan May 2 '18 at 0:42