User:Larivact/drafts/Formatting and punctuation

From ArchWiki
< User:Larivact
Revision as of 15:07, 26 January 2019 by Larivact (talk | contribs) (update comment)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
Comment: Non-authoritative alternative version of Help:Style/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 &mdash;.

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

  1. Do not use different highlighting methods from the ones defined in this section.
  2. 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