7

This question is partially inspired by a rejected edit to this post.

In the answers, inline backtick formatting is used for manpage titles such as mount(8) and sudoers(4). In the question, it is not. I believed that the use of formatting was correct in this case, and submitted an edit to the question. This edit was rejected.

After getting the rejection, I searched the site, and while backtick formatting usage wasn't consistent, it did seem to be typical in question answers involving manpage names. In addition, the impression I get from unix.SE is that backtick formatting should be used for all instances of the manpage title, and that one of these should if possible link to an online copy of the manpage (when relevant.)

I also thought it improved clarity, though other people's opinion may differ from mine.

Can someone give me some guidance on the correct use of backtick formatting here?

3
  • 5
    There's 2 rejects and one approval - which isn't that bad. I do think its deeply subjective, and its a matter of if one sees it as a minor edit or not. I'd say broadly its fine as an edit on its own, but as a suggested edit, whether its substancial enough, well depends on how the reviewer sees it
    – Journeyman Geek Mod
    Commented Nov 11 at 13:37
  • 2
    I agree the edit is fine. @JourneymanGeek - as a mod, you have the ability to override reviews in cases such as these ๐Ÿ˜‰
    – Robotnik
    Commented Nov 13 at 5:06
  • 1
    Well yes. But I wanted to take a look at it with fresh eyes and forgot ๐Ÿ˜…
    – Journeyman Geek Mod
    Commented Nov 13 at 6:02

2 Answers 2

Reset to default
9

I agree that it improves readability, and did the edits for you.

4
  • Thanks - it also means the question and its answers are now consistent in how they format the manpage names.
    – AJM
    Commented Nov 12 at 18:50
  • 2
    In future, I would suggest to keep doing what you tried. That's also how I got some of my early rep :P But ya, readability improvements should be suggested where possible. I see nothing wrong with what you tried
    – Canadian Luke
    Commented Nov 12 at 19:14
  • Thanks, but I risk an edit ban if too many of these are rejected, which is a shame since I really do think they make a significant difference to readability.
    – AJM
    Commented Nov 12 at 19:15
  • One rejected edit is not going to get you banned.
    – Canadian Luke
    Commented Nov 12 at 22:55
1

I agree that backticks are fine in your edit specifically; but I disagree that they should be used for all instances. The Stack Exchange sites use a rather heavyweight stylesheet for backticks, i.e. not just monospace font, but also very eye-catching background color (one that really clashes with hyperlink colors on SuperUser, too).

Similar to overuse of bold formatting, or Wikipedia's "avoid making the entire page blue" guideline for hyperlinks, I think backticks as they are currently styled should be used sparingly โ€“ e.g. in places where they're meant to attract the eye of someone skimming through the post (so e.g. the first mention of a command, but not all 20 subsequent mentions), or where they actually denote keyboard input or some code to be copy/pasted (which "regex(7)" is not!), but not necessarily where it's just an inline mention of something that happens to be code. Compare e.g. with traditional Unix manual pages, which use plain bold or italics even for command names.

(I've seen some posts where every other sentence is bold, making the formatting lose its purpose, and then every third sentence is bold + italic to compensate for that, and then increasingly bolder headings, etc. That is not easy to read, much less quickly skim through.)

Even more so with hyperlinks; at least on the main Super User site, the light blue link color becomes rather difficult to read when combined with the dark gray "code" background, so it can be a net decrease in clarity.

2
  • 6
    Sorry I have to disagree - being consistent with formatting throughout a post makes the most sense, backticks for computer input especially. Sure, they might be visually ugly, but they are semantic markup: under the hood they are being rendered as HTML <code></code> sections, which get treated differently in accessibility software. For example, screen readers may spell out code, rather than try to read it word-for-word. For someone using a reader, it would be confusing to have the same text treated differently because the first instance used semantic formatting and subsequent ones did not.
    – Robotnik
    Commented Nov 14 at 14:16
  • 2
    This is one of those things we should probably keep a periodic watch on as a community-- actually seeing (hearing) how things formatted as code are presented in major screen readers. One thing which enlightened me years ago was seeing a tweet / post about how 'fancy letters' (eg unicode blackletter, unicode heavy lettering) were read out individually. Eg '๐“ข๐“ธ๐“ถ๐“ฎ ๐“ฏ๐“ช๐“ท๐“ฌ๐”‚ ๐“ฝ๐“ฎ๐”๐“ฝ' becomes "Mathematical bold script captial S, mathematical bold script small o, ... " (etc) If there's a difference in rendering, I'm with graw- visual consistency should not come at the cost of accessibility
    – bertieb
    Commented Nov 15 at 20:02

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .