Difference between revisions of "Help:Style/Formatting and punctuation"

From ArchWiki
Jump to: navigation, search
(File names and paths: + example)
(Examples: + rules)
Line 159: Line 159:
 
Also device names:
 
Also device names:
 
* Each partition is identified with a number suffix. For example, {{ic|sda1}} specifies the first partition of the first drive, while {{ic|sda}} designates the entire drive.
 
* Each partition is identified with a number suffix. For example, {{ic|sda1}} specifies the first partition of the first drive, while {{ic|sda}} designates the entire drive.
 +
 +
===Keyboard keys===
 +
Use {{ic|monospace}}.
 +
 +
* You have to press a key (usually {{ic|Delete}}, {{ic|F1}}, {{ic|F2}}, {{ic|F11}} or {{ic|F12}}) during the POST.
  
 
===Package and group names===
 
===Package and group names===

Revision as of 11:56, 25 August 2013


The following directions define how different parts of the content of an article should be highlighted through formatting or punctuation.

General rules

These rules always override #Specific cases.

  • Do not mix more than one highlighting method except where explicitly allowed by these rules.
  • Do not use different highlighting methods from the ones defined in this manual; this includes, but is not limited to, underlining, blinking, full-word capitalization, colors, asterisks, exclamation marks, emoticons, HTML tags with a style attribute.

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 does not require any further highlighting in the article, except in the case of #Name/term lists.

Links

  • 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).

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 should not be italic-ized by themselves, or names in a list where most of the items are formatted according to #First instances.

Specific cases

#General rules always override the following rules.

Italic

Use the MediaWiki syntax ''italic text'' instead of <i> tags.

Bold

Use the MediaWiki syntax '''bold text''' instead of <b> tags.

Monospace

Use Template:ic {{ic|monospace text}} instead of <code> tags for text outside of code blocks.

Quote marks

Use typewriter quotes "quoted text" instead of single quotes 'quoted text' or typographic quotes “quoted text”.

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Use <blockquote> or : for block quotes. (Discuss in Help talk:Style/Formatting and punctuation#)

Examples

CLI lines

Use monospace. 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.
  • You can use the command ip link to discover the names of your interfaces.
  • If you get a ping: unknown host error, first check if there is an issue with your cable or wireless signal strength.
  • Type yes and choose Quit (or press Q) to exit without making any more changes.

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".

Configuration parameters, variables, options, properties...

Use monospace.

  • By default, the keyboard layout is set to us.
  • [...] where layout can be fr, uk, dvorak, be-latin1, etc.
  • As of v197, udev no longer assigns network interface names according to the wlanX and ethX naming scheme.
  • In this example, the Ethernet interface is enp2s0f0.
  • 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".
  • Currently, you may include a maximum of three nameserver lines.
  • You will need to create an extra BIOS Boot Partition of size 1007 KiB and EF02 type code.
  • All files should have 644 permissions and root:root ownership.

Also command options:

  • The -i switch can be omitted if you wish to install every package from the base group without prompting.

Also 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.

Also environment variables:

  • If you are behind a proxy server, you will need to export the http_proxy and ftp_proxyenvironment variables.
  • 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.

Also variables in general:

  • [...] this roughly equates to what you included in the DAEMONS array.

Daemons/services, kernel modules

Use monospace.

  • The dhcpcd network daemon starts automatically during boot.

Executable/application names

Use italic, but only for full lower-case names. Affected by #First instances.

  • Uncomment the selected locale in /etc/locale.gen and generate it with the locale-gen utility.
  • As of v197, udev no longer assigns network interface names according to the wlanX and ethX naming scheme.
  • The Arch Linux install media includes the following partitioning tools: fdisk, gdisk, cfdisk, cgdisk, parted.

Note that this rule applies 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:

  • Uncomment the selected locale in /etc/locale.gen and generate it with locale-gen.
  • If pacman fails to verify your packages, check the system time with cal.
  • Set a root password with passwd.

File content

Use monospace 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.
  • Remove the # in front of the locale you want from /etc/locale.gen.

File extensions

Use italic.

  • Pacman is written in the C programming language and uses the .pkg.tar.xz package format.

File names and paths

Use monospace.

  • To test if you have booted into UEFI mode check if directory /sys/firmware/efi has been created.
  • All files and directories appear under the root directory /, even if they are stored on different physical devices.
  • Edit resolv.conf, substituting your name servers' IP addresses and your local domain name.
  • Before installing, you may want to edit the mirrorlist file and place your preferred mirror first.

Also names with wildcards:

  • 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.

Also device names:

  • 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.

Keyboard keys

Use monospace.

  • You have to press a key (usually Delete, F1, F2, F11 or F12) during the POST.

Package and group names

Use italic for package and package-group names. Affected by #First instances.

  • The package wireless_tools then provides a basic set of tools for managing the wireless connection.

Repository names

Use italic for repository names. Affected by #First instances.

  • If you enable testing, you must also enable community-testing.