7

What is the correct way to format terms which should be searched for or button names?
Example:

  1. Search for "Settings"
  2. Click on the "System Settings" button

Should an inline code span be used, "quotation marks" or italics?

By my knowledge, inline code is for commands and file paths

||||||
9

There's no official right way to format text that is input to, or output from, a graphical interface. It's largely a matter of personal style, and probably no style is objectively best.

Quotation marks are often good, as are italics. When quotation marks or italics are already being used, the sparing use of bold may even be considered.

An author might choose to use the same convention for every different type of GUI text talked about in a post. Alternatively, an author might choose to format text that is to be typed into a textbox one way, "static" labels (that do not respond when clicked) one way, and "dynamic" labels (like the text on a menu or command button) another way.

With that said there are three guidelines that I believe are widely agreed upon:

  1. Within any single post, consistency is better than inconsistency. (This is similar to the idea that the same word should be spelled the same way within any single post, barring any special reason to do otherwise.)

  2. Subjective style preferences of an editor don't warrant changing one established style to another. Only if the current style is causing problems should it be changed. So, if a post italicizes all names of menus, they shouldn't be put in quotes instead unless there is reason to think that would really improve readability.

  3. code spans should only ever be used for text that is code-like in nature. This includes actual program code, but also most text that would appear or be typed into a terminal. Text that appears in a graphical interface is not usually code-like, so code spans should usually not be used for it.

    Editing is justified to remove code formatting from text that is not code-like in any way. However, there is some reasonable disagreement about what is code-like. Filenames are widely considered to be code-like, here. Are package names code-like?

    When something is clearly code-like (like commands for entry in a terminal), editing is justified to add code formatting.

||||||
  • It could be useful to have a guide to help new users which way to go here. For example **for Bold text** **italic text** and `for inline code` and a choice of either <pre>code sample</pre> or 4 spaces before each line of text, for multiple lines of coded text. It took me some time to work this out. A bit like the <kbd>Alt</kbd> to suggest a keystroke. – SimplySimon Aug 25 '13 at 15:28
  • @SimplySimon Are you thinking of something like this? It doesn't cover <kbd> tags, but it has the basic formatting. – Eliah Kagan Aug 25 '13 at 16:33
  • sort of, but more of a small info panel next to the input box. – SimplySimon Aug 25 '13 at 16:44
  • 1
    Feel free to disagree with me Eliah, but I believe for absolute paths (such as /etc/apt/sources.list as an example), code tags make the path more readable, making it easier to tell the difference between a capital 'i' and a capital 'l' for example. As well, I believe that program names that would be executed in terminal, such as dpkg or eclipse should also be code formatted. but that's just my opinion, sorry for putting my opinion here. – Thomas Ward Aug 27 '13 at 22:53
  • @ThomasW. I totally agree. I use code formatting for paths and commands (including command names) as well. – Eliah Kagan Aug 28 '13 at 11:00
  • What about using <kbd></kbd> tags for button names? – kiri Sep 13 '13 at 10:02
  • 1
    @minerz029 I think <kbd> tags for buttons in a graphical interface should be avoided. The way text in <kbd> tags is displayed varies from browser to browser (and even with the "same browser" from OS to OS). Some browsers display <kbd> text inside a picture of a key. – Eliah Kagan Sep 13 '13 at 22:11
  • 1
    I have just found a shortcut which would have saved hours! Ctrl+K. Type in the code, select it and press Ctrl+K and all the lines will be prefixed with 4 spaces automatically! Brilliant! – SimplySimon Sep 17 '13 at 12:01

You must log in to answer this question.

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