Difference between revisions of "Help:Style"

From ArchWiki
Jump to: navigation, search
m (Edit summary: as a non-native speaker I've never understood if "patroller" is correct, but "patrol" seems to be more frequent)
(don't use a redlink for this, just use an obvious example article)
 
(134 intermediate revisions by 13 users not shown)
Line 2: Line 2:
 
[[es:Help:Style]]
 
[[es:Help:Style]]
 
[[it:Help:Style]]
 
[[it:Help:Style]]
 +
[[ja:ヘルプ:スタイル]]
 
[[ru:Help:Style]]
 
[[ru:Help:Style]]
 
[[zh-CN:Help:Style]]
 
[[zh-CN:Help:Style]]
{{Article summary start}}
+
[[zh-TW:Help:Style]]
{{Article summary text|This page gives guidelines for the standardization of style in ArchWiki articles.}}
+
{{Related articles start}}
{{Article summary heading|Related}}
+
{{Related|Help:Style/Formatting and punctuation}}
{{Article summary wiki|Help:Editing}}
+
{{Related|Help:Style/White space}}
{{Article summary wiki|Help:Reading}}
+
{{Related|Help:Editing}}
{{Article summary end}}
+
{{Related|Help:Reading}}
 
+
{{Related|Help:Discussion}}
 +
{{Related|Help:Template}}
 +
{{Related articles end}}
 
These style conventions encourage tidy, organized, and visually consistent articles. Follow them as closely as possible when editing the ArchWiki.
 
These style conventions encourage tidy, organized, and visually consistent articles. Follow them as closely as possible when editing the ArchWiki.
  
==Article pages==
+
== Article pages ==
===Title===
+
*If the subject of the article is commonly known both with the full name and the acronym, prefer using the full name in the title of the article. Do not include both the full name and the acronym (e.g. in parentheses) in the title, but rather use a [[Help:Editing#Redirects|redirect]] on the acronym page that points to the page titled with the full name.
+
*See also [[Article Naming Guidelines]].
+
  
===Layout===
+
=== Title ===
*Order elements in an article as follows:
+
#[[#Magic words]] (optional)
+
#[[#Categories]]
+
#[[#Interlanguage links]]
+
#[[#Article status templates]] (optional)
+
#[[#Article summary]] (optional)
+
#[[#Preface or introduction]]
+
#Table of contents (automatic)
+
#Article-specific sections
+
  
===Magic words===
+
* Titles should use [[Wikipedia:Letter case#Usage|sentence case]], e.g. "Title for new page" is correct, while "Title for New Page" is not. Note that common words that are part of a proper name or an upper-case acronym must be capitalized, e.g. "Advanced Linux Sound Architecture", not "Advanced Linux sound architecture". <br> Namespaces are not considered part of titles, so "ArchWiki:Example article" is correct, while "ArchWiki:example article" is not. Subpage names should start with a capital letter, so "My page/My subpage" is correct, while "My page/my subpage" is not.
*Behavior switches, and in general all the [[mw:Help:Magic words|magic words]] that change how an article is displayed or behaves but do not add content by themselves, should all go at the very top of the articles. <br> This rule applies in particular to {{ic|<nowiki>{{DISPLAYTITLE:title}}</nowiki>}} and [[Template:Lowercase title]], which makes use of the former.
+
* By default, the topic name in titles should be in the singular form; it should be in the plural form if it represents a group or class of something and is a countable noun or perceived as such.
 +
* If the subject of the article is commonly known both with the full name and the acronym, prefer using the full name in the title of the article. Do not include both the full name and the acronym (e.g. in parentheses) in the title, but rather use a [[Help:Editing#Redirects|redirect]] on the acronym page that points to the page titled with the full name.
 +
* Titles of localized pages must follow [[Help:i18n#Page titles]].
 +
* See the [[Help:Article naming guidelines]] article for more information.
  
===Categories===
+
=== Layout ===
*Every article must be categorized under at least one existing category.
+
*An article can belong to more than one category, provided one is not ancestor of the others.
+
*Categories must be included at the top of every article, right below any magic words. {{Note|This is different from some other MediaWiki projects such as Wikipedia, which include categories at the bottom.}}
+
*There should be no blank lines between categories and the first line of text (or interlanguage links, if present), because this introduces extra space at the top of the article.
+
*See also [[Recategorizing Pages]].
+
  
===Interlanguage links===
+
* Order elements in an article as follows:
*If the article has translations in the local or an external Arch Linux wiki, interlanguage links must be included right below the categories and above the first line of text. <br> Note that they will actually appear in the appropriate column to the left side of the page.
+
# [[#Magic words]] (optional)
*There should be no blank lines between interlanguage links and the first line of text, because this introduces extra space at the top of the article.
+
# [[#Categories]]
*When adding or editing interlanguage links you should take care of repeating your action for all the already existing translations.
+
# [[#Interlanguage links]]
*Do not add more than one interlanguage link for each language to an article.
+
# [[#Article status templates]] (optional)
*Do not add interlanguage links for the same language of the article.
+
# [[#Related articles box]] (optional)
*The interlanguage links must be sorted alphabetically based on the language tag, not the local name, so for example {{ic|<nowiki>[[fi:Title]]</nowiki>}} comes before {{ic|<nowiki>[[fr:Title]]</nowiki>}} even though "Suomi" would come after "Français".
+
# [[#Preface or introduction]]
*See also [[Help:i18n]] and  [[Wikipedia:Help:Interlanguage links]].
+
# Table of contents (automatic)
 +
# Article-specific sections
  
===Article status templates===
+
=== Magic words ===
*[[:Category:Template#Article_status_templates|Article status templates]] can be included right below the categories (or interlanguage links, if present) and right above the Article Summary.
+
*Article status templates can also be used inside article sections, when appropriate.
+
*Article status templates should always be accompanied by at least some words of explanation in the talk page.
+
  
===Article summary===
+
* Behavior switches&#8202;&mdash;&#8202;and in general, all of the [[mw:Help:Magic words|magic words]] that change how an article is displayed or behaves but do not add content by themselves&#8202;&mdash;&#8202;should all go at the very top of articles. <br> This rule applies in particular to {{ic|<nowiki>{{DISPLAYTITLE:title}}</nowiki>}} and [[Template:Lowercase title]], which makes use of the former.
*Describes the structure and scope of the article.
+
*Optionally included right below categories (or interlanguage links, or Article status templates, if present).
+
*See also [[Writing Article Overviews]].
+
  
===Preface or introduction===
+
=== Categories ===
*Describes the topic of the article. <br> Rather than paraphrasing or writing your own (possibly biased) description of a piece of software, you can use the upstream author's description, which can usually be found on the project's home page or about page, if it exists. An example is [[MediaTomb]].
+
*Included right below the Article summary.
+
*Do not explicitly make an {{Ic|1===Introduction==}} or {{Ic|1===Preface==}} section: let it appear above the first section heading. A table of contents is shown automatically between the preface and first section when there are sufficient sections in the article.
+
*See also [[Writing Article Introductions]].
+
  
===Section headings===
+
* Every article must be categorized under at least one existing category.
*Headings should start from level 2 ({{Ic|1===}}), because level 1 is reserved for article titles.
+
* An article can belong to more than one category, provided one is not ancestor of the others.
*Do not skip levels when making subsections, so a subsection of a level 2 needs a level 3 heading and so on.
+
* Categories must be included at the top of every article, right below any magic words. {{Note|This is different from some other MediaWiki projects such as Wikipedia, which include categories at the bottom.}}
*Headings use sentence case; ''not'' title case: ''My new heading''; not ''My New Heading''.
+
* There should be no blank lines between categories and the first line of text (or interlanguage links, if present), because this introduces extra space at the top of the article.
*Avoid using links in headings, since they break style consistency and do not stand out well enough. Usually the anchor text is also found in the section content, otherwise you can use a simple sentence like ''See also [[My New Page]]''. <br> For the same reason, also avoid using any kind of html or wiki markup code, including [[#Code formatting templates|code formatting templates]].
+
* See the [[Help:Category]] article for more information.
*See [[Effective Use of Headers]].
+
  
===Blank lines===
+
=== Interlanguage links ===
*Avoid using multiple blank lines to space out paragraphs or sections.
+
*See [[Help:Editing#Line breaks]] for more information.
+
  
===Code formatting templates===
+
* If the article has translations in the local or an external Arch Linux wiki, interlanguage links must be included right below the categories and above the first line of text. <br> Note that they will actually appear in the appropriate column to the left side of the page.
*Use {{ic|<nowiki>{{ic|code}}</nowiki>}} for short lines of code, file names, command names, variable names and the like to be represented inline, for example: <br> Run {{ic|sh ./hello_world.sh}} in the console.
+
* There should be no blank lines between interlanguage links and the first line of text, because this introduces extra space at the top of the article.
*Use {{ic|<nowiki>{{bc|code}}</nowiki>}} for single or multiple lines of code (command line input or output code and file content) to be represented in a proper frame, for example:
+
* When adding or editing interlanguage links you should take care of repeating your action for all the already existing translations.
{{bc|$ sh ./hello_world.sh}}
+
* Do not add more than one interlanguage link for each language to an article.
{{bc|Hello World}}
+
* Do not add interlanguage links for the same language of the article.
 +
* The interlanguage links must be sorted alphabetically based on the language tag, not the local name, so for example {{ic|<nowiki>[[fi:Title]]</nowiki>}} comes before {{ic|<nowiki>[[fr:Title]]</nowiki>}} even though "Suomi" would come after "Français".
 +
* See the [[Help:i18n]] and [[Wikipedia:Help:Interlanguage links]] articles for more information.
 +
 
 +
=== Article status templates ===
 +
 
 +
* [[Help:Template#Article_status_templates|Article status templates]] can be included right below the categories (or interlanguage links, if present) and right above the introduction (or the Related articles box, if present).
 +
* Article status templates can also be used inside article sections, when appropriate.
 +
* Always accompany an article status template with some words of explanation in the dedicated field (examples are provided in each template's page), possibly even opening a discussion in the talk page.
 +
 
 +
=== Related articles box ===
 +
 
 +
* Provides a simple list of related internal articles.
 +
* Optionally included right below categories (or interlanguage links, or Article status templates, if present).
 +
* It can only be made of [[Template:Related articles start]], [[Template:Related]] and [[Template:Related articles end]]. See also the guidelines in those pages.
 +
* Non-English articles can make use of [[Template:Related2]] for translating the anchor text.
 +
* Use the [[#"See also" sections|"See also" section]] for a more complete and detailed list that also includes link descriptions and interwiki or external links.
 +
 
 +
=== Preface or introduction ===
 +
 
 +
* Describes the topic of the article. <br> Rather than paraphrasing or writing your own (possibly biased) description of a piece of software, you can use the upstream author's description, which can usually be found on the project's home page or about page, if it exists. An example is [[MediaTomb]].
 +
* Included right above the first section of the article.
 +
* Do not explicitly make an {{Ic|1===Introduction==}} or {{Ic|1===Preface==}} section: let it appear above the first section heading. A table of contents is shown automatically between the preface and first section when there are sufficient sections in the article.
 +
* See [[Help:Writing article introductions]] for more information.
 +
 
 +
=== Section headings ===
 +
 
 +
* Headings should start from level 2 ({{Ic|1===}}), because level 1 is reserved for article titles.
 +
* Do not skip levels when making subsections, so a subsection of a level 2 needs a level 3 heading and so on.
 +
* Headings use sentence case; ''not'' title case: ''My new heading''; not ''My New Heading''.
 +
* Avoid using links in headings because they break style consistency and do not stand out well enough. Usually the anchor text is also found in the section content, otherwise you can use a simple sentence like:
 +
:: See [[main page|Some related article]] for more information.
 +
: For the same reason, also avoid using any kind of HTML or wiki markup code, including [[#Code formatting]] templates. See also [[Help:Style/Formatting and punctuation]].
 +
* See the [[Help:Effective use of headers]] articles for more information.
 +
 
 +
=== Code formatting ===
 +
 
 +
* Use {{ic|<nowiki>{{ic|code}}</nowiki>}} for short lines of code, file names, command names, variable names and the like to be represented inline, for example: <br> Run {{ic|sh ./hello_world.sh}} in the console.
 +
 
 +
* For single lines of code (command line input or output code and file content) to be represented in a proper frame, simply start them with a single space character, see also [[Help:Editing#Code]]. For example:
 +
 
 +
$ sh ./hello_world.sh
 +
 
 +
Hello World
 +
 
 +
* Use {{ic|<nowiki>{{bc|code}}</nowiki>}} for multiple lines of code (command line input or output code and file content) to be represented in a proper frame, for example:
 
{{bc|#!/bin/sh
 
{{bc|#!/bin/sh
  
 
# Demo
 
# Demo
 
echo "Hello World"}}
 
echo "Hello World"}}
:For short lines of code, you can just start them with a space instead of using {{ic|<nowiki>{{bc|code}}</nowiki>}} (see [[Help:Editing]]).
+
* Use {{ic|<nowiki>{{hc|input|output}}</nowiki>}} when in the need of representing both command line input and output, for example:
*Use {{ic|<nowiki>{{hc|input|output}}</nowiki>}} when in the need of representing both command line input and output, for example:
+
 
{{hc|$ sh ./hello_world.sh|Hello World}}
 
{{hc|$ sh ./hello_world.sh|Hello World}}
*When you need to represent file content and you feel it may be difficult for readers to understand which file that code refers to, you can also use {{ic|<nowiki>{{hc|filename|content}}</nowiki>}} to show the file name in the heading, for example:
+
* When you need to represent file content and you feel it may be difficult for readers to understand which file that code refers to, you can also use {{ic|<nowiki>{{hc|filename|content}}</nowiki>}} to show the file name in the heading, for example:
 
{{hc|~/hello_world.sh|<nowiki>
 
{{hc|~/hello_world.sh|<nowiki>
 
#!/bin/sh
 
#!/bin/sh
Line 93: Line 114:
 
# Demo
 
# Demo
 
echo "Hello World"</nowiki>}}
 
echo "Hello World"</nowiki>}}
*For guidelines about [[Template:Keypress]], see [[#Keyboard keys]].
 
*See also [[Help:Template]] for more information and for troubleshooting problems with template-breaking characters like {{ic|1==}} or {{ic|<nowiki>|</nowiki>}}.
 
  
===Command line text===
+
* For blocks of code such as a configuration file, consider focusing the reader to the relevant lines and ellipsing ({{ic|...}}) any surrounding, non-relevant content.
*Use {{Ic|$}} as a prompt for regular user commands; use {{Ic|#}} as a prompt for root commands. {{Note|Since {{Ic|#}} is also used to denote comments in text files, you should always make sure to avoid ambiguities, usually by explicitly writing to run the command or edit a text file.}}
+
*The sentence introducing a command should usually end with {{Ic|:}}.
+
*Prefer using {{Ic|# command}} instead of writing {{Ic|$ sudo command}} unless it is really necessary.
+
*Do not assume the user uses {{ic|[[sudo]]}} or other privilege escalation utilities (e.g. {{ic|gksu}}, {{ic|kdesu}}).
+
*{{Ic|# sudo command}} is redundant and must be avoided. The only exception is when {{Ic|sudo}} is used with the {{Ic|-u}} flag: in this case the prompt can match the others of the same code block, or default to {{Ic|$}}.
+
*Do not add comments in the same box of a command (e.g. {{Ic|# pacman -S foo  #Install package foo}})
+
*Avoid writing excessively long lines of code: use line-breaking techniques when possible.
+
  
===File editing requests===
+
* See the [[Help:Template]] article for more information and for troubleshooting problems with template-breaking characters like {{ic|1==}} or {{ic|<nowiki>|</nowiki>}}.
*Do not assume a specific text editor (nano, vim, emacs, ...) when requesting text file edits, except when necessary.
+
*Do not use implicit commands to request text file edits, unless strictly necessary. For example {{ic|$ echo -e "clear\nreset" >> ~/.bash_logout}} should better be:
+
:Append the following lines to {{ic|~/.bash_logout}}:
+
:{{bc|clear<br>reset}}
+
  
===Keyboard keys===
+
=== Command line text ===
*The standard way to represent keyboard keys in articles is using instances of [[Template:Keypress]].
+
*Letter keys should be represented in lower case: {{keypress|a}}. To represent upper-case letters, use {{keypress|Shift+a}} instead of {{keypress|Shift+A}} or {{keypress|A}}.
+
*The correct way to represent key combinations makes use of the {{ic|+}} symbol to join keys, with no additional spaces around it, in a single instance of the template: {{keypress|Ctrl+c}}. <br> {{keypress|Ctrl + c}}, {{keypress|Ctrl}}+{{keypress|c}}, {{keypress|Ctrl-c}} are non-compliant forms, and should be avoided.
+
*The following are the standard ways of representing some special keys:
+
**{{keypress|Shift}} (not {{keypress|SHIFT}})
+
**{{keypress|Ctrl}} (not {{keypress|CTRL}} or {{keypress|Control}})
+
**{{keypress|Alt}} (not {{keypress|ALT}})
+
**{{keypress|Super}} (not {{keypress|Windows}} or {{keypress|Mod}})
+
**{{keypress|Enter}} (not {{keypress|ENTER}} or {{keypress|Return}})
+
**{{keypress|Esc}} (not {{keypress|ESC}} or {{keypress|Escape}})
+
**{{keypress|Space}} (not {{keypress|SPACE}})
+
**{{keypress|Backspace}}
+
**{{keypress|Tab}}
+
**{{keypress|Ins}} (not {{keypress|INS}} or {{keypress|Insert}})
+
**{{keypress|Del}} (not {{keypress|DEL}} or {{keypress|Delete}})
+
**{{keypress|Print Screen}}
+
  
===Package management instructions===
+
* When using inline code ([[Template:ic]]), no prompt symbol is to be represented, but any notes about permissions must be added explicitly to the surrounding text.
====Official packages====
+
* When using block code ([[Template:bc]] or lines starting with a space character), use {{ic|$}} as a prompt for regular user commands; use {{ic|#}} as a prompt for root commands. {{Note|Because {{ic|#}} is also used to denote comments in text files, you should always make sure to avoid ambiguities, usually by explicitly writing to run the command or edit a text file.}}
*Please avoid using examples of pacman commands in order to give instructions for the installation of official packages: this has been established both for simplicity's sake (every Arch user should know [[pacman]]'s article by memory) and to avoid errors such as {{Ic|pacman -Sy package}} or possibly never-ending discussions like the choice between {{Ic|pacman -S package}} and {{Ic|pacman -Syu package}}. All the more reason you should not suggest the use of pacman frontends or wrappers. <br> Instead, just use a simple statement like: <br> <span style="margin:0 1em;"></span> [[pacman|Install]] {{Pkg|package}} from the [[official repositories]].<br> Or, if for example the application name differs from the package name: <br> <span style="margin:0 1em;"></span>''MyApplication'' can be [[pacman|installed]] with the package {{Pkg|my-app-pkg}}, available in the [[official repositories]]. <br> The instructions for the installation of a list of packages may appear as: <br> <span style="margin:0 1em;"></span> [[pacman|Install]] {{Pkg|package1}}, {{Pkg|package2}} and {{Pkg|package3}} from the [[official repositories]]. <br> You are granted the flexibility to adapt the wording to your specific article.
+
** The sentence introducing a command block should usually end with {{ic|:}}.
*Links to the referenced packages are mandatory and should be created using [[Template:Pkg]], for example {{Ic|<nowiki>{{Pkg|package}}</nowiki>}}.
+
**  Unless really necessary, prefer using: {{bc|# ''command''}} instead of writing: {{bc|$ sudo ''command''}}
*The above examples also make use of an implicit link to the [[pacman]] article (e.g. {{ic|<nowiki>[[pacman|Install]]</nowiki> ...}}) and one to [[official repositories]] ({{ic|<nowiki>[[official repositories]]</nowiki>}}): these are recommended to be used at least on the first occurrence of an installation request, especially in articles that are more likely to be visited by Arch novices.
+
** Do not use the root prompt and the ''sudo'' command together, like in: {{bc|# sudo ''command''}} The only exception is when ''sudo'' is used with the {{ic|-u}} flag: in this case the prompt can match the others of the same code block, or default to {{ic|$}}.
*Examples of pacman commands are nonetheless accepted and even recommended in the [[Beginners' Guide]] and its subpages.
+
** Do not add comments in the same box of a command, for example: {{bc|# pacman -S foo  #Install package foo}}
*If the package is hosted in [core], [extra] or [community], do not make reference to the repository, thus facilitating maintenance since it is not uncommon for a package to be moved to a different repository. If however the package is hosted in an official repository which is not enabled by default ([multilib], [testing], etc.), mentioning it is required, using a wording like: <br> <span style="margin:0 1em;"></span>[[pacman|Install]] {{Pkg|package}} from the official [[multilib|&#91;multilib&#93;]] repository.
+
** Avoid writing excessively long lines of code: use line-breaking techniques when possible.
 +
* Do not assume the user uses [[sudo]] or other privilege escalation utilities (e.g. ''gksu'', ''kdesu'').
  
====AUR packages====
+
=== File editing requests ===
*Please avoid using examples of how to install AUR packages, neither with the official method nor mentioning AUR helpers: every user who installs unofficial packages should have read the [[Arch User Repository]] article, and be aware of all the possible consequences on his system. <br> Instead, just use a simple statement like: <br> <span style="margin:0 1em;"></span> Install {{AUR|package}} from the [[Arch User Repository]]. <br> You are granted the flexibility to adapt the wording to your specific article, see the section on [[#Official packages]] for more examples.
+
*Links to the referenced packages are mandatory and should be created using [[Template:AUR]], for example {{Ic|<nowiki>{{AUR|package}}</nowiki>}}.
+
*You should always make clear that the package is unofficial, also linking to the [[Arch User Repository]] article or one of its redirects, e.g. [[AUR]].
+
  
===Kernel module operations===
+
* Do not assume a specific text editor (''nano'', ''vim'', ''emacs'', etc.) when requesting text file edits, except when necessary.
*Giving examples of how to load, remove, blacklist or perform any other basic operation with modules is deprecated: the standard phrasing is a list of the modules involved, possibly remarking dependencies or conflicts with other modules, a description of the actions to be performed, and a link to [[Kernel modules]].
+
* Do not use implicit commands to request text file edits, unless strictly necessary. For example, {{ic|$ echo -e "clear\nreset" >> ~/.bash_logout}} should be:
*The [[Beginners' Guide]] and its subpages are the only exceptions to the rule above.
+
::Append the following lines to {{ic|~/.bash_logout}}:
 +
::{{bc|clear<br>reset}}
 +
:Where it might be helpful, a link to [[Help:Reading#Append, add, create, edit]] can be added.
  
===Daemon operations===
+
=== Keyboard keys ===
*Giving examples of how to enable, start or perform any other basic operations with daemons is deprecated: the standard phrasing is a list of the daemons involved, possibly remarking dependencies or conflicts with other daemons, a description of the actions to be performed, and a link to [[systemd]].
+
*The [[Beginners' Guide]] and its subpages are the only exceptions to the rule above.
+
  
===Notes, Warnings, Tips===
+
* The standard way to represent keyboard keys in articles is using instances of [[Template:ic]].
 +
* Letter keys should be represented in lower case: {{ic|a}}. To represent upper-case letters, use {{ic|Shift+a}} instead of {{ic|Shift+A}} or {{ic|A}}.
 +
* The correct way to represent key ''combinations'' makes use of the {{ic|+}} symbol to join keys, with no additional spaces around it, in a single instance of the template: {{ic|Ctrl+c}}. <br> {{ic|Ctrl + c}}, {{ic|Ctrl}}+{{ic|c}}, {{ic|Ctrl-c}} are non-compliant forms, and should be avoided.
 +
* The correct way to represent key ''sequences'' is either verbose, e.g. "press {{ic|g}} followed by {{ic|Shift+t}}", or concise, separating the keys with a single space in different instances of the template: {{ic|g}} {{ic|Shift+t}}.
 +
* The following are the standard ways of representing some special keys:
 +
** {{ic|Shift}} (not {{ic|SHIFT}})
 +
** {{ic|Ctrl}} (not {{ic|CTRL}} or {{ic|Control}})
 +
** {{ic|Alt}} (not {{ic|ALT}})
 +
** {{ic|Super}} (not {{ic|Windows}} or {{ic|Mod}})
 +
** {{ic|Enter}} (not {{ic|ENTER}} or {{ic|Return}})
 +
** {{ic|Esc}} (not {{ic|ESC}} or {{ic|Escape}})
 +
** {{ic|Space}} (not {{ic|SPACE}})
 +
** {{ic|Backspace}}
 +
** {{ic|Tab}}
 +
** {{ic|Ins}} (not {{ic|INS}} or {{ic|Insert}})
 +
** {{ic|Del}} (not {{ic|DEL}} or {{ic|Delete}})
 +
** {{ic|PrintScreen}}
 +
** {{ic|PageUp}}
 +
** {{ic|PageDown}}
  
*A [[Template:Note|Note]] should be used for information that somehow diverges from what the user would naturally expect at some point in the article. This includes also information that gives more in-depth knowledge on something in particular that otherwise would be considered a bit extraneous to the article. Another example is when needing to point out a temporary announcement like a change in the name of a package. <br> A Note can also be used to highlight information that is important but easily overlooked by someone new to the subject area.
+
=== Package management instructions ===
*A [[Template:Warning|Warning]] should be used where the described procedure could carry severe consequences such as being reasonably difficult to undo or resulting in damage to the system. Warnings should generally indicate both the worst case scenarios as well as the conditions that could lead to or avoid such worst cases.
+
 
*A [[Template:Tip|Tip]] should indicate a method or procedure that could be useful and bring benefits to somebody, albeit not needed to complete the operation being dealt with, and therefore safely ignorable.
+
==== Official packages ====
*When two or more notes, warnings or tips have to appear one after each other at the same point of an article, prefer grouping their texts in a list inside a single template, avoiding stacking the templates unless they are completely unrelated. For example:
+
 
 +
* Please avoid using examples of ''pacman'' commands in order to give instructions for the installation of official packages: this has been established both for simplicity's sake (every Arch user should know [[pacman]]'s article by memory) and to avoid errors such as {{Ic|pacman -Sy package}} or possibly never-ending discussions like the choice between {{Ic|pacman -S package}} and {{Ic|pacman -Syu package}}. All the more reason you should not suggest the use of ''pacman'' frontends or wrappers.
 +
: Instead, just use a simple statement like:
 +
:: [[Install]] the {{Pkg|foobar}} package.
 +
: Or, if for example the application name differs from the package name:
 +
:: ''MyApplication'' can be [[install]]ed with the {{Pkg|my-app-pkg}} package.
 +
: The instructions for the installation of a list of packages may appear as:
 +
:: [[Install]] the {{Pkg|foobar1}}, {{Pkg|foobar2}} and {{Pkg|foobar3}} packages.
 +
: If referring to a package group you may use:
 +
:: [[Install]] the {{Grp|foobar}} group.
 +
: You are granted the flexibility to adapt the wording to your specific article.
 +
* Links to the referenced packages are mandatory and should be created using [[Template:Pkg]], for example {{ic|<nowiki>{{Pkg|foobar}}</nowiki>}}.
 +
: When referring to package groups, [[Template:Grp]] should be used instead, for example {{ic|<nowiki>{{Grp|foobar}}</nowiki>}}.
 +
* The above examples also make use of a link to [[install]] (e.g. {{ic|<nowiki>[[install]]</nowiki>}}): this is recommended to be used at least on the first occurrence of an installation request, especially in articles that are more likely to be visited by Arch novices.
 +
* Examples of ''pacman'' commands are nonetheless accepted and even recommended in the [[Beginners' guide]].
 +
* If the package is hosted in the ''core'', ''extra'', or ''community'' repositories, do not make reference to the repository, thus facilitating maintenance because it is not uncommon for a package to be moved to a different repository. If however the package is hosted in an official repository which is not enabled by default (''multilib'', ''testing'', etc.), mentioning it is required, using a wording like:
 +
::[[Install]] the {{Pkg|foobar}} package from the official [[multilib]] repository.
 +
 
 +
==== AUR packages ====
 +
 
 +
* Please avoid using examples of how to install AUR packages, neither with the official method nor mentioning AUR helpers. Every user who installs unofficial packages should have read the [[Arch User Repository]] article and be aware of all the possible consequences on his system.
 +
: Instead, just use a simple statement like:
 +
:: Install the {{AUR|foobar}} package.
 +
: You are granted the flexibility to adapt the wording to your specific article. See the section on [[#Official packages]] for more examples.
 +
* Links to the referenced packages are mandatory and should be created using [[Template:AUR]] (e.g. {{ic|<nowiki>{{AUR|foobar}}</nowiki>}}).
 +
 
 +
==== Unofficial repositories ====
 +
 
 +
* When suggesting to use an unofficial repository for installing a pre-built package, do not provide instructions for enabling the repository, but make sure such repository is included in [[Unofficial user repositories]] and then simply link to it. Also, just like with [[#Official packages|official packages]], do not add examples of ''pacman'' commands. For example:
 +
:: Install the ''foobar'' package from the [[Unofficial user repositories#example|example]] repository.
 +
: If the package is also available in the [[AUR]]:
 +
:: Install the {{AUR|foobar}} package, also available in the [[Unofficial user repositories#example|example]] repository.
 +
: If the package is available in the [[AUR]] with a different name:
 +
:: Install the {{AUR|aurpkg}} package, also available as ''builtpackage'' from the [[Unofficial user repositories#example|example]] repository.
 +
: You are granted the flexibility to adapt the wording to your specific article.
 +
* The link to [[Unofficial user repositories]] is mandatory and should point to the relevant repository section, for example {{ic|<nowiki>[[Unofficial user repositories#example|example]]</nowiki>}}.
 +
 
 +
=== systemd units operations ===
 +
 
 +
* Do not give examples of how to enable, start, or perform any other basic operations with ''systemctl'' on [[systemd]] units. Instead, use a simple sentence listing the units involved, possibly remarking dependencies or conflicts with other units, and a description of the actions to be performed. For example:
 +
:: To have GDM launched at boot time, [[enable]] {{ic|gdm.service}}.
 +
: Or, if for example the unit is a template that needs instantiation:
 +
:: To enable automatic switching of ''netctl'' profiles on a wireless interface, [[enable]] an instance of {{ic|netctl-auto@.service}} with the interface name, for example {{ic|netctl-auto@wlan0.service}}.
 +
: You are granted the flexibility to adapt the wording to your specific article.
 +
* Make sure to link to the [[systemd#Using units]] article section, either directly or through a dedicated [https://wiki.archlinux.org/index.php?title=Special:WhatLinksHere/Systemd&hidelinks=1&hidetrans=1 redirect] like {{ic|<nowiki>[[start]]</nowiki>}}, {{ic|<nowiki>[[enable]]</nowiki>}} or {{ic|<nowiki>[[stop]]</nowiki>}}.
 +
* Examples of ''systemctl'' commands are nonetheless accepted and even recommended in the [[Beginners' guide]].
 +
 
 +
=== Notes, Warnings, Tips ===
 +
 
 +
* A [[Template:Note|Note]] should be used for information that somehow diverges from what the user would naturally expect at some point in the article. This includes also information that gives more in-depth knowledge on something in particular that otherwise would be considered a bit extraneous to the article. Another example is when needing to point out a temporary announcement like a change in the name of a package.
 +
: A Note can also be used to highlight information that is important but easily overlooked by someone new to the subject area.
 +
* A [[Template:Warning|Warning]] should be used where the described procedure could carry severe consequences such as being reasonably difficult to undo or resulting in damage to the system. Warnings should generally indicate both the worst case scenarios as well as the conditions that could lead to or avoid such worst cases.
 +
: In general, do not abuse Warnings: if you are undecided, chances are high that you should use a Note.
 +
* A [[Template:Tip|Tip]] should indicate a method or procedure that could be useful and bring benefits to somebody, albeit not needed to complete the operation being dealt with, and therefore safely ignorable.
 +
* When two or more notes, warnings or tips have to appear one after each other at the same point of an article, prefer grouping their texts in a list inside a single template, avoiding stacking the templates unless they are completely unrelated. For example:
 
:{{Tip|
 
:{{Tip|
:*Tip example #1.
+
:* Tip example #1.
:*Tip example #2.}}
+
:* Tip example #2.}}
  
===Shells===
+
=== Shells ===
*Do not assume a particular shell as the user's shell (e.g. bash), except when really needed: try to be as shell-neutral as possible when writing or editing articles.
+
  
===Hypertext metaphor===
+
* Do not assume a particular shell as the user's shell (e.g. Bash), except when really needed: try to be as shell-neutral as possible when writing or editing articles.
*Try to interlink your article with as many others as you can, using the various keywords in the text.
+
*For technical terms like [[Wikipedia:system call|system call]] not covered by an article in the ArchWiki, link to the relevant Wikipedia page.
+
*When linking to other articles of the wiki do not use full URLs, but take advantage of the special syntax for interwiki links: {{Ic|<nowiki>[[Wiki Article]]</nowiki>}}. This will also let the wiki engine keep track of the internal links hence facilitating maintenance. <br> See [[Help:Editing#Links]] for in-depth information and more advanced uses of interwiki links syntax.
+
*Except in rare cases, you should not leave an article as a dead-end page (an article that does not link to any other) or an orphan page (an article that is not linked from any other).
+
*Before writing a specific procedure in an article, or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.
+
*If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.
+
*Do not use interwiki links for links to local pages of the same language of the article being edited, since they will not be shown in [[Special:WhatLinksHere]] pages. For example using {{ic|<nowiki>[[:hu:Main Page]]</nowiki>}} in a Hungarian article is wrong, while {{ic|<nowiki>[[Main Page (Magyar)]]</nowiki>}} is correct. <br> Using this kind of links between different languages is instead acceptable, since this would make it easier to move the articles to a separate wiki in case it is set up. <br> Finally, note the difference of this kind of links from [[#Interlanguage links]], which do not have the colon at the beginning.
+
  
==="Tips and tricks" sections===
+
=== Hypertext metaphor ===
*Advanced tips or examples of using the software.
+
*Standard title is ''Tips and tricks''.
+
*The various tips and tricks should be organized in subsections.
+
  
==="Troubleshooting" sections===
+
* Try to interlink your article with as many others as you can, using the various keywords in the text.
*Frequently asked questions regarding the software, or solutions to common problems (compare to [[#"Known issues" sections]]).
+
* Only link to a new article after creating it. In general, do not create links to non-existent articles.
*Standard title is ''Troubleshooting''; ''Trouble shooting'', ''Trouble-shooting'', ''TroubleShooting'' are common mistake examples.
+
* For technical terms, such as [[Wikipedia:system call|system call]], not covered by an article in the ArchWiki, link to the relevant Wikipedia page.
*You can also report temporary workarounds for known bugs, but in this case it is very desirable that you provide a link to the bug report, and in case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed. <br> There are great benefits in linking to a bug report both for readers and editors:
+
* When linking to other articles of the wiki, do not use full URLs; take advantage of the special syntax for internal links: {{Ic|<nowiki>[[Wiki Article]]</nowiki>}}. This will also let the wiki engine keep track of the internal links, hence facilitating maintenance. <br> See [[Help:Editing#Links]] for in-depth information and more advanced uses of interwiki links syntax.
 +
** Do not hide the anchor symbol in same-page section links (e.g. {{ic|<nowiki>[[#Links to sections of a document|Links to sections of a document]]</nowiki>}}). Besides the needless reformat, the anchor gives a clear indication that the link points to an article section, rather than a full article.
 +
* Avoid implicit links whenever possible. For example, prefer instructions like "See the [[systemd]] article for more information" instead of "See [[systemd|here]] for more information".
 +
* Except in rare cases, you should not leave an article as a dead-end page (an article that does not link to any other) or an orphan page (an article that is not linked to from any other).
 +
* Before writing a specific procedure in an article or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.
 +
* If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.
 +
* Do not use interwiki links for links to localized pages of the same language of the article being edited because they will not be shown in [[Special:WhatLinksHere]] pages. For example, using {{ic|<nowiki>[[:hu:Main page]]</nowiki>}} in a Hungarian article is wrong, while {{ic|<nowiki>[[Main page (Magyar)]]</nowiki>}} is correct. <br> Using this kind of links between different languages is instead acceptable because this would make it easier to move the articles to a separate wiki in case a separate wiki is created in the future. <br> Finally, note the difference of this kind of links from [[#Interlanguage links]], which do not have the colon at the beginning.
 +
 
 +
=== Coding style ===
 +
 
 +
* When adding commands or scripts, use a consistent coding style throughout the article, possibly also referring to the other articles, especially if there are any related ones. If available, respect the official or most common coding style guidelines for the language.
 +
* Avoid deprecated features of the programming/scripting language you are using: for example, use the {{ic|$()}} syntax for shell command substitution instead of the backticks/grave ({{ic|``}}) syntax.
 +
 
 +
=== Supported kernel versions ===
 +
 
 +
* Do not remove any notes or adaptations regarding kernel versions greater than or equal to the minimum version between the current {{Pkg|linux-lts}} package in the ''core'' repository and the kernel on the latest [https://www.archlinux.org/download/ installation media].
 +
 
 +
=== "Tips and tricks" sections ===
 +
 
 +
* ''Tips and tricks'' sections provide advanced tips or examples of using the software.
 +
* Use the standard title of ''Tips and tricks''.
 +
* The various tips and tricks should be organized in subsections.
 +
 
 +
=== "Troubleshooting" sections ===
 +
 
 +
* ''Troubleshooting'' sections are used for frequently asked questions regarding the software or for solutions to common problems (compare to [[#"Known issues" sections]]).
 +
* Use the standard title of ''Troubleshooting''. Common misspellings that should be avoided are ''Trouble shooting'', ''Trouble-shooting'', and ''TroubleShooting''.
 +
* You can also report temporary workarounds for known bugs, but in this case, it is very desirable that you provide a link to the bug report. In case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed. <br> There are great benefits in linking to a bug report both for readers and editors:
 
** For readers, the Wiki does not become a stopping point: they can find more information close to the source that may have otherwise been missed by their search efforts.
 
** For readers, the Wiki does not become a stopping point: they can find more information close to the source that may have otherwise been missed by their search efforts.
** For Wiki editors, it makes clean up easier by reducing the effort involved in researching whether the reported bug is still an issue; this can even lead to greater autonomy if the reader finds new information and comes back to edit the wiki.
+
** For Wiki editors, it makes cleanup easier by reducing the effort involved in researching whether the reported bug is still an issue; this can even lead to greater autonomy if the reader finds new information and comes back to edit the wiki.
 +
 
 +
=== "Known issues" sections ===
 +
 
 +
* ''Known issues'' sections are used for known bugs or usage problems which do not have a solution yet (compare to [[#"Troubleshooting" sections]]).
 +
* Use the standard title of ''Known issues''.
 +
* If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.
 +
 
 +
=== "See also" sections ===
 +
 
 +
* ''See also'' sections contain a list of links to references and sources of additional information.
 +
* This should be a list where each entry is started with {{Ic|*}}, which creates a MediaWiki bulleted list.
 +
* Use the standard title of ''See also''. Other similar titles such as ''External links'', ''More resources'', etc. should be avoided.
 +
 
 +
=== Non-pertinent content ===
 +
 
 +
* Please do not sign articles, nor credit article authors: the ArchWiki is a work of the community, and the history of each article is enough for crediting its contributors. <br> Reporting the sources used to write an article, though, is good practice: you can use the "See also" section for this purpose.
 +
* Uploading files is disabled for normal users, and including the existing images in articles is not allowed. As an alternative you can include links to external images or galleries, and if you need to draw simple diagrams you may use an ASCII editor like [http://www.asciiflow.com/ Asciiflow]. Rationale:
 +
** Maintenance: Arch is rolling release, and images would make updating articles much more difficult.
 +
** Necessity: Arch does not develop nor maintain any sort of GUI application, so we do not need to display any screenshot.
 +
** Moderation: free image upload would require time to be spent removing oversized or inappropriate images.
 +
** Accessibility: we support users with slow connections, text-only browsers, screen readers and the like.
 +
** Efficiency: images waste server bandwidth and storage space.
 +
** Simplicity: text-only articles just look simpler and tidier.
 +
 
 +
=== Language register ===
  
==="Known issues" sections===
+
* Articles should be written using formal, professional, and concise language. Care should be taken to remove grammar and orthography errors through edit previews and proofreading.
*Known bugs or usage problems which do not have a solution yet (compare to [[#"Troubleshooting" sections]]).
+
* Remember not only to answer ''how'', but also ''why''. Explanatory information always goes further toward imparting knowledge than does instruction alone.
*Standard title is ''Known issues''.
+
* Avoid contractions: "don't", "isn't", "you've", etc. should be "do not", "is not", and "you have", for example.
*If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.
+
* Avoid unnecessary [[Wikipedia:Shortening (grammar)|shortening]] of words: for example, instead of "repo", "distro", and "config", prefer "repository", "distribution", and "configuration". <br> In the same fashion, prefer using the long form of ''uncommon'' command options instead of their single-character counterpart.
 +
* Do not omit terms that are necessary to give an exact, unambiguous meaning to a sentence. For example, always add the word "repository" when mentioning the name of a repository.
 +
* Do not use indefinite time references such as "currently", "at the time of writing" or "soon"; replace them with definite expressions such as "as of May 2015" etc.
 +
* Write objectively: do not include personal comments on articles; use discussion pages for this purpose. In general, do not write in first person.
 +
* When editing content, be consistent with the style used in the rest of the article. For example, if the reader is always addressed using the second person, this style should be adopted by the added content; the same goes if third person or passive voice are clearly dominant throughout the article.
 +
* When offering a choice among different options (pieces of software, methods to do something, etc.) do not explicitly recommend one over the others, but objectively describe the advantages and disadvantages of each, thus helping the reader to make the best decision for his personal case.
  
==="See also" sections===
+
== Category pages ==
*A list of links to references and sources of additional information.
+
*This should be a list where each entry is started with {{Ic|*}}.
+
*The standard title is ''See also'', other similar titles like ''External links'', ''More resources'' etc. should be avoided.
+
  
===Non-pertinent content===
+
* Every [[Help:Category|category]] must be appropriately categorized under at least one parent category, except for root categories, which are [[:Category:Archive]], [[:Category:DeveloperWiki]], [[:Category:Languages]], [[:Category:Maintenance]] and [[:Category:Sandbox]].
*Please do not sign articles, nor credit article authors: the ArchWiki is a work of the community, and the history of each article is enough for crediting its contributors. <br> Reporting the sources used to write an article, though, is good practice: you can use the "See also" section for this purpose.
+
* A category can be categorized under more than one category, provided one is not ancestor of the others.
*Uploading files is disabled for normal users, and including the existing images in articles is not allowed. As an alternative you can include links to external images or galleries, and if you need to draw simple diagrams you may use an ASCII editor like [http://www.asciiflow.com/ Asciiflow]. Rationale:
+
* Avoid circular relationships: two categories cannot be reciprocal ancestors.
**Maintenance: Arch is rolling release, and images would make updating articles much more difficult.
+
* Do not categorize a category under itself (self-categorized category).
**Necessity: Arch does not develop nor maintain any sort of GUI application, so we do not need to display any screenshot.
+
* Categories must be included at the top of the category page.
**Moderation: free image upload would require time to be spent removing oversized or inappropriate images.
+
* Categories should not redirect, except temporarily during [[Help:Procedures#Rename a category|renaming]].
**Accessibility: we support users with slow connections, text-only browsers, screen readers and the like.
+
* By default, category names should be in the singular form ("topic" categories); they should be in the plural form if the singular form can be used to describe ''one'' of its members ("set" categories).
**Efficiency: images waste server bandwidth and storage space.
+
**Simplicity: text-only articles just look simpler and tidier.
+
  
===Language register===
+
== Redirect pages ==
*Articles should be written using formal, professional and concise language.
+
*Remember not only to answer ''how'', but also ''why.'' Explanatory information always goes further toward imparting knowledge than does instruction alone.
+
*Avoid contractions: "don't," "isn't," "you've," etc. should be "do not," "is not," "you have," for example.
+
*Avoid unnecessary [[Wikipedia:Shortening (grammar)|shortening]] of words: for example instead of "repo," "distro," and "config," prefer "repository," "distribution," and "configuration."
+
*Write objectively: do not include personal comments on articles, use discussion pages for this purpose. In general, do not write in first person.
+
  
==Discussion pages==
+
* Redirect pages should contain only the redirect code and nothing else. The only exceptions are:
*Add new discussions at the bottom of discussion pages and with a proper heading. You can also make use of the {{ic|+}} tag at the top of each discussion page.
+
** [[ArchWiki:Archive|Archived]] pages, which are in fact redirects, must be categorized under [[:Category:Archive]].
*Indent your answers using colons at the beginning of new lines.
+
** [[Help:Procedures#Rename_a_category|Renamed categories]] can contain a [[Template:Archive]] flag.
*Do not edit your posts if somebody has already replied, otherwise you will break the flow of the discussion and make it difficult for others to further respond. Only striking (using {{Ic|<nowiki><s></nowiki>}} tags) words or sentences is allowed, but the related explanation should be given in a regular reply.
+
* Redirect only to internal articles; do not use interwiki redirections.
*Always append a signature ({{ic|<nowiki>~~~~</nowiki>}}) to your edits.
+
:Redirects using interlanguage links are exceptionally allowed in accordance with [[Help:i18n]] and upon authorization from the [[ArchWiki:Maintenance Team]].
*Discussion pages should not be categorized.
+
*You should take care to strike the header of exhausted discussions using {{Ic|<nowiki><s></nowiki>}} tags. <br> Exhausted discussions will be deleted a while after striking.
+
*See also [[Help:Editing#Discussion pages]].
+
  
==Category pages==
+
== User pages ==
*Every category must be appropriately categorized under at least one parent category, except for root categories. <br> Root categories are [[:Category:DeveloperWiki]], [[:Category:Languages]], [[:Category:Sandbox]] and [[:Category:Template]].
+
*A category can be categorized under more than one category, provided one is not ancestor of the others.
+
*Avoid circular relationships: two categories cannot be reciprocal ancestors.
+
*Do not categorize a category under itself (self-categorized category).
+
*Categories must be included at the top of the category page.
+
*Categories should not redirect.
+
  
==Redirect pages==
+
* Pages in the [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=&namespace=2 User] namespace cannot be categorized.
*Redirect pages should contain only the redirect code, nothing more.
+
* Pages in the [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=&namespace=2 User] namespace can only be linked from other pages in the ''User'' or ''talk'' namespaces, unless authorization to do otherwise is given by Administrators.
*Redirect only to internal articles; do not use interwiki redirections.
+
  
==Template pages==
+
== Generic rules ==
*See [[Help:Template]].
+
  
==User pages==
+
=== Edit summary ===
*User pages cannot be categorized.
+
  
==Generic rules==
+
See [[ArchWiki:Contributing#The 3 fundamental rules]].
===Edit summary===
+
*The changes made daily to the articles are bravely checked by dedicated and voluntary [[ArchWiki:Maintenance Team|patrols]], whom you must help by making sure that all your edits are accompanied by some explanation words in the "Summary" field of the editor page.
+
**If the edit is [[Wikipedia:Help:Minor edit|minor]], e.g. grammar or orthography corrections or the simple rewording of a sentence, a simple description of your edit is perfectly enough.
+
**If you are performing a major change, e.g. adding, moving, modifying or removing content, besides summarizing your edit, you should make sure to explain the reason ''why'' you edited the article, even linking to a discussion on the wiki or the forums, if one exists at all.
+
**An explanation is not mandatory in talk pages, where the ''why'' should be already evident. <br> When deleting exhausted discussions, however, some explanation words are required (e.g. "closed discussion," "fixed," etc.) and including also the title of the discussion could help retrieving it in the history in case it needs to be reopened.
+
:{{Tip|Take a look at the edit summaries in the [[Special:RecentChanges|Recent Changes]] to get an idea of what you should write in your summary, but be warned that unfortunately not all users respect these guidelines.}}
+
*When performing major changes to articles, you should better try to split your work in multiple edits, based on the logical steps needed to complete the change. <br> Especially when moving sections (both within the same article or between two articles), you should avoid also modifying their content in the same edit, otherwise it will be more difficult to check the consequent diff.
+
  
===HTML tags===
+
=== HTML tags ===
*Usage of HTML tags is generally discouraged: always prefer using wiki markup or templates when possible, see [[Help:Editing]] and related.
+
* Usage of HTML tags is generally discouraged: always prefer using wiki markup or templates when possible, see [[Help:Editing]] and related.
*When tempted to use {{ic|<nowiki><pre>code</pre></nowiki>}}, always resort to {{ic|<nowiki>{{bc|code}}</nowiki>}}. When tempted to use {{ic|<nowiki><tt>text</tt></nowiki>}} or {{ic|<nowiki><code>text</code></nowiki>}}, always resort to {{ic|<nowiki>{{ic|text}}</nowiki>}}.
+
* When tempted to use {{ic|<nowiki><pre>code</pre></nowiki>}}, always resort to {{ic|<nowiki>{{bc|code}}</nowiki>}}. When tempted to use {{ic|<nowiki><tt>text</tt></nowiki>}} or {{ic|<nowiki><code>text</code></nowiki>}}, always resort to {{ic|<nowiki>{{ic|text}}</nowiki>}}.
*Especially avoid HTML comments ({{ic|<nowiki><!-- comment --></nowiki>}}): it is likely that a note added in a HTML comment can be explicitly shown in the article's discussion page. <br> You can add an appropriate [[:Category:Template#Article_status_templates|Article status template]] in place of the comment.
+
* Especially avoid HTML comments ({{ic|<nowiki><!-- comment --></nowiki>}}): it is likely that a note added in a HTML comment can be explicitly shown in the article's discussion page. <br> You can add an appropriate [[Help:Template#Article_status_templates|Article status template]] in place of the comment.
*Use {{ic|<nowiki><br></nowiki>}} only when necessary: to start a new paragraph or break a line, put a blank line below it. <br> Common exceptions to this rule are when it is necessary to break a line in a list item and you cannot use a sub-item, or inside a template and you cannot use a list.
+
* Use {{ic|<nowiki><br></nowiki>}} only when necessary: to start a new paragraph or break a line, put a blank line below it. <br> Common exceptions to this rule are when it is necessary to break a line in a list item and you cannot use a sub-item, or inside a template and you cannot use a list.

Latest revision as of 02:56, 11 April 2016

These style conventions encourage tidy, organized, and visually consistent articles. Follow them as closely as possible when editing the ArchWiki.

Article pages

Title

  • Titles should use sentence case, e.g. "Title for new page" is correct, while "Title for New Page" is not. Note that common words that are part of a proper name or an upper-case acronym must be capitalized, e.g. "Advanced Linux Sound Architecture", not "Advanced Linux sound architecture".
    Namespaces are not considered part of titles, so "ArchWiki:Example article" is correct, while "ArchWiki:example article" is not. Subpage names should start with a capital letter, so "My page/My subpage" is correct, while "My page/my subpage" is not.
  • By default, the topic name in titles should be in the singular form; it should be in the plural form if it represents a group or class of something and is a countable noun or perceived as such.
  • If the subject of the article is commonly known both with the full name and the acronym, prefer using the full name in the title of the article. Do not include both the full name and the acronym (e.g. in parentheses) in the title, but rather use a redirect on the acronym page that points to the page titled with the full name.
  • Titles of localized pages must follow Help:i18n#Page titles.
  • See the Help:Article naming guidelines article for more information.

Layout

  • Order elements in an article as follows:
  1. #Magic words (optional)
  2. #Categories
  3. #Interlanguage links
  4. #Article status templates (optional)
  5. #Related articles box (optional)
  6. #Preface or introduction
  7. Table of contents (automatic)
  8. Article-specific sections

Magic words

  • Behavior switches — and in general, all of the magic words that change how an article is displayed or behaves but do not add content by themselves — should all go at the very top of articles.
    This rule applies in particular to {{DISPLAYTITLE:title}} and Template:Lowercase title, which makes use of the former.

Categories

  • Every article must be categorized under at least one existing category.
  • An article can belong to more than one category, provided one is not ancestor of the others.
  • Categories must be included at the top of every article, right below any magic words.
    Note: This is different from some other MediaWiki projects such as Wikipedia, which include categories at the bottom.
  • There should be no blank lines between categories and the first line of text (or interlanguage links, if present), because this introduces extra space at the top of the article.
  • See the Help:Category article for more information.

Interlanguage links

  • If the article has translations in the local or an external Arch Linux wiki, interlanguage links must be included right below the categories and above the first line of text.
    Note that they will actually appear in the appropriate column to the left side of the page.
  • There should be no blank lines between interlanguage links and the first line of text, because this introduces extra space at the top of the article.
  • When adding or editing interlanguage links you should take care of repeating your action for all the already existing translations.
  • Do not add more than one interlanguage link for each language to an article.
  • Do not add interlanguage links for the same language of the article.
  • The interlanguage links must be sorted alphabetically based on the language tag, not the local name, so for example [[fi:Title]] comes before [[fr:Title]] even though "Suomi" would come after "Français".
  • See the Help:i18n and Wikipedia:Help:Interlanguage links articles for more information.

Article status templates

  • Article status templates can be included right below the categories (or interlanguage links, if present) and right above the introduction (or the Related articles box, if present).
  • Article status templates can also be used inside article sections, when appropriate.
  • Always accompany an article status template with some words of explanation in the dedicated field (examples are provided in each template's page), possibly even opening a discussion in the talk page.

Related articles box

Preface or introduction

  • Describes the topic of the article.
    Rather than paraphrasing or writing your own (possibly biased) description of a piece of software, you can use the upstream author's description, which can usually be found on the project's home page or about page, if it exists. An example is MediaTomb.
  • Included right above the first section of the article.
  • Do not explicitly make an ==Introduction== or ==Preface== section: let it appear above the first section heading. A table of contents is shown automatically between the preface and first section when there are sufficient sections in the article.
  • See Help:Writing article introductions for more information.

Section headings

  • Headings should start from level 2 (==), because level 1 is reserved for article titles.
  • Do not skip levels when making subsections, so a subsection of a level 2 needs a level 3 heading and so on.
  • Headings use sentence case; not title case: My new heading; not My New Heading.
  • Avoid using links in headings because they break style consistency and do not stand out well enough. Usually the anchor text is also found in the section content, otherwise you can use a simple sentence like:
See Some related article for more information.
For the same reason, also avoid using any kind of HTML or wiki markup code, including #Code formatting templates. See also Help:Style/Formatting and punctuation.

Code formatting

  • Use {{ic|code}} for short lines of code, file names, command names, variable names and the like to be represented inline, for example:
    Run sh ./hello_world.sh in the console.
  • For single lines of code (command line input or output code and file content) to be represented in a proper frame, simply start them with a single space character, see also Help:Editing#Code. For example:
$ sh ./hello_world.sh
Hello World
  • Use {{bc|code}} for multiple lines of code (command line input or output code and file content) to be represented in a proper frame, for example:
#!/bin/sh

# Demo
echo "Hello World"
  • Use {{hc|input|output}} when in the need of representing both command line input and output, for example:
$ sh ./hello_world.sh
Hello World
  • When you need to represent file content and you feel it may be difficult for readers to understand which file that code refers to, you can also use {{hc|filename|content}} to show the file name in the heading, for example:
~/hello_world.sh
#!/bin/sh

# Demo
echo "Hello World"
  • For blocks of code such as a configuration file, consider focusing the reader to the relevant lines and ellipsing (...) any surrounding, non-relevant content.
  • See the Help:Template article for more information and for troubleshooting problems with template-breaking characters like = or |.

Command line text

  • When using inline code (Template:ic), no prompt symbol is to be represented, but any notes about permissions must be added explicitly to the surrounding text.
  • When using block code (Template:bc or lines starting with a space character), use $ as a prompt for regular user commands; use # as a prompt for root commands.
    Note: Because # is also used to denote comments in text files, you should always make sure to avoid ambiguities, usually by explicitly writing to run the command or edit a text file.
    • The sentence introducing a command block should usually end with :.
    • Unless really necessary, prefer using:
      # command
      instead of writing:
      $ sudo command
    • Do not use the root prompt and the sudo command together, like in:
      # sudo command
      The only exception is when sudo is used with the -u flag: in this case the prompt can match the others of the same code block, or default to $.
    • Do not add comments in the same box of a command, for example:
      # pacman -S foo  #Install package foo
    • Avoid writing excessively long lines of code: use line-breaking techniques when possible.
  • Do not assume the user uses sudo or other privilege escalation utilities (e.g. gksu, kdesu).

File editing requests

  • Do not assume a specific text editor (nano, vim, emacs, etc.) when requesting text file edits, except when necessary.
  • Do not use implicit commands to request text file edits, unless strictly necessary. For example, $ echo -e "clear\nreset" >> ~/.bash_logout should be:
Append the following lines to ~/.bash_logout:
clear
reset
Where it might be helpful, a link to Help:Reading#Append, add, create, edit can be added.

Keyboard keys

  • The standard way to represent keyboard keys in articles is using instances of Template:ic.
  • Letter keys should be represented in lower case: a. To represent upper-case letters, use Shift+a instead of Shift+A or A.
  • The correct way to represent key combinations makes use of the + symbol to join keys, with no additional spaces around it, in a single instance of the template: Ctrl+c.
    Ctrl + c, Ctrl+c, Ctrl-c are non-compliant forms, and should be avoided.
  • The correct way to represent key sequences is either verbose, e.g. "press g followed by Shift+t", or concise, separating the keys with a single space in different instances of the template: g Shift+t.
  • The following are the standard ways of representing some special keys:
    • Shift (not SHIFT)
    • Ctrl (not CTRL or Control)
    • Alt (not ALT)
    • Super (not Windows or Mod)
    • Enter (not ENTER or Return)
    • Esc (not ESC or Escape)
    • Space (not SPACE)
    • Backspace
    • Tab
    • Ins (not INS or Insert)
    • Del (not DEL or Delete)
    • PrintScreen
    • PageUp
    • PageDown

Package management instructions

Official packages

  • Please avoid using examples of pacman commands in order to give instructions for the installation of official packages: this has been established both for simplicity's sake (every Arch user should know pacman's article by memory) and to avoid errors such as pacman -Sy package or possibly never-ending discussions like the choice between pacman -S package and pacman -Syu package. All the more reason you should not suggest the use of pacman frontends or wrappers.
Instead, just use a simple statement like:
Install the foobar package.
Or, if for example the application name differs from the package name:
MyApplication can be installed with the my-app-pkg package.
The instructions for the installation of a list of packages may appear as:
Install the foobar1, foobar2 and foobar3 packages.
If referring to a package group you may use:
Install the foobar group.
You are granted the flexibility to adapt the wording to your specific article.
  • Links to the referenced packages are mandatory and should be created using Template:Pkg, for example {{Pkg|foobar}}.
When referring to package groups, Template:Grp should be used instead, for example {{Grp|foobar}}.
  • The above examples also make use of a link to install (e.g. [[install]]): this is recommended to be used at least on the first occurrence of an installation request, especially in articles that are more likely to be visited by Arch novices.
  • Examples of pacman commands are nonetheless accepted and even recommended in the Beginners' guide.
  • If the package is hosted in the core, extra, or community repositories, do not make reference to the repository, thus facilitating maintenance because it is not uncommon for a package to be moved to a different repository. If however the package is hosted in an official repository which is not enabled by default (multilib, testing, etc.), mentioning it is required, using a wording like:
Install the foobar package from the official multilib repository.

AUR packages

  • Please avoid using examples of how to install AUR packages, neither with the official method nor mentioning AUR helpers. Every user who installs unofficial packages should have read the Arch User Repository article and be aware of all the possible consequences on his system.
Instead, just use a simple statement like:
Install the foobarAUR package.
You are granted the flexibility to adapt the wording to your specific article. See the section on #Official packages for more examples.
  • Links to the referenced packages are mandatory and should be created using Template:AUR (e.g. {{AUR|foobar}}).

Unofficial repositories

  • When suggesting to use an unofficial repository for installing a pre-built package, do not provide instructions for enabling the repository, but make sure such repository is included in Unofficial user repositories and then simply link to it. Also, just like with official packages, do not add examples of pacman commands. For example:
Install the foobar package from the example repository.
If the package is also available in the AUR:
Install the foobarAUR package, also available in the example repository.
If the package is available in the AUR with a different name:
Install the aurpkgAUR package, also available as builtpackage from the example repository.
You are granted the flexibility to adapt the wording to your specific article.
  • The link to Unofficial user repositories is mandatory and should point to the relevant repository section, for example [[Unofficial user repositories#example|example]].

systemd units operations

  • Do not give examples of how to enable, start, or perform any other basic operations with systemctl on systemd units. Instead, use a simple sentence listing the units involved, possibly remarking dependencies or conflicts with other units, and a description of the actions to be performed. For example:
To have GDM launched at boot time, enable gdm.service.
Or, if for example the unit is a template that needs instantiation:
To enable automatic switching of netctl profiles on a wireless interface, enable an instance of netctl-auto@.service with the interface name, for example netctl-auto@wlan0.service.
You are granted the flexibility to adapt the wording to your specific article.
  • Make sure to link to the systemd#Using units article section, either directly or through a dedicated redirect like [[start]], [[enable]] or [[stop]].
  • Examples of systemctl commands are nonetheless accepted and even recommended in the Beginners' guide.

Notes, Warnings, Tips

  • A Note should be used for information that somehow diverges from what the user would naturally expect at some point in the article. This includes also information that gives more in-depth knowledge on something in particular that otherwise would be considered a bit extraneous to the article. Another example is when needing to point out a temporary announcement like a change in the name of a package.
A Note can also be used to highlight information that is important but easily overlooked by someone new to the subject area.
  • A Warning should be used where the described procedure could carry severe consequences such as being reasonably difficult to undo or resulting in damage to the system. Warnings should generally indicate both the worst case scenarios as well as the conditions that could lead to or avoid such worst cases.
In general, do not abuse Warnings: if you are undecided, chances are high that you should use a Note.
  • A Tip should indicate a method or procedure that could be useful and bring benefits to somebody, albeit not needed to complete the operation being dealt with, and therefore safely ignorable.
  • When two or more notes, warnings or tips have to appear one after each other at the same point of an article, prefer grouping their texts in a list inside a single template, avoiding stacking the templates unless they are completely unrelated. For example:
Tip:
  • Tip example #1.
  • Tip example #2.

Shells

  • Do not assume a particular shell as the user's shell (e.g. Bash), except when really needed: try to be as shell-neutral as possible when writing or editing articles.

Hypertext metaphor

  • Try to interlink your article with as many others as you can, using the various keywords in the text.
  • Only link to a new article after creating it. In general, do not create links to non-existent articles.
  • For technical terms, such as system call, not covered by an article in the ArchWiki, link to the relevant Wikipedia page.
  • When linking to other articles of the wiki, do not use full URLs; take advantage of the special syntax for internal links: [[Wiki Article]]. This will also let the wiki engine keep track of the internal links, hence facilitating maintenance.
    See Help:Editing#Links for in-depth information and more advanced uses of interwiki links syntax.
    • Do not hide the anchor symbol in same-page section links (e.g. [[#Links to sections of a document|Links to sections of a document]]). Besides the needless reformat, the anchor gives a clear indication that the link points to an article section, rather than a full article.
  • Avoid implicit links whenever possible. For example, prefer instructions like "See the systemd article for more information" instead of "See here for more information".
  • Except in rare cases, you should not leave an article as a dead-end page (an article that does not link to any other) or an orphan page (an article that is not linked to from any other).
  • Before writing a specific procedure in an article or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.
  • If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.
  • Do not use interwiki links for links to localized pages of the same language of the article being edited because they will not be shown in Special:WhatLinksHere pages. For example, using [[:hu:Main page]] in a Hungarian article is wrong, while [[Main page (Magyar)]] is correct.
    Using this kind of links between different languages is instead acceptable because this would make it easier to move the articles to a separate wiki in case a separate wiki is created in the future.
    Finally, note the difference of this kind of links from #Interlanguage links, which do not have the colon at the beginning.

Coding style

  • When adding commands or scripts, use a consistent coding style throughout the article, possibly also referring to the other articles, especially if there are any related ones. If available, respect the official or most common coding style guidelines for the language.
  • Avoid deprecated features of the programming/scripting language you are using: for example, use the $() syntax for shell command substitution instead of the backticks/grave (``) syntax.

Supported kernel versions

  • Do not remove any notes or adaptations regarding kernel versions greater than or equal to the minimum version between the current linux-lts package in the core repository and the kernel on the latest installation media.

"Tips and tricks" sections

  • Tips and tricks sections provide advanced tips or examples of using the software.
  • Use the standard title of Tips and tricks.
  • The various tips and tricks should be organized in subsections.

"Troubleshooting" sections

  • Troubleshooting sections are used for frequently asked questions regarding the software or for solutions to common problems (compare to #"Known issues" sections).
  • Use the standard title of Troubleshooting. Common misspellings that should be avoided are Trouble shooting, Trouble-shooting, and TroubleShooting.
  • You can also report temporary workarounds for known bugs, but in this case, it is very desirable that you provide a link to the bug report. In case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed.
    There are great benefits in linking to a bug report both for readers and editors:
    • For readers, the Wiki does not become a stopping point: they can find more information close to the source that may have otherwise been missed by their search efforts.
    • For Wiki editors, it makes cleanup easier by reducing the effort involved in researching whether the reported bug is still an issue; this can even lead to greater autonomy if the reader finds new information and comes back to edit the wiki.

"Known issues" sections

  • Known issues sections are used for known bugs or usage problems which do not have a solution yet (compare to #"Troubleshooting" sections).
  • Use the standard title of Known issues.
  • If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.

"See also" sections

  • See also sections contain a list of links to references and sources of additional information.
  • This should be a list where each entry is started with *, which creates a MediaWiki bulleted list.
  • Use the standard title of See also. Other similar titles such as External links, More resources, etc. should be avoided.

Non-pertinent content

  • Please do not sign articles, nor credit article authors: the ArchWiki is a work of the community, and the history of each article is enough for crediting its contributors.
    Reporting the sources used to write an article, though, is good practice: you can use the "See also" section for this purpose.
  • Uploading files is disabled for normal users, and including the existing images in articles is not allowed. As an alternative you can include links to external images or galleries, and if you need to draw simple diagrams you may use an ASCII editor like Asciiflow. Rationale:
    • Maintenance: Arch is rolling release, and images would make updating articles much more difficult.
    • Necessity: Arch does not develop nor maintain any sort of GUI application, so we do not need to display any screenshot.
    • Moderation: free image upload would require time to be spent removing oversized or inappropriate images.
    • Accessibility: we support users with slow connections, text-only browsers, screen readers and the like.
    • Efficiency: images waste server bandwidth and storage space.
    • Simplicity: text-only articles just look simpler and tidier.

Language register

  • Articles should be written using formal, professional, and concise language. Care should be taken to remove grammar and orthography errors through edit previews and proofreading.
  • Remember not only to answer how, but also why. Explanatory information always goes further toward imparting knowledge than does instruction alone.
  • Avoid contractions: "don't", "isn't", "you've", etc. should be "do not", "is not", and "you have", for example.
  • Avoid unnecessary shortening of words: for example, instead of "repo", "distro", and "config", prefer "repository", "distribution", and "configuration".
    In the same fashion, prefer using the long form of uncommon command options instead of their single-character counterpart.
  • Do not omit terms that are necessary to give an exact, unambiguous meaning to a sentence. For example, always add the word "repository" when mentioning the name of a repository.
  • Do not use indefinite time references such as "currently", "at the time of writing" or "soon"; replace them with definite expressions such as "as of May 2015" etc.
  • Write objectively: do not include personal comments on articles; use discussion pages for this purpose. In general, do not write in first person.
  • When editing content, be consistent with the style used in the rest of the article. For example, if the reader is always addressed using the second person, this style should be adopted by the added content; the same goes if third person or passive voice are clearly dominant throughout the article.
  • When offering a choice among different options (pieces of software, methods to do something, etc.) do not explicitly recommend one over the others, but objectively describe the advantages and disadvantages of each, thus helping the reader to make the best decision for his personal case.

Category pages

  • Every category must be appropriately categorized under at least one parent category, except for root categories, which are Category:Archive, Category:DeveloperWiki, Category:Languages, Category:Maintenance and Category:Sandbox.
  • A category can be categorized under more than one category, provided one is not ancestor of the others.
  • Avoid circular relationships: two categories cannot be reciprocal ancestors.
  • Do not categorize a category under itself (self-categorized category).
  • Categories must be included at the top of the category page.
  • Categories should not redirect, except temporarily during renaming.
  • By default, category names should be in the singular form ("topic" categories); they should be in the plural form if the singular form can be used to describe one of its members ("set" categories).

Redirect pages

  • Redirect pages should contain only the redirect code and nothing else. The only exceptions are:
  • Redirect only to internal articles; do not use interwiki redirections.
Redirects using interlanguage links are exceptionally allowed in accordance with Help:i18n and upon authorization from the ArchWiki:Maintenance Team.

User pages

  • Pages in the User namespace cannot be categorized.
  • Pages in the User namespace can only be linked from other pages in the User or talk namespaces, unless authorization to do otherwise is given by Administrators.

Generic rules

Edit summary

See ArchWiki:Contributing#The 3 fundamental rules.

HTML tags

  • Usage of HTML tags is generally discouraged: always prefer using wiki markup or templates when possible, see Help:Editing and related.
  • When tempted to use <pre>code</pre>, always resort to {{bc|code}}. When tempted to use <tt>text</tt> or <code>text</code>, always resort to {{ic|text}}.
  • Especially avoid HTML comments (<!-- comment -->): it is likely that a note added in a HTML comment can be explicitly shown in the article's discussion page.
    You can add an appropriate Article status template in place of the comment.
  • Use <br> only when necessary: to start a new paragraph or break a line, put a blank line below it.
    Common exceptions to this rule are when it is necessary to break a line in a list item and you cannot use a sub-item, or inside a template and you cannot use a list.