Help talk:Style/Formatting and punctuation

From ArchWiki
< Help talk:Style
Revision as of 13:53, 26 June 2013 by Kynikos (Talk | contribs) (First instances: first instances)

Jump to: navigation, search

General indications

[Split from a longer discussion: [1]. -- Kynikos (talk) 15:23, 5 June 2013 (UTC)]

I am personally against any formatting at all, at least where it can be avoided. IMHO, if we want formatting in articles to be meaningful and helpful for readers, it is necessary to completely deprecate it's usage except limited list of well-defined cases. Such lists would obviously tend to change, but at least this would help to prevent counterintuitiveness and inconsistency. --AlexanderR 20:45, 3 February 2012 (EST)

I think what AlexanderR wrote here is very important: the style rules that will derive from this talk page will have to be a white list of (very) specific cases that require formatting, like in "all text is to be left without formatting except for the following cases: ...". -- Kynikos (talk) 13:26, 4 June 2013 (UTC)
We could also mention Wikipedia:Manual of Style in the guide and only integrate it (or override, if really necessary) where needed. -- Kynikos (talk) 07:03, 6 June 2013 (UTC)



With respect to this Wiki specificity (and taking into account various precedents) I propose to limit usage of bold text to: --AlexanderR 19:44, 31 January 2012 (EST)



I already noticed two kinds of italic usage in this Wiki, conventional enough to be proposed for this role (I am so lazy.. please add examples yourself if you want): --AlexanderR 19:44, 31 January 2012 (EST)



As far as I know underlining is used relatively rarely in this Wiki. The only use case I can imagine is using in place of bold (e.g. for highlighting single words and sentences without pulling them out of context). If we decide to deprecate direct usage of bold text in order to fully utilize it for technical purposes, such replacement would be suitable. --AlexanderR 20:45, 3 February 2012 (EST)

Following Wikipedia:Manual of Style/Text formatting#How not to apply emphasis I would deprecate any use of underlining. -- Kynikos (talk) 07:33, 6 June 2013 (UTC)

Quoting and double quoting

Quoting belongs to punctuation rather than formatting, so there is nothing to discuss. --AlexanderR 20:45, 3 February 2012 (EST)

Now the discussion also includes punctuation :) -- Kynikos (talk) 11:51, 4 June 2013 (UTC)

Alternative approach

We could define our own basic (or simple, following Arch's philosophy) rules for italics and bold, and derive all the use cases from them. Citing AlexanderR in #Inline templates, I would find it quite natural to use bold to "attract additional users attention" and italic to "offset text from its surrounding content".

Once these two cases are defined, all the specific uses should come quite naturally, for example #Executables names (as executables in file system, not in command line) and #Pseudo-variables would be in italic, #"not" and #Important part of file/command line contents would be in bold. Under these simple rules, I would even be in favour of using italic for #Single file names.

In this case I would reserve the use of Template:ic only for:

  • Complete commands, e.g. "run grep Ignore /etc/pacman.conf using the grep utility"
  • Full file paths
  • Content that can be read or written on a file, e.g. "add bind '"\e[A": history-search-backward' to your .bashrc file" or "check that the GRUB_CMDLINE_LINUX_DEFAULT variable in /etc/default/grub is set to "quiet splash", thus making the whole line of the grub file be GRUB_CMDLINE_LINUX_DEFAULT="quiet splash""
  • In general when it can make sense to copy-paste the ic'ed text in a terminal or a text editor (i.e. when there can be a realistic reason for doing it)
  • Keyboard keys, see Help talk:Style/Migration to new Code formatting templates#Template:Keypress

Note however that basically I'm brainstorming, there are probably many aspects that I've overlooked with this reasoning, so please go on and comment!

(EDIT:Comment only on the two "basic" definitions defined in the first paragraph; the rest of the post is only used to give an idea of what the consequences would be. To comment each specific case, just reply to one of the sections below or create a new one)

-- Kynikos (talk) 07:31, 6 June 2013 (UTC) (Last edit: 14:38, 6 June 2013 (UTC))

Any comments on this? Anybody else with some opinion on these issues? The problem is that it's difficult to make decisions here since I and Flu do not agree on everything, so any additional point of view will be highly appreciated ^^ -- Kynikos (talk) 13:17, 10 June 2013 (UTC)

Formatting cases

Simple file names

(Highly questionable)

search for loop.ko in /lib/modules/kernel_release

--AlexanderR 19:44, 31 January 2012 (EST)

It seems I raised the problem again:
I second AlexanderR choices, also the first point (between fstab and fstab the latter is better-looking), plus the package name (once Pkg template has been used the first time). I bring to bear witness Core_Utilities article which is quiet good-looking, I think, also using lynx. -- Flu (talk) 16:10, 2 June 2013 (UTC)
I'm against bold in this case, consistency is more important than aesthetics, so we should use the same formatting for both full-path file names and short (single) file names. I'm in favour of using Template:ic for filesystem paths and file names.
search for loop.ko in /lib/modules/kernel_release
-- Kynikos (talk) 05:57, 6 June 2013 (UTC)
good point, changed my mind, +1 -- Flu (talk) 21:07, 6 June 2013 (UTC)
Eheh sorry but now it's me who's changed his mind :) For coherence with executable names I propose using italic:
  • "Edit resolv.conf, substituting your name servers' IP addresses and your local domain name:" (Beginners' Guide)
  • "Before installing, you may want to edit the mirrorlist file and place your preferred mirror first." (Beginners' Guide)
  • "For kernel modules to load during boot, place a *.conf file in /etc/modules-load.d/, with a name based on the program that uses them." (Beginners' Guide)
  • "Create a refind_linux.conf file with the kernel parameters to be used by rEFInd:" (Beginners' Guide)
I guess also device names should fall here:
  • "Each partition is identified with a number suffix. For example, sda1 specifies the first partition of the first drive, while sda designates the entire drive." (Beginners' Guide)
Also include extensions:
  • "Pacman is written in the C programming language and uses the .pkg.tar.xz package format." (Pacman)
-- Kynikos (talk) 04:18, 26 June 2013 (UTC)

Executable/application names

javaws, which is in icedtea-web-java7

Template:Box YELLOW

--AlexanderR 19:44, 31 January 2012 (EST)

An interesting case from Installation Guide:
  • Uncomment the selected locale in /etc/locale.gen and generate it with locale-gen
I guess technically locale-gen would stay formatted that way, since it would be the same as writing:
  • Uncomment the selected locale in /etc/locale.gen and generate it executing locale-gen
If however for instance the sentence changed very slightly to:
  • Uncomment the selected locale in /etc/locale.gen and generate it with the locale-gen utility
Following AlexanderR's way it should become:
  • Uncomment the selected locale in /etc/locale.gen and generate it with the locale-gen utility
And with #Alternative approach it should become:
  • Uncomment the selected locale in /etc/locale.gen and generate it with the locale-gen utility
-- Kynikos (talk) 14:32, 10 June 2013 (UTC)
I suggest using italic, and only for full lower-case names:
  • "You can also use iwconfig and see which interfaces are not wireless:" (Beginners' Guide)
  • "As of v197, udev no longer assigns network interface names according to the wlanX and ethX naming scheme." (Beginners' Guide)
  • "The Arch Linux install media includes the following partitioning tools: fdisk, gdisk, cfdisk, cgdisk, parted." (Beginners' Guide)
  • "This article deals with so-called core utilities on a GNU/Linux system, such as less, ls, and grep." (Core Utilities)
Note that this rule would apply to executables when they represent the application/file itself, not when used in #CLI lines. In particular pay attention to executables that are usually run without any arguments:
-- Kynikos (talk) 03:31, 26 June 2013 (UTC)

Repository names

Currently the [repository] form seems the most frequent, however note the problem of brackets in links, e.g. [[#.5Bcommunity.5D|[community]]] in the intro of AUR. The repository form (italic) can be an alternative, what do you think? -- Kynikos (talk) 04:29, 26 June 2013 (UTC)

Package and group names

Use italic for package and package-group names. -- Kynikos (talk) 04:41, 26 June 2013 (UTC)

Daemons/services, kernel modules

ensure that radeonfb is blacklisted

--AlexanderR 19:44, 31 January 2012 (EST)

I'd use italic in these cases (of course only when the name represents the service/module itself, not when used in #CLI lines):
  • "The dhcpcd network daemon starts automatically during boot" (Beginners' Guide)
-- Kynikos (talk) 04:07, 26 June 2013 (UTC)

Configuration parameters, variables, options, properties...

Use monospace (Template:ic):

  • "By default, the keyboard layout is set to us." (Beginners' Guide)
  • "...where layout can be fr, uk, dvorak, be-latin1, etc." (Beginners' Guide)
  • "As of v197, udev no longer assigns network interface names according to the wlanX and ethX naming scheme." (Beginners' Guide)
  • "In this example, the Ethernet interface is enp2s0f0." (Beginners' Guide)
  • "If you are unsure, your Ethernet interface is likely to start with the letter "e", and unlikely to be lo or start with the letter "w"." (Beginners' Guide)
  • "Currently, you may include a maximum of three nameserver lines." (Beginners' Guide)
  • "you will need to create an extra BIOS Boot Partition of size 1007 KiB and EF02 type code." (Beginners' Guide)
  • "All files should have 644 permissions and root:root ownership." (systemd)

Also include command options:

  • "The -i switch can be omitted if you wish to install every package from the base group without prompting." (Beginners' Guide)

...and user groups:

  • "Adding your user to groups (sys, disk, lp, network, video, audio, optical, storage, scanner, power, etc.) is not necessary for most use cases with systemd." (systemd)

Plus environment variables:

  • "If you are behind a proxy server, you will need to export the http_proxy and ftp_proxyenvironment variables." (Beginners' Guide)
  • "To use other locales for other LC_* variables, run locale to see the available options and add them to locale.conf. It is not recommended to set the LC_ALL variable. An advanced example can be found here." (Beginners' Guide)

...and variables in general:

  • "this roughly equates to what you included in the DAEMONS array." (systemd)

-- Kynikos (talk) 04:20, 26 June 2013 (UTC)

CLI lines

Use Template:ic. Must be inline command examples, not a simple mention of an executable name (see #Executable/application names). Also console output and text that may reasonably be useful to paste in a terminal.

  • "you are encouraged to type man command to read the man page of any command" (Beginners' Guide)
  • "You can use the command ip link to discover the names of your interfaces." (Beginners' Guide)
  • "If you get a ping: unknown host error, first check if there is an issue with your cable or wireless signal strength." (Beginners' Guide)
  • "Type yes and choose Quit (or press Q) to exit without making any more changes." (Beginners' Guide)

No prompt symbol is to be represented in inline code: if needed, permission notes must be added explicitly, like in "Execute pacman -Syu with root privileges", not "Execute # pacman -Syu".

-- Kynikos (talk) 05:03, 26 June 2013 (UTC)

File content

Use Template:ic for content that can be both read or written on a file or that may reasonably be useful to copy from or paste in a text editor:

  • "At the end of the string type nomodeset and press Enter. Alternatively, try video=SVIDEO-1:d which, if it works, will not disable kernel mode setting." (Beginners' Guide)
  • "remove the # in front of the locale you want from /etc/locale.gen" (Beginners' Guide)
  • "Please choose the UTF-8 entry." (Beginners' Guide) (could be grouped in #Technical terms instead)

-- Kynikos (talk) 04:25, 26 June 2013 (UTC)

Full file system paths

Use Template:ic:

  • "To test if you have booted into UEFI mode check if directory /sys/firmware/efi has been created" (Beginners' Guide)
  • "All files and directories appear under the root directory /, even if they are stored on different physical devices." (Partitioning)

-- Kynikos (talk) 04:25, 26 June 2013 (UTC)

Keyboard keys

Use Template:ic, see Help talk:Style/Migration to new Code formatting templates#Template:Keypress:

  • "you have to press a key (usually Delete, F1, F2, F11 or F12) during the POST" (Beginners' Guide)

-- Kynikos (talk) 04:25, 26 June 2013 (UTC)

Important part of file/command line contents

root=/dev/sda6 ro 5 radeon.modeset=1 vga=current logo.nologo quiet splash

--AlexanderR 19:44, 31 January 2012 (EST)

This one can be acceptable. -- Kynikos 17:58, 3 February 2012 (EST)
Since these contents are code themselves, when referenced outside of the template, Template:ic should be preserved, as opposed to #Pseudo-variables:
# ln -s /usr/src/linux-$(uname -r)/include/generated/uapi/linux/version.h /usr/src/linux-$(uname -r)/include/linux/
You can replace $(uname -r) with any kernel not currently running." (VMware)
-- Kynikos (talk) 03:53, 26 June 2013 (UTC)


I don't know if we should use bold or what else when using pseudo-variables like:

# modprobe module_name
# modprobe module_name
# modprobe <module_name>
# modprobe [MODULE_NAME]

(from Kernel Modules). -- Kynikos 17:58, 3 February 2012 (EST)

This conflicts with "important part of file/command line contents" part. As I said below, italic seems to be more appropriate.
Probably worse idea than just italic: Another proposal –
# modprobe <module_name>
This way pseudo-variables become highlighted and offset from surrounding text at the same time but in different way than "important part". --AlexanderR 20:45, 3 February 2012 (EST)
I prefer:
# modprobe module_name
-- Flu (talk) 15:20, 2 June 2013 (UTC)
+1 (plain italic). -- Kynikos (talk) 06:08, 6 June 2013 (UTC)
When mentioning the variable outside of the template, it should drop Template:ic:
-- Kynikos (talk) 03:34, 26 June 2013 (UTC)

Inline templates

(IMHO, those with italic formatting look much better than ones with bold formatting):

--AlexanderR 19:44, 31 January 2012 (EST)

I don't understand, you'd use always italic inside Template:ic regardless of the content? In that case I don't even like it aesthetically :) -- Kynikos 17:58, 3 February 2012 (EST)
This is exactly what you name "pseudo-variables" (your wording was better than mine, lets use it). Using bold in this case conflicts with "important part of file/command line contents" part; italic would also be more intuitive: we want to offset text from its surrounding content rather than attract additional users attention. --AlexanderR 20:45, 3 February 2012 (EST)
Ah ok, then formatting in this case should be coherent with #Pseudo-variables. -- Kynikos (talk) 07:07, 6 June 2013 (UTC)
Closing as it duplicates #Pseudo-variables. -- Kynikos (talk) 04:31, 26 June 2013 (UTC)

GUI/TUI text

Use italic, for example for menu entries:

  • "Then, select Boot Arch Linux from the menu and press Enter in order to begin with the installation" (Beginners' Guide)
  • "When using Gparted, selecting the option to create a new partition table gives an msdos partition table by default. If you are intending to follow the advice to create a GPT partition table then you need to choose Advanced and then select gpt from the drop-down menu." (Beginners' Guide)
  • "Type yes and choose Quit (or press Q) to exit without making any more changes." (Beginners' Guide)

-- Kynikos (talk) 04:09, 26 June 2013 (UTC)

Technical terms

I suggest using italic:

  • "you are encouraged to type man command to read the man page of any command" (Beginners' Guide)
  • "This article deals with so-called core utilities on a GNU/Linux system" (Core Utilities)
  • "Primary partitions can be bootable and are limited to four partitions per disk or RAID volume." (Partitioning)
  • "This is already a separate partition by default, by virtue of being mounted as tmpfs by systemd." (Partitioning)

Except for all-caps terms (usually acronyms):

  • "you have to press a key (usually Delete, F1, F2, F11 or F12) during the POST (Power On Self-Test) phase" (Beginners' Guide)
  • "Please choose the UTF-8 entry." (Beginners' Guide) (could be thought of as part of a line in /etc/locale.gen and grouped in #File content)

-- Kynikos (talk) 03:20, 26 June 2013 (UTC)

Stressed/strong words or statements

not bold when it is worth -- Flu (talk) 15:20, 2 June 2013 (UTC)

I would use italics in this case, see also Wikipedia:MOS:text_formatting#Contraindications and Wikipedia:MOS:text_formatting#Emphasis.
It would also be great if we could find the right words to define "worth".
-- Kynikos (talk) 06:12, 6 June 2013 (UTC)
Attempt 1: it is worth when it may lead a user to a dangerous or inefficient choice.
I do not like italic by the way, it is not that evident. -- Flu (talk) 21:15, 6 June 2013 (UTC)
So would you see these special nots as kind of a super-compact Template:Warning? (as defined in Help:Style#Notes, Warnings, Tips)
About bold vs italic, I'd support bold if there was agreement over #Alternative approach: I want to find a solid basic reference from which derive all our text formatting rules, instead of deciding case by case without any kind of global vision of the problem; in this section I proposed to base our rules on Wikipedia's style rules, but now I tend to prefer the definitions that I've exposed in #Alternative approach.
-- Kynikos (talk) 14:43, 7 June 2013 (UTC)
Yes, but a warning does not exclude a not -- Flu (talk) 10:57, 8 June 2013 (UTC)
So, a general rule could be to use italic for words whose importance in giving the meaning to a sentence would not be recognized otherwise; usually they would be pronounced in a stressed way if reading out loud:
  • "Choose the best environment for your needs." (Beginners' Guide)
  • "This command can synchronize the repository databases and update the system's packages" (Pacman)
  • "If the screen does not go blank and the boot process gets stuck" (Beginners' Guide)
  • "so please type it exactly as you see it:" (Beginners' Guide)
  • "If you want, you can make it the only mirror available by getting rid of everything else" (Beginners' Guide)
When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in bold (use only when really needed (or "worth", citing Flu above), though):
  • "Partitioning can destroy data. You are strongly cautioned and advised to backup any critical data before proceeding." (Beginners' Guide)
  • "keep up to date with changes in Arch Linux that require manual intervention before upgrading your system." (Beginners' Guide)
The same goes for very important parts of a section that cannot be put in a separate Warning or Note as they are an essential part of the section itself:
  • "When performing a system update, it is essential that users read all information output by pacman and use common sense." (Pacman)
  • "This means that partial upgrades are not supported." (Pacman)
-- Kynikos (talk) 03:47, 26 June 2013 (UTC)

Acronym/abbreviation expansions

I suggest italic:

-- Kynikos (talk) 03:46, 26 June 2013 (UTC)

Words/letters when referenced as mere "text entities"

Use quote marks:

  • "When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in bold" (#Stressed/strong words or statements)
  • "If you are unsure, your Ethernet interface is likely to start with the letter "e", and unlikely to be lo or start with the letter "w"." (Beginners' Guide)

-- Kynikos (talk) 04:08, 26 June 2013 (UTC)

Generic words used in an improper or questionable way

Use quote marks:

'Words/letters when referenced as mere "text entities"' (from the section above)

-- Kynikos (talk) 04:11, 26 June 2013 (UTC)


All your data belongs to us – Google

--AlexanderR 19:44, 31 January 2012 (EST)

...or "All your data belongs to us" (w/ quotes)? (see e.g. Beginners'_Guide#The_Arch_Way) -- Kynikos 17:58, 3 February 2012 (EST)
This is matter of punctuation, not formatting. --AlexanderR 20:45, 3 February 2012 (EST)
Both ways seem incoherent with Wikipedia:MOSQUOTE#Italics and quotations. -- Kynikos (talk) 07:00, 6 June 2013 (UTC)
I'd like to follow Wikipedia on this topic, and avoid italic for quotations: in general, I'd refer to Wikipedia's guidelines, so use quote marks for inline quotations, and <blockquote> or : (we'd better choose only one form here) for block quotes, without italic-izing them.
"All your data belongs to us" – Google
-- Kynikos (talk) 03:56, 26 June 2013 (UTC)

General rules

First instances

The first relevant appearance of a term or name in an article (e.g. executable names) can be highlighted if regarded as worthy of particular attention, considering the topic of the article or the specific section. The first "relevant" appearance may not be the absolute first appearance of the name: its choice is left to the editor.

The preferable way of highlighting the name is using a link to a closely related article in the wiki or to an external page, like Wikipedia; if there are no possible pertinent links, bold can be used as a fallback solution.

Package and group names should make use of Template:Pkg, Template:AUR or Template:Grp.

Note that if the name is already introduced by the title of the article or by a section heading, it doesn't require any further highlighting in the article, except in the case of #Name/term lists.

-- Kynikos (talk) 13:53, 26 June 2013 (UTC)

Name of application in the beginning of application-related article

Foo is the most popular Linux alternative to Wikipedia:Bar.

--AlexanderR 19:44, 31 January 2012 (EST)

I don't know, usually the name of the application is also the title of the article, so this rule could just add bloat for nothing. I'd recommend to use the first encounter of the app name as an anchor for a link to the official website instead. If there's nothing to link, leave it in normal weight. -- Kynikos 17:58, 3 February 2012 (EST)
>> so this rule could just add bloat for nothing
Maybe, but for some reason cited HTML5 developers, authors of many articles in this Wiki and even webmaster believe this to be "conventional typographic presentation". This, however, does not oblige us to support such case of usage here.
>> I'd recommend to use the first encounter of the app name as an anchor for a link to the official website instead.
This is neither consistent (there is often nothing to link) nor intuitive – user can not see link destination without hovering cursor over it. As I said in discussion on "See also visibility", links to Wikipedia article(s), application home page(s), application project(s) on code hostings etc. together with reliable summary are the only reasonable content for article summary template and should probably be placed in that single predefined place. --AlexanderR 20:45, 3 February 2012 (EST)


Whenever any of the above formatting cases can be a link to another article or external page, the link takes precedence over any formatting (which is discarded). -- Kynikos (talk) 04:43, 26 June 2013 (UTC)

Name/term lists

Keep consistent formatting in lists of executable names, technical terms... even if not all of the items would require to be formatted (e.g. all-caps terms, which shouldn't be italic-ized by themselves, or names in a list where most of the items are formatted according to #First instances. -- Kynikos (talk) 06:10, 26 June 2013 (UTC)