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

From ArchWiki
Jump to: navigation, search
(Examples: + rules)
(update interlanguage links)
(Tag: wiki-scripts)
(42 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
[[Category:Help]]
 
[[Category:Help]]
{{Stub|Work in progress: these rules are '''not''' in a definitive state yet.}}
+
[[el:Help:Style/Formatting and punctuation]]
 
The following directions define how different parts of the content of an article should be highlighted through formatting or punctuation.
 
The following directions define how different parts of the content of an article should be highlighted through formatting or punctuation.
  
 
==General rules==
 
==General rules==
These rules always override [[#Specific cases]].
+
These general rules always override [[#Specific cases]]. For cases not covered in this guide, [[Wikipedia:Manual of Style]] is the authority reference.
  
* Do not mix more than one highlighting method except where explicitly allowed by these rules.
+
* Do not mix more than one highlighting method except where explicitly allowed by these rules. <br> This rule also applies in the cases where some formatting is already set by CSS rules, for example bold in [[Help:Editing#Definition_lists|definition list terms]]. If the preset CSS formatting is not allowed on the affected item (e.g. bold on [[#File names and paths]]), then you have to resort using a different, compatible wiki markup altogether (e.g. [[Help:Editing#Bullet_points|bullet points]] instead of a definition list).
 
* 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 {{ic|<nowiki>style</nowiki>}} attribute.
 
* 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 {{ic|<nowiki>style</nowiki>}} attribute.
  
 
===First instances===
 
===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 first relevant appearance of a term or name in an article (e.g. executable names) can be ''highlighted'' (see below) 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.
 
* 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]].
+
: 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]].
+
* If the name is already introduced by the title of the article or by a section heading, its first relevant appearance in the body can only be used as a link anchor, but not simply highlighted in bold, except in the case of [[#Name/term lists]].
 +
* First-instance highlighting can be applied only to the [[#Specific cases]] that explicitly allow it.
  
 
===Links===
 
===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).
+
* No formatting shall be applied to the anchor text of links.
  
 
===Name/term lists===
 
===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]].
+
* It is allowed, not mandatory, to keep consistent formatting in lists of names or terms, even if normally not all of the items would require to be formatted. This can involve for example 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]]. <br> "List" is to be intended in a broad sense, so that for example also all the initial words of a series of subsequent paragraphs could be considered forming a list of terms.
  
==Specific cases==
+
==Cases by formatting/punctuation==
[[#General rules]] always override the following rules.
+
Cases marked by <sup>1</sup> are affected by [[#First instances]]. Cases marked by <sup>m</sup> apply to monospaced text.
  
 
===Italic===
 
===Italic===
 
Use the MediaWiki syntax {{ic|<nowiki>''italic text''</nowiki>}} instead of {{ic|<nowiki><i></nowiki>}} tags.
 
Use the MediaWiki syntax {{ic|<nowiki>''italic text''</nowiki>}} instead of {{ic|<nowiki><i></nowiki>}} tags.
  
*[[#Executable/application names]]
+
*[[#Executable/application names]]<sup>1</sup>
**only for full lower-case names
 
**not when used in [[#CLI lines]]
 
**affected by [[#First instances]]
 
 
*[[#File extensions]]
 
*[[#File extensions]]
*[[#Repository names]]
+
*[[#Repository names]]<sup>1</sup>
**affected by [[#First instances]]
+
*[[#Package and group names]]<sup>1</sup>
*[[#Package and group names]]
+
*[[#Pseudo-variables in file/command line contents]]<sup>m</sup>
**affected by [[#First instances]]
 
*[[#Pseudo-variables]]
 
 
*[[#GUI/TUI text]]
 
*[[#GUI/TUI text]]
*[[#Technical terms]]
+
*[[#Technical terms]]<sup>1</sup>
**affected by [[#First instances]]
 
 
*[[#Stressed/strong words or statements]]
 
*[[#Stressed/strong words or statements]]
**can also use bold
 
 
*[[#Acronym/abbreviation expansions]]
 
*[[#Acronym/abbreviation expansions]]
  
Line 48: Line 42:
 
Use the MediaWiki syntax {{ic|<nowiki>'''bold text'''</nowiki>}} instead of {{ic|<nowiki><b></nowiki>}} tags.
 
Use the MediaWiki syntax {{ic|<nowiki>'''bold text'''</nowiki>}} instead of {{ic|<nowiki><b></nowiki>}} tags.
  
*[[#Important part of file/command line contents]]
+
*[[#Important part of file/command line contents]]<sup>m</sup>
 
*[[#Stressed/strong words or statements]]
 
*[[#Stressed/strong words or statements]]
**can also use italic
 
 
*[[#First instances]]
 
*[[#First instances]]
  
Line 57: Line 50:
  
 
*[[#File names and paths]]
 
*[[#File names and paths]]
**also device names
 
**not file extensions
 
 
*[[#Daemons/services, kernel modules]]
 
*[[#Daemons/services, kernel modules]]
 
*[[#Configuration parameters, variables, options, properties...]]
 
*[[#Configuration parameters, variables, options, properties...]]
**also command options
 
**also user groups
 
**also (environment) variables
 
 
*[[#CLI lines]]
 
*[[#CLI lines]]
 
*[[#File content]]
 
*[[#File content]]
Line 71: Line 59:
 
Use typewriter quotes {{ic|"quoted text"}} instead of single quotes {{ic|'quoted text'}} or typographic quotes {{ic|“quoted text”}}.
 
Use typewriter quotes {{ic|"quoted text"}} instead of single quotes {{ic|'quoted text'}} or typographic quotes {{ic|“quoted text”}}.
  
 +
*[[#References to titles, headings...]]
 
*[[#Words/letters when referenced as mere "text entities"]]
 
*[[#Words/letters when referenced as mere "text entities"]]
 
*[[#Generic words used in an improper or questionable way]]
 
*[[#Generic words used in an improper or questionable way]]
*[[#Inline quotations]]
+
*[[#Quotations]]
  
{{Expansion|Use {{ic|&lt;blockquote>}} or {{ic|:}} for block quotes.}}
+
==Specific cases==
 +
[[#General rules]] always override the following rules.
  
==Examples==
 
 
=== Acronym/abbreviation expansions===
 
=== Acronym/abbreviation expansions===
 
Use ''italic''.
 
Use ''italic''.
  
 +
====Examples====
 
* Pacman is the Arch Linux ''pac''kage ''man''ager.
 
* Pacman is the Arch Linux ''pac''kage ''man''ager.
 
* [[Wikipedia:cat_(Unix)|cat]] (''catenate'') is a standard Unix utility that concatenates and lists files.
 
* [[Wikipedia:cat_(Unix)|cat]] (''catenate'') is a standard Unix utility that concatenates and lists files.
  
 
===CLI lines===
 
===CLI lines===
Use {{ic|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.
+
Use {{ic|monospace}}. Must be inline command examples, not simple mentions of [[#Executable/application names]]. Also console output and text that may reasonably be useful to paste in a terminal.
  
 +
====Examples====
 
* You are encouraged to type {{ic|man ''command''}} to read the ''man'' page of any command.
 
* You are encouraged to type {{ic|man ''command''}} to read the ''man'' page of any command.
 
* You can use the command {{ic|ip link}} to discover the names of your interfaces.
 
* You can use the command {{ic|ip link}} to discover the names of your interfaces.
 
* If you get a {{ic|ping: unknown host}} error, first check if there is an issue with your cable or wireless signal strength.
 
* If you get a {{ic|ping: unknown host}} error, first check if there is an issue with your cable or wireless signal strength.
 
* Type {{ic|yes}} and choose ''Quit'' (or press {{ic|Q}}) to exit without making any more changes.
 
* Type {{ic|yes}} and choose ''Quit'' (or press {{ic|Q}}) to exit without making any more changes.
 +
* Execute {{ic|pacman -Syu}} with root privileges.
 +
 +
=== Configuration parameters, variables, options, properties... ===
 +
 +
Use {{ic|monospace}}. Also affects command options, user groups, IP addresses, environment variables and variables in general.
  
No prompt symbol is to be represented in inline code: if needed, permission notes must be added explicitly, like in "Execute {{ic|pacman -Syu}} with root privileges", '''not''' "Execute {{ic|# pacman -Syu}}".
+
When both the short and long form of a command option have to be represented, use the "/" symbol without spaces to separate them, for example {{ic|-a}}/{{ic|--anything}}.  
  
===Configuration parameters, variables, options, properties...===
+
==== Examples ====
Use {{ic|monospace}}.
 
  
 
* By default, the keyboard layout is set to {{ic|us}}.
 
* By default, the keyboard layout is set to {{ic|us}}.
Line 105: Line 100:
 
* You will need to create an extra [[GRUB#GUID Partition Table (GPT) specific instructions|BIOS Boot Partition]] of size 1007 KiB and {{ic|EF02}} type code.
 
* You will need to create an extra [[GRUB#GUID Partition Table (GPT) specific instructions|BIOS Boot Partition]] of size 1007 KiB and {{ic|EF02}} type code.
 
* All files should have {{ic|644}} permissions and {{ic|root:root}} ownership.
 
* All files should have {{ic|644}} permissions and {{ic|root:root}} ownership.
 
Also command options:
 
 
 
* The {{ic|-i}} switch can be omitted if you wish to install every package from the {{Grp|base}} group without prompting.
 
* The {{ic|-i}} switch can be omitted if you wish to install every package from the {{Grp|base}} group without prompting.
 
+
* Adding your user to [[Users and groups|groups]] ({{ic|sys}}, {{ic|disk}}, {{ic|lp}}, {{ic|network}}, {{ic|video}}, {{ic|audio}}, {{ic|optical}}, {{ic|storage}}, {{ic|scanner}}, {{ic|power}}, etc.) is '''not''' necessary for most use cases with systemd.
Also user groups:
 
 
 
* Adding your user to [[Users and Groups|groups]] ({{ic|sys}}, {{ic|disk}}, {{ic|lp}}, {{ic|network}}, {{ic|video}}, {{ic|audio}}, {{ic|optical}}, {{ic|storage}}, {{ic|scanner}}, {{ic|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 {{ic|http_proxy}} and {{ic|ftp_proxy}}environment variables.
 
* If you are behind a proxy server, you will need to export the {{ic|http_proxy}} and {{ic|ftp_proxy}}environment variables.
* To use other locales for other {{ic|LC_*}} variables, run {{ic|locale}} to see the available options and add them to ''locale.conf''. It is not recommended to set the {{ic|LC_ALL}} variable. An advanced example can be found [[Locale#Setting_system-wide_locale|here]].
+
* To use other locales for other {{ic|LC_*}} variables, run {{ic|locale}} to see the available options and add them to ''locale.conf''. It is not recommended to set the {{ic|LC_ALL}} variable. An advanced example can be found [[Locale#Setting the system locale|here]].
 +
* [...] this roughly equates to what you included in the {{ic|DAEMONS}} array.
 +
* If you are running a private network, it is safe to use IP addresses in {{ic|192.168.*.*}} for your IP addresses, with a subnet mask of {{ic|255.255.255.0}} and a broadcast address of {{ic|192.168.*.255}}. The gateway is usually {{ic|192.168.*.1}} or {{ic|192.168.*.254}}.
 +
* By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}.
  
Also variables in general:
+
=== Daemons/services, kernel modules ===
  
* [...] this roughly equates to what you included in the {{ic|DAEMONS}} array.
+
Use {{ic|monospace}}.
  
===Daemons/services, kernel modules===
+
==== Example ====
Use {{ic|monospace}}.
 
  
* The {{ic|dhcpcd}} network daemon starts automatically during boot.
+
* The {{ic|dhcpcd.service}} starts the daemon for all network interfaces.
 +
* Some unit names contain an {{ic|@}} sign (e.g. {{ic|name@''string''.service}}).
  
 
=== Executable/application names===
 
=== Executable/application names===
 
Use ''italic'', but only for full lower-case names. Affected by [[#First instances]].
 
Use ''italic'', but only for full lower-case names. Affected by [[#First instances]].
  
 +
Note that this rule applies to executables only 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.
 +
 +
====Examples====
 
* Uncomment the selected locale in {{ic|/etc/locale.gen}} and generate it with the ''locale-gen'' utility.
 
* Uncomment the selected locale in {{ic|/etc/locale.gen}} and generate it with the ''locale-gen'' utility.
 +
* Uncomment the selected locale in {{ic|/etc/locale.gen}} and generate it with {{ic|locale-gen}}.
 
* As of v197, ''udev'' no longer assigns network interface names according to the {{ic|wlan''X''}} and {{ic|eth''X''}} naming scheme.
 
* As of v197, ''udev'' no longer assigns network interface names according to the {{ic|wlan''X''}} and {{ic|eth''X''}} naming scheme.
 
* The Arch Linux install media includes the following partitioning tools: ''fdisk'', ''gdisk'', ''cfdisk'', ''cgdisk'', ''parted''.
 
* 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 {{ic|/etc/locale.gen}} and generate it with {{ic|locale-gen}}.
 
 
* If pacman fails to verify your packages, check the system time with {{ic|cal}}.
 
* If pacman fails to verify your packages, check the system time with {{ic|cal}}.
 
* Set a root password with {{ic|passwd}}.
 
* Set a root password with {{ic|passwd}}.
Line 144: Line 133:
 
Use {{ic|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.
 
Use {{ic|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.
  
 +
====Examples====
 
* At the end of the string type {{ic|nomodeset}} and press {{ic|Enter}}. Alternatively, try {{ic|1=video=SVIDEO-1:d}} which, if it works, will not disable kernel mode setting.
 
* At the end of the string type {{ic|nomodeset}} and press {{ic|Enter}}. Alternatively, try {{ic|1=video=SVIDEO-1:d}} which, if it works, will not disable kernel mode setting.
 
* Remove the {{ic|#}} in front of the [http://www.greendesktiny.com/support/knowledgebase_detail.php?ref=EUH-483 locale] you want from {{ic|/etc/locale.gen}}.
 
* Remove the {{ic|#}} in front of the [http://www.greendesktiny.com/support/knowledgebase_detail.php?ref=EUH-483 locale] you want from {{ic|/etc/locale.gen}}.
Line 150: Line 140:
 
Use ''italic''.
 
Use ''italic''.
  
 +
====Example====
 
* Pacman is written in the C programming language and uses the ''.pkg.tar.xz'' package format.
 
* Pacman is written in the C programming language and uses the ''.pkg.tar.xz'' package format.
  
 
===File names and paths===
 
===File names and paths===
Use {{ic|monospace}}.
+
Use {{ic|monospace}}. Also device names and names with wildcards are affected. [[#File extensions]] are treated differently, though.
  
 +
====Examples====
 
* To test if you have booted into UEFI mode check if directory {{ic|/sys/firmware/efi}} has been created.
 
* To test if you have booted into UEFI mode check if directory {{ic|/sys/firmware/efi}} has been created.
 
* All files and directories appear under the root directory {{ic|/}}, even if they are stored on different physical devices.
 
* All files and directories appear under the root directory {{ic|/}}, even if they are stored on different physical devices.
* Edit {{ic|resolv.conf}}, substituting your name servers' IP addresses and your local domain name.
+
* Edit {{ic|/etc/resolv.conf}}, substituting your name servers' IP addresses and your local domain name.
 
* Before installing, you may want to edit the {{ic|mirrorlist}} file and place your preferred mirror first.
 
* Before installing, you may want to edit the {{ic|mirrorlist}} file and place your preferred mirror first.
 +
* For kernel modules to load during boot, place a ''.conf'' file with a name based on the program that uses them in {{ic|/etc/modules-load.d/}}.
 +
* 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.
  
Also names with wildcards:
+
=== Generic words used in an improper or questionable way ===
* For kernel modules to load during boot, place a {{ic|*.conf}} file in {{ic|/etc/modules-load.d/}}, with a name based on the program that uses them.
+
Use "typewriter quotes".
  
Also device names:
+
====Example====
* 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.
+
* Words/letters when referenced as mere "text entities".
  
 
===GUI/TUI text===
 
===GUI/TUI text===
Use ''italic''. For example for menu entries:
+
Use ''italic''. For example for menu entries. When representing navigation in menus, use the "''>''" symbol, still in ''italic'', to separate the items.
  
 +
====Examples====
 
* Then, select ''Boot Arch Linux'' from the menu and press {{ic|Enter}} in order to begin with the installation.
 
* Then, select ''Boot Arch Linux'' from the menu and press {{ic|Enter}} in order to begin with the installation.
 
* 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.
 
* 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.
 
* Type {{ic|yes}} and choose ''Quit'' (or press {{ic|Q}}) to exit without making any more changes.
 
* Type {{ic|yes}} and choose ''Quit'' (or press {{ic|Q}}) to exit without making any more changes.
 +
* For plugins to be updated, you should check to have their update repositories enabled in ''Window > Preferences > Install/Update > Available Software Sites''.
  
 
===Important part of file/command line contents===
 
===Important part of file/command line contents===
Use '''bold'''. Since these contents are code themselves, when referenced outside of the template, {{ic|monospace}} should be preserved, as opposed to [[#Pseudo-variables]].
+
Use '''bold'''. Since these contents are code themselves, when referenced outside of the template, {{ic|monospace}} should be preserved.
  
 +
====Example====
 
* {{bc|# ln -s /usr/src/linux-'''$(uname -r)'''/include/generated/uapi/linux/version.h /usr/src/linux-'''$(uname -r)'''/include/linux/}}
 
* {{bc|# ln -s /usr/src/linux-'''$(uname -r)'''/include/generated/uapi/linux/version.h /usr/src/linux-'''$(uname -r)'''/include/linux/}}
 
: You can replace '''{{ic|$(uname -r)}}''' with any kernel not currently running.
 
: You can replace '''{{ic|$(uname -r)}}''' with any kernel not currently running.
Line 182: Line 179:
 
Use {{ic|monospace}}.
 
Use {{ic|monospace}}.
  
* You have to press a key (usually {{ic|Delete}}, {{ic|F1}}, {{ic|F2}}, {{ic|F11}} or {{ic|F12}}) during the POST.
+
====Example====
 +
* 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===
Use ''italic'' for package and package-group names. Affected by [[#First instances]].
+
Use ''italic''. Affected by [[#First instances]].
  
 +
====Example====
 
* The package ''wireless_tools'' then provides a basic set of tools for managing the wireless connection.
 
* The package ''wireless_tools'' then provides a basic set of tools for managing the wireless connection.
  
===Pseudo-variables===
+
=== Pseudo-variables in file/command line contents ===
Use ''italic''. When mentioning the variable outside of the template, it should drop {{ic|monospace}}.
+
 
 +
Use ''italic''. When mentioning a variable outside of the template, {{ic|monospace}} should be preserved.
 +
 
 +
Make sure that variables do not contain any spaces: underscores should be used in their place.  
  
* {{bc|# loadkeys ''layout''}}
+
Ensure naming consistency with the rest of the article, which may already use a pseudo-variable. For example do not introduce a new {{ic|''keyboardlayout''}} variable, if {{ic|''keyboard_layout''}} is already used.
: [...] where ''layout'' can be {{ic|fr}}, {{ic|uk}}, {{ic|dvorak}}, {{ic|be-latin1}}, etc.
+
 
 +
==== Example ====
 +
 
 +
* {{bc|# loadkeys ''keyboard_layout''}}
 +
: [...] where {{ic|''keyboard_layout''}} can be {{ic|fr}}, {{ic|uk}}, {{ic|dvorak}}, {{ic|be-latin1}}, etc.
 +
* Bring the interface up with {{ic|ip link set ''interface'' up}}.
 +
* You can connect to the network with:
 +
: {{bc|# wifi-menu ''interface_name''}}
 +
: Where {{ic|''interface_name''}} is the interface of your wireless chipset.
 +
 
 +
===Quotations===
 +
For inline quotations, use "typewriter quotes". For block quotations, use indentation through a line-initial colon without any additional punctuation or formatting.
 +
 
 +
====Examples====
 +
* "All your data belongs to us" &ndash; Google
 +
* From http://www.x.org/wiki/:
 +
: The X.Org project provides an open source implementation of the X Window System. The development work is being done in conjunction with the freedesktop.org community. The X.Org Foundation is the educational non-profit corporation whose Board serves this effort, and whose Members lead this work.
 +
 
 +
===References to titles, headings...===
 +
Use "typewriter quotes". When referencing section headings, however, use internal anchor links ({{ic|<nowiki>[[#Section]]</nowiki>}}).
 +
 
 +
====Example====
 +
* The column "dm-crypt +/- LUKS" denotes features of dm-crypt for both LUKS ("+") and plain ("-") encryption modes. If a specific feature requires using LUKS, this is indicated by "(with LUKS)". Likewise "(without LUKS)" indicates usage of LUKS is counter-productive to achieve the feature and plain mode should be used.
  
 
===Repository names===
 
===Repository names===
 
Use ''italic'' for repository names. Affected by [[#First instances]].
 
Use ''italic'' for repository names. Affected by [[#First instances]].
  
* If you enable ''testing'', you must also enable ''community-testing''.
+
====Example====
 +
* To enable the ''testing'' repository, you have to uncomment the {{ic|[testing]}} section in {{ic|/etc/pacman.conf}}.
 +
* If you enable the ''testing'' repository, you must also enable the ''community-testing'' repository.
  
 
===Stressed/strong words or statements===
 
===Stressed/strong words or statements===
 
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.
 
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.
  
 +
When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in '''bold'''.
 +
 +
The same goes for very important statements that cannot be put in a separate Warning or Note as they are an essential part of the section itself.
 +
 +
====Examples====
 
* Choose the best environment for ''your'' needs.
 
* Choose the best environment for ''your'' needs.
 
* This command can synchronize the repository databases ''and'' update the system's packages.
 
* This command can synchronize the repository databases ''and'' update the system's packages.
Line 208: Line 239:
 
* [...] so please type it ''exactly'' as you see it.
 
* [...] so please type it ''exactly'' as you see it.
 
* If you want, you can make it the ''only'' mirror available by getting rid of everything else.
 
* If you want, you can make it the ''only'' mirror available by getting rid of everything else.
 
When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in '''bold'''.
 
 
 
* Partitioning can destroy data. You are '''strongly''' cautioned and advised to backup any critical data before proceeding.
 
* Partitioning can destroy data. You are '''strongly''' cautioned and advised to backup any critical data before proceeding.
 
* keep up to date with changes in Arch Linux that require manual intervention '''before''' upgrading your system.
 
* keep up to date with changes in Arch Linux that require manual intervention '''before''' upgrading your system.
 
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.'''
 
* '''When performing a system update, it is essential that users read all information output by pacman and use common sense.'''
 
* This means that partial upgrades are '''not supported'''.
 
* This means that partial upgrades are '''not supported'''.
  
 
===Technical terms===
 
===Technical terms===
Use ''italic''.
+
Use ''italic'', except for all-caps terms (usually acronyms). Affected by [[#First instances]].
  
 +
====Examples====
 
* You are encouraged to type {{ic|man ''command''}} to read the ''man'' page of any command.
 
* You are encouraged to type {{ic|man ''command''}} to read the ''man'' page of any command.
 
* This article deals with so-called ''core'' utilities on a GNU/Linux system.
 
* This article deals with so-called ''core'' utilities on a GNU/Linux system.
 
* ''Primary'' partitions can be bootable and are limited to four partitions per disk or RAID volume.
 
* ''Primary'' partitions can be bootable and are limited to four partitions per disk or RAID volume.
 
* This is already a separate partition by default, by virtue of being mounted as ''tmpfs'' by systemd.
 
* This is already a separate partition by default, by virtue of being mounted as ''tmpfs'' by systemd.
 +
* You have to press a key (usually {{ic|Delete}}, {{ic|F1}}, {{ic|F2}}, {{ic|F11}} or {{ic|F12}}) during the POST (Power On Self-Test) phase.
  
All-caps terms (usually acronyms) are excepted, though:
+
=== Words/letters when referenced as mere "text entities" ===
 +
Use "typewriter quotes".
  
* You have to press a key (usually {{ic|Delete}}, {{ic|F1}}, {{ic|F2}}, {{ic|F11}} or {{ic|F12}}) during the POST (Power On Self-Test) phase.
+
====Examples====
 +
* When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in '''bold'''.
 +
* If you are unsure, your Ethernet interface is likely to start with the letter "e", and unlikely to be {{ic|lo}} or start with the letter "w".

Revision as of 14:19, 2 December 2016

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

General rules

These general rules always override #Specific cases. For cases not covered in this guide, Wikipedia:Manual of Style is the authority reference.

  • Do not mix more than one highlighting method except where explicitly allowed by these rules.
    This rule also applies in the cases where some formatting is already set by CSS rules, for example bold in definition list terms. If the preset CSS formatting is not allowed on the affected item (e.g. bold on #File names and paths), then you have to resort using a different, compatible wiki markup altogether (e.g. bullet points instead of a definition list).
  • 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 (see below) 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.
  • If the name is already introduced by the title of the article or by a section heading, its first relevant appearance in the body can only be used as a link anchor, but not simply highlighted in bold, except in the case of #Name/term lists.
  • First-instance highlighting can be applied only to the #Specific cases that explicitly allow it.

Links

  • No formatting shall be applied to the anchor text of links.

Name/term lists

  • It is allowed, not mandatory, to keep consistent formatting in lists of names or terms, even if normally not all of the items would require to be formatted. This can involve for example 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.
    "List" is to be intended in a broad sense, so that for example also all the initial words of a series of subsequent paragraphs could be considered forming a list of terms.

Cases by formatting/punctuation

Cases marked by 1 are affected by #First instances. Cases marked by m apply to monospaced text.

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

Specific cases

#General rules always override the following rules.

Acronym/abbreviation expansions

Use italic.

Examples

  • Pacman is the Arch Linux package manager.
  • cat (catenate) is a standard Unix utility that concatenates and lists files.

CLI lines

Use monospace. Must be inline command examples, not simple mentions of #Executable/application names. Also console output and text that may reasonably be useful to paste in a terminal.

Examples

  • 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.
  • Execute pacman -Syu with root privileges.

Configuration parameters, variables, options, properties...

Use monospace. Also affects command options, user groups, IP addresses, environment variables and variables in general.

When both the short and long form of a command option have to be represented, use the "/" symbol without spaces to separate them, for example -a/--anything.

Examples

  • 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.
  • The -i switch can be omitted if you wish to install every package from the base group without prompting.
  • 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.
  • 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.
  • [...] this roughly equates to what you included in the DAEMONS array.
  • If you are running a private network, it is safe to use IP addresses in 192.168.*.* for your IP addresses, with a subnet mask of 255.255.255.0 and a broadcast address of 192.168.*.255. The gateway is usually 192.168.*.1 or 192.168.*.254.
  • By giving the -net nic argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address 52:54:00:12:34:56.

Daemons/services, kernel modules

Use monospace.

Example

  • The dhcpcd.service starts the daemon for all network interfaces.
  • Some unit names contain an @ sign (e.g. name@string.service).

Executable/application names

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

Note that this rule applies to executables only 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.

Examples

  • Uncomment the selected locale in /etc/locale.gen and generate it with the locale-gen utility.
  • Uncomment the selected locale in /etc/locale.gen and generate it with locale-gen.
  • 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.
  • 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.

Examples

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

Example

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

File names and paths

Use monospace. Also device names and names with wildcards are affected. #File extensions are treated differently, though.

Examples

  • 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 /etc/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.
  • For kernel modules to load during boot, place a .conf file with a name based on the program that uses them in /etc/modules-load.d/.
  • 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.

Generic words used in an improper or questionable way

Use "typewriter quotes".

Example

  • Words/letters when referenced as mere "text entities".

GUI/TUI text

Use italic. For example for menu entries. When representing navigation in menus, use the ">" symbol, still in italic, to separate the items.

Examples

  • Then, select Boot Arch Linux from the menu and press Enter in order to begin with the installation.
  • 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.
  • Type yes and choose Quit (or press Q) to exit without making any more changes.
  • For plugins to be updated, you should check to have their update repositories enabled in Window > Preferences > Install/Update > Available Software Sites.

Important part of file/command line contents

Use bold. Since these contents are code themselves, when referenced outside of the template, monospace should be preserved.

Example

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

Keyboard keys

Use monospace.

Example

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

Package and group names

Use italic. Affected by #First instances.

Example

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

Pseudo-variables in file/command line contents

Use italic. When mentioning a variable outside of the template, monospace should be preserved.

Make sure that variables do not contain any spaces: underscores should be used in their place.

Ensure naming consistency with the rest of the article, which may already use a pseudo-variable. For example do not introduce a new keyboardlayout variable, if keyboard_layout is already used.

Example

  • # loadkeys keyboard_layout
[...] where keyboard_layout can be fr, uk, dvorak, be-latin1, etc.
  • Bring the interface up with ip link set interface up.
  • You can connect to the network with:
# wifi-menu interface_name
Where interface_name is the interface of your wireless chipset.

Quotations

For inline quotations, use "typewriter quotes". For block quotations, use indentation through a line-initial colon without any additional punctuation or formatting.

Examples

The X.Org project provides an open source implementation of the X Window System. The development work is being done in conjunction with the freedesktop.org community. The X.Org Foundation is the educational non-profit corporation whose Board serves this effort, and whose Members lead this work.

References to titles, headings...

Use "typewriter quotes". When referencing section headings, however, use internal anchor links ([[#Section]]).

Example

  • The column "dm-crypt +/- LUKS" denotes features of dm-crypt for both LUKS ("+") and plain ("-") encryption modes. If a specific feature requires using LUKS, this is indicated by "(with LUKS)". Likewise "(without LUKS)" indicates usage of LUKS is counter-productive to achieve the feature and plain mode should be used.

Repository names

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

Example

  • To enable the testing repository, you have to uncomment the [testing] section in /etc/pacman.conf.
  • If you enable the testing repository, you must also enable the community-testing repository.

Stressed/strong words or statements

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.

When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in bold.

The same goes for very important statements that cannot be put in a separate Warning or Note as they are an essential part of the section itself.

Examples

  • Choose the best environment for your needs.
  • This command can synchronize the repository databases and update the system's packages.
  • If the screen does not go blank and the boot process gets stuck.
  • [...] so please type it exactly as you see it.
  • If you want, you can make it the only mirror available by getting rid of everything else.
  • Partitioning can destroy data. You are strongly cautioned and advised to backup any critical data before proceeding.
  • keep up to date with changes in Arch Linux that require manual intervention before upgrading your system.
  • When performing a system update, it is essential that users read all information output by pacman and use common sense.
  • This means that partial upgrades are not supported.

Technical terms

Use italic, except for all-caps terms (usually acronyms). Affected by #First instances.

Examples

  • You are encouraged to type man command to read the man page of any command.
  • This article deals with so-called core utilities on a GNU/Linux system.
  • Primary partitions can be bootable and are limited to four partitions per disk or RAID volume.
  • This is already a separate partition by default, by virtue of being mounted as tmpfs by systemd.
  • You have to press a key (usually Delete, F1, F2, F11 or F12) during the POST (Power On Self-Test) phase.

Words/letters when referenced as mere "text entities"

Use "typewriter quotes".

Examples

  • When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in bold.
  • 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".