User:Larivact/drafts/Formatting and punctuation
This manual describes how articles on the ArchWiki should be formatted and punctuated, it complements Help:Style.
Bold, italic, monospace and quotation marks should only be used as described in this manual.
Punctuation
Use ASCII characters for punctuation, instead of typographic Unicode characters.
The only exception being the em dash, which can be inserted as — or —.
Quotation marks
Use typewriter quotes "..." instead of single quotes '...' or typographic quotes “...”.
Use cases:
- Inline quotations
- References to columns / rows
- the "Cache" column
- #Strings
- Words used in an improper or questionable way
- "text entities"
Formatting
- Do not use different highlighting methods from the ones defined in this section.
- Do not mix more than one highlighting method except where explicitly allowed by this manual.
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.
- Initial mentions of packages and package groups 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.
Emphasis
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:
- ... 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.
Italic
Use the MediaWiki syntax ''text'' instead of <i> tags.
Use cases:
- emphasis, see #Emphasis
- Acronym/abbreviation expansions
- ABS (Arch Build System)
- File extensions
- .pkg.tar.xz
- Full lower-case application/executable names
- the locale-gen utility
- Packages and package groups that were linked earlier.
- the wireless_tools package
- Repository names
- core, extra, community
- Technical terms
- tmpfs, cut buffer
- User interface text
- select Boot Arch Linux
Bold
Use the MediaWiki syntax '''bold text''' instead of <b> tags.
Use cases:
Monospace
Used for text that may be entered in a terminal and to improve readability of individual characters. See also Help:Style#Code formatting.
Use cases:
- Command-line input and output
ip link,-i,ping: unknown host
- Text like variables, parameters, user groups and IP addresses
LC_ALL,iommu=soft,audio,127.0.0.1
- File names, paths and content
mirrorlist,/etc/resolv.conf,nameserver
- Keyboard keys and shortcuts, see also Help:Style#Keyboard keys
Delete,F11,Ctrl+c
- #Strings
Emphasis in code
- Italic for pseudo-variables
man page
- Bold for important parts of file/command-line contents
pacman -Syu package_name
Elements
Links
- The anchor text of links shall not be formatted.
- A numbered external link that does not have a grammatical function should appear at the end of the sentence that it supports, immediately after a punctuation mark that terminates the sentence, unless such mark is a dash or a parenthesis, in which case the link shall be inserted immediately before it.
See also Help:Editing#Links.
Quotations
For inline quotations, use quotation marks. For example: "Talk is cheap. Show me the code." - Linus Torvalds
For block quotations, use indentation through a line-initial colon without any additional punctuation or formatting. For example:
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.
Strings
Words/letters when referenced as mere "text entities".
Generally quotation marks should be used. However if the character sequence contains consecutive confusable letters like "Il" (uppercase eye and lowercase ell) or "0O" (zero and uppercase o), monospace should be used instead.
Examples:
- words like "not", "only", "exactly", "strongly", "before"
- interfaces names are prefixed with "en", "wl", or "ww"
- you can test fonts for legibility with
Illegal1