Difference between revisions of "Help:Reading"

From ArchWiki
Jump to: navigation, search
(Regular user or root: add alternative name for character for those not versed in American)
(Arch User Repository: add mention of base-devel to make the info more prominent, re Talk:Installation guide#Let.27s mention filesystem tools in pacstrap step)
 
(63 intermediate revisions by 12 users not shown)
Line 1: Line 1:
 
[[Category:Help]]
 
[[Category:Help]]
 
[[es:Help:Reading]]
 
[[es:Help:Reading]]
 +
[[ja:ヘルプ:読み方]]
 +
[[ru:Help:Reading]]
 +
[[zh-CN:Help:Reading]]
 +
[[zh-TW:Help:Reading]]
 +
{{Related articles start}}
 +
{{Related|Help:Searching}}
 +
{{Related|Help:Style}}
 +
{{Related articles end}}
 +
 
Because the vast majority of the ArchWiki contains indications that may need clarification for users new to GNU/Linux, this rundown of basic procedures was written both to avoid confusion in the assimilation of the articles and to deter repetition in the content itself.
 
Because the vast majority of the ArchWiki contains indications that may need clarification for users new to GNU/Linux, this rundown of basic procedures was written both to avoid confusion in the assimilation of the articles and to deter repetition in the content itself.
  
==Regular user or root==
+
== Regular user or root ==
 +
 
 
Some lines are written like so:
 
Some lines are written like so:
  '''#''' pacman -S kernel26
+
  # mkinitcpio -p linux
  
 
Others have a different prefix:
 
Others have a different prefix:
  '''$''' makepkg -s
+
  $ makepkg -s
  
The numeral or hash sign ('''#''') indicates that the line is to be entered as ''root'', whereas the dollar sign ('''$''') shows that the line is to be entered as a ''regular user''.
+
The numeral or hash sign ({{ic|#}}) indicates that the line is to be entered as ''root'', whereas the dollar sign ({{ic|$}}) shows that the line is to be entered as a ''regular user''.
 +
 
 +
{{Note|The commands prefixed with {{ic|#}} are intended to be executed from a ''root shell'', which can for example be easily accessed with {{ic|sudo -i}}. Running {{ic|sudo ''command''}} from an unprivileged shell instead of {{ic|''command''}} from a root shell will also work in most cases, with some notable exceptions such as [[Wikipedia:Redirection_(computing)|redirection]] and [[Wikipedia:Command substitution|substitution]], which strictly require a root shell. See also [[sudo]].}}
  
 
A notable exception to watch out for:
 
A notable exception to watch out for:
  '''#''' This alias makes ls colorize the listing
+
  # This alias makes ls colorize the listing
 
  alias ls='ls --color=auto'
 
  alias ls='ls --color=auto'
  
 
In this example, the context surrounding the numeral sign communicates that this is not to be run as a command; it should be edited into a file instead. So in this case, the numeral sign denotes a ''comment''. A comment can be explanatory text that will not be interpreted by the associated program. [[Bash]] scripts denotation for comments happens to coincide with the root ''PS1''.
 
In this example, the context surrounding the numeral sign communicates that this is not to be run as a command; it should be edited into a file instead. So in this case, the numeral sign denotes a ''comment''. A comment can be explanatory text that will not be interpreted by the associated program. [[Bash]] scripts denotation for comments happens to coincide with the root ''PS1''.
  
After further examination, "give away" signs include the uppercase character following the '''#''' sign. Usually, Unix commands are not written this way and most of the time they are short abbreviations instead of full-blown English words (e.g., ''Copy'' becomes {{ic|cp}}).
+
After further examination, "give away" signs include the uppercase character following the {{ic|#}} sign. Usually, Unix commands are not written this way and most of the time they are short abbreviations instead of full-blown English words (e.g., ''Copy'' becomes ''cp'').
  
 
Regardless, most articles make this easy to discern by notifying the reader:
 
Regardless, most articles make this easy to discern by notifying the reader:
Line 26: Line 38:
 
  alias ls='ls --color=auto
 
  alias ls='ls --color=auto
  
==''Append'', ''create'', ''edit'' and ''source''==
+
== Append, add, create, edit ==
When prompted to ''append'', ''add'', ''create'' or ''edit'', consider it an indication for using a text editor, such as [[nano]], in order to make changes to configuration file(s):
+
 
 +
When prompted to ''append'', ''add'', ''create'', or ''edit'' use a [[text editor]] to make changes to the specified file(s). For example, using [[nano]] the command to edit the file {{ic|/etc/bash.bashrc}} is:
 +
 
 
  # nano /etc/bash.bashrc
 
  # nano /etc/bash.bashrc
  
In programs, be it shells or otherwise, ''sourcing'' applies settings specified in a file. For Bash, sourcing can be done in a command prompt:
+
One can alternatively use [http://www.gnu.org/software/bash/manual/html_node/Redirections.html output redirection] to create or overwrite a file from a string. The following example creates or overwrites the contents of the file {{ic|/etc/hostname}} with the text {{ic|myhostname}}.
$ source /etc/bash.bashrc
+
and it can also happen in a file itself:
+
# This line includes settings from another file
+
source /etc/bash.bashrc
+
As a result, sourcing a file after alteration is an ''implied omission'' in the case of shell files.
+
  
However, not all articles will specify the nature of the changes to be made, nor ''which'' file to alter in the first place. This wiki builds-up on previous knowledge, such as common locations for files that are prone to sporadic editing.
+
# echo myhostname > /etc/hostname
  
==System-wide versus user-specific configuration==
+
Output redirection can also be used to append a string to a file. The following example appends the text {{ic|[custom-repo]}} to the file {{ic|/etc/pacman.conf}}.
It is important to remember that there are two different kinds of configurations on a GNU/Linux system. '''System-wide''' configuration affects all users. Since system-wide settings are generally located in the {{ic|/etc}} directory, root privileges are required in order to alter them. E.g., to apply a Bash setting that affects all users, {{ic|/etc/bash.bashrc}} should be modified.
+
 
 +
# echo "[custom-repo]" >> /etc/pacman.conf
 +
 
 +
== Source ==
 +
 
 +
Some applications, notably [[command-line shell]]s, use scripts for their configuration: after modifying them, they must be ''sourced'' in order for the changes to be applied. In the case of [[bash]], for example, this is done by running (you can also replace {{ic|source}} with {{ic|.}}):
 +
 
 +
$ source ~/.bashrc
 +
 
 +
When the wiki will suggest to modify such a configuration script, it will not explicitly remind you to source the file, and only in some cases it will point you to this section with a reminder link.
 +
 
 +
== Installation of packages ==
 +
 
 +
When an article invites to install some packages in the conventional way, it will not indicate the detailed instructions to do so, instead it will simply mention the names of the packages to be installed.
 +
 
 +
{{Note|Frequently, the [[install]] or [[installed]] links are used to point to this article section. However, as of March 2016 bugs handicap the feature:
 +
 
 +
* WebKit/Blink-based browsers (Chrome/chromium, Epiphany, Opera, qutebrowser, etc.) will not automatically scroll to the proper destination section (fixed in MediaWiki 1.27);
 +
* all the other browsers (e.g. Firefox) will scroll, but only if JavaScript is enabled.
 +
 
 +
Until the bugs are resolved, you will be able to read the name of the destination section in the URL's [[w:fragment identifier|fragment identifier]], and manually follow the respective link from the article's Table of Contents. See [[Help talk:Style#Links to redirects]] for more information.}}
 +
 
 +
The subsections below give an overview of the generic installation procedures depending on the package type.
 +
 
 +
=== Official packages ===
 +
 
 +
For packages from the [[official repositories]] you will read something like:
 +
 
 +
:Install the {{Pkg|foobar}} package.
 +
 
 +
This means that you have to run:
 +
 
 +
# pacman -S foobar
 +
 
 +
The [[pacman]] article contains detailed explanations to deal with package management in Arch Linux proficiently.
 +
 
 +
=== Arch User Repository ===
 +
 
 +
For packages from the [[Arch User Repository]] (AUR) you will read something like:
 +
 
 +
:Install the {{AUR|foobar}} package.
 +
 
 +
This means that in general you have to follow the {{AUR|foobar}} link, download the PKGBUILD archive, extract it, '''verify the content''' and finally run, in the same folder:
 +
 
 +
$ makepkg -sri
 +
 
 +
Note the {{Grp|base-devel}} group of packages is required to install packages from the AUR.
 +
 
 +
The [[Arch User Repository]] article contains all the detailed explanations and best practices to deal with AUR packages.
 +
 
 +
== Control of systemd units ==
 +
 
 +
When an article invites to ''start'', ''enable'', ''stop'' or ''restart'' some systemd units (e.g. a service), it will not indicate the detailed instructions to do so, but instead you will read something like:
 +
 
 +
:[[Start]] {{ic|example.service}}.
 +
 
 +
This means that you have to run:
 +
 
 +
# systemctl start example.service
 +
 
 +
The [[start]] link will lead you to the [[systemd]] article, which contains all the detailed explanations to deal with systemd units in Arch Linux proficiently.
 +
 
 +
{{Note|As of March 2016, the [[start]], [[enable]], [[stop]], [[restart]]... links are handicapped by the following MediaWiki bugs:
 +
 
 +
* WebKit/Blink-based browsers (Chrome/chromium, Epiphany, Opera, qutebrowser, etc.) will not automatically scroll to the proper destination section (fixed in MediaWiki 1.27);
 +
* all the other browsers (e.g. Firefox) will scroll, but only if JavaScript is enabled.
 +
 
 +
Until the bugs are resolved, you will be able to read the name of the destination section in the URL's [[w:fragment identifier|fragment identifier]], and manually follow the respective link from the article's Table of Contents. See [[Help talk:Style#Links to redirects]] for more information.}}
 +
 
 +
== System-wide versus user-specific configuration ==
 +
 
 +
It is important to remember that there are two different kinds of configurations on a GNU/Linux system. '''System-wide''' configuration affects all users. Since system-wide settings are generally located in the {{ic|/etc}} directory, root privileges are required in order to alter them. For example, to apply a Bash setting that affects all users, {{ic|/etc/bash.bashrc}} should be modified.
  
 
'''User-specific''' configuration affects only a single user. ''Dotfiles'' are used for user-specific configuration. For example, the file {{ic|~/'''.'''bashrc}} is the user-specific configuration file. The idea is that each user can define their own settings, such as aliases, functions and other interactive features like the prompt, without affecting other users' preferences.
 
'''User-specific''' configuration affects only a single user. ''Dotfiles'' are used for user-specific configuration. For example, the file {{ic|~/'''.'''bashrc}} is the user-specific configuration file. The idea is that each user can define their own settings, such as aliases, functions and other interactive features like the prompt, without affecting other users' preferences.
  
{{Note|{{ic|~/}} is a shortcut for the user's home directory, usually {{ic|/home/''username''/}}.}}
+
{{Note|{{ic|~/}} and {{ic|$HOME}} are shortcuts for the user's home directory, usually {{ic|/home/''username''/}}.}}
 +
 
 +
=== Common shell files ===
 +
 
 +
Bash and other Bourne-compatible shells, such as [[Zsh]], also source files depending on whether the shell is a ''login shell'' or an ''interactive shell''. See [[Bash#Configuration files]] and [[Zsh#Startup/Shutdown files]] for details.
 +
 
 +
== Pseudo-variables in code examples ==
 +
 
 +
Some code blocks may contain so-called ''pseudo-variables'', which, as the name says, are not actual variables used in the code. Instead they are generic placeholders and have to be manually replaced with system-specific configuration items '''before''' the code may be run or parsed. Common shells such as [[bash]] and [[zsh]] provide [[w:Command-line_completion|tab-completion]] to auto-complete parameters for common commands such as ''systemctl''.
  
===Common shell files===
+
In the articles that comply with [[Help:Style/Formatting and punctuation]], ''pseudo-variables'' are formatted in italics. For example:
For ease of use, here is a selective listing of basic configuration files and their locations.
+
  
====Bash====
+
* [[Enable]] the {{ic|dhcpcd@''interface_name''.service}} for the network interface identified from the output of the {{ic|ip link}} command.
''See also: [[Bash]] and {{ic|man bash}}''
+
  
Within Bash and other bourne-compatible shells, such as [[Zsh]], there is even further differentiation in the purposes of the configuration files. Some files only get sourced when Bash is starting as a ''login shell'', whereas other files only do so when Bash is an ''interactive shell''.
+
In this case {{ic|''interface_name''}} is used as a ''pseudo-variable'' placeholder in a systemd template unit. All systemd template units, identifiable by the {{ic|@}} sign, require a system-specific configuration item as argument. See [[Systemd#Using units]].  
  
When Bash is run in a ''virtual console'', for instance, it is started as a login shell. Bash shells started in a [[Xorg]] session, such as those employed by [[xterm]], are interactive shells.
+
* The command {{ic|1=dd if=''data_source'' of=/dev/sd"X" bs=''sector_size'' count=''sector_number'' seek=''partitions_start_sector''}} can be run as root to wipe a partition with the specific parameters.  
  
Common files:
+
In this case the ''pseudo-variables'' are used to describe the parameters that must be substituted for them. Details on how to gather them are elaborated on in the section [[Securely wipe disk#Calculate blocks to wipe manually]], which features the command.
  
;{{ic|/etc/bash.bashrc}} : System-wide settings; sourced only by a login shell
+
{{Expansion|Mention other examples, ideally from other device categories (e.g. storage), with links to background articles. The examples are meant to avoid duplicating existing explanations in other articles.}}
  
;{{ic|~/.bashrc}} : Personal shell settings; sourced only by an interactive shell
+
In case of file examples, pasting pseudo-variables in real configuration files might break the programs that use them.
  
====Zsh====
+
=== Ellipses ===
''See also: [[Zsh]] and {{ic|man zsh}}''
+
  
Common files:
+
In most cases ellipses ({{ic|...}}) are not part of the actual file content or code output, and instead represent omitted or optional text that is not relevant for the discussed subject.
  
;{{ic|/etc/zprofile}} : System-wide settings; sourced only by a login shell
+
For example {{ic|1=HOOKS="... encrypt ... filesystems ..."}} or:
  
;{{ic|~/.zshrc}} : Personal shell settings; sourced only by an interactive shell
+
{{hc|/etc/X11/xorg.conf.d/50-synaptics.conf|
 +
Section "InputClass"
 +
    ...
 +
    Option      "CircularScrolling"          "on"
 +
    Option      "CircScrollTrigger"          "0"
 +
    ...
 +
EndSection
 +
}}
  
== See also ==
+
Be aware though that, in a few instances, ellipses may be a meaningful part of the code syntax: attentive users will be able to easily recognize these cases by the context.
* [[Help:Style]]
+

Latest revision as of 13:32, 10 August 2016

Related articles

Because the vast majority of the ArchWiki contains indications that may need clarification for users new to GNU/Linux, this rundown of basic procedures was written both to avoid confusion in the assimilation of the articles and to deter repetition in the content itself.

Regular user or root

Some lines are written like so:

# mkinitcpio -p linux

Others have a different prefix:

$ makepkg -s

The numeral or hash sign (#) indicates that the line is to be entered as root, whereas the dollar sign ($) shows that the line is to be entered as a regular user.

Note: The commands prefixed with # are intended to be executed from a root shell, which can for example be easily accessed with sudo -i. Running sudo command from an unprivileged shell instead of command from a root shell will also work in most cases, with some notable exceptions such as redirection and substitution, which strictly require a root shell. See also sudo.

A notable exception to watch out for:

# This alias makes ls colorize the listing
alias ls='ls --color=auto'

In this example, the context surrounding the numeral sign communicates that this is not to be run as a command; it should be edited into a file instead. So in this case, the numeral sign denotes a comment. A comment can be explanatory text that will not be interpreted by the associated program. Bash scripts denotation for comments happens to coincide with the root PS1.

After further examination, "give away" signs include the uppercase character following the # sign. Usually, Unix commands are not written this way and most of the time they are short abbreviations instead of full-blown English words (e.g., Copy becomes cp).

Regardless, most articles make this easy to discern by notifying the reader:

Append to ~/path/to/file:

# This alias makes ls colorize the listing
alias ls='ls --color=auto

Append, add, create, edit

When prompted to append, add, create, or edit use a text editor to make changes to the specified file(s). For example, using nano the command to edit the file /etc/bash.bashrc is:

# nano /etc/bash.bashrc

One can alternatively use output redirection to create or overwrite a file from a string. The following example creates or overwrites the contents of the file /etc/hostname with the text myhostname.

# echo myhostname > /etc/hostname

Output redirection can also be used to append a string to a file. The following example appends the text [custom-repo] to the file /etc/pacman.conf.

# echo "[custom-repo]" >> /etc/pacman.conf

Source

Some applications, notably command-line shells, use scripts for their configuration: after modifying them, they must be sourced in order for the changes to be applied. In the case of bash, for example, this is done by running (you can also replace source with .):

$ source ~/.bashrc

When the wiki will suggest to modify such a configuration script, it will not explicitly remind you to source the file, and only in some cases it will point you to this section with a reminder link.

Installation of packages

When an article invites to install some packages in the conventional way, it will not indicate the detailed instructions to do so, instead it will simply mention the names of the packages to be installed.

Note: Frequently, the install or installed links are used to point to this article section. However, as of March 2016 bugs handicap the feature:
  • WebKit/Blink-based browsers (Chrome/chromium, Epiphany, Opera, qutebrowser, etc.) will not automatically scroll to the proper destination section (fixed in MediaWiki 1.27);
  • all the other browsers (e.g. Firefox) will scroll, but only if JavaScript is enabled.
Until the bugs are resolved, you will be able to read the name of the destination section in the URL's fragment identifier, and manually follow the respective link from the article's Table of Contents. See Help talk:Style#Links to redirects for more information.

The subsections below give an overview of the generic installation procedures depending on the package type.

Official packages

For packages from the official repositories you will read something like:

Install the foobar package.

This means that you have to run:

# pacman -S foobar

The pacman article contains detailed explanations to deal with package management in Arch Linux proficiently.

Arch User Repository

For packages from the Arch User Repository (AUR) you will read something like:

Install the foobarAUR package.

This means that in general you have to follow the foobarAUR link, download the PKGBUILD archive, extract it, verify the content and finally run, in the same folder:

$ makepkg -sri

Note the base-devel group of packages is required to install packages from the AUR.

The Arch User Repository article contains all the detailed explanations and best practices to deal with AUR packages.

Control of systemd units

When an article invites to start, enable, stop or restart some systemd units (e.g. a service), it will not indicate the detailed instructions to do so, but instead you will read something like:

Start example.service.

This means that you have to run:

# systemctl start example.service

The start link will lead you to the systemd article, which contains all the detailed explanations to deal with systemd units in Arch Linux proficiently.

Note: As of March 2016, the start, enable, stop, restart... links are handicapped by the following MediaWiki bugs:
  • WebKit/Blink-based browsers (Chrome/chromium, Epiphany, Opera, qutebrowser, etc.) will not automatically scroll to the proper destination section (fixed in MediaWiki 1.27);
  • all the other browsers (e.g. Firefox) will scroll, but only if JavaScript is enabled.
Until the bugs are resolved, you will be able to read the name of the destination section in the URL's fragment identifier, and manually follow the respective link from the article's Table of Contents. See Help talk:Style#Links to redirects for more information.

System-wide versus user-specific configuration

It is important to remember that there are two different kinds of configurations on a GNU/Linux system. System-wide configuration affects all users. Since system-wide settings are generally located in the /etc directory, root privileges are required in order to alter them. For example, to apply a Bash setting that affects all users, /etc/bash.bashrc should be modified.

User-specific configuration affects only a single user. Dotfiles are used for user-specific configuration. For example, the file ~/.bashrc is the user-specific configuration file. The idea is that each user can define their own settings, such as aliases, functions and other interactive features like the prompt, without affecting other users' preferences.

Note: ~/ and $HOME are shortcuts for the user's home directory, usually /home/username/.

Common shell files

Bash and other Bourne-compatible shells, such as Zsh, also source files depending on whether the shell is a login shell or an interactive shell. See Bash#Configuration files and Zsh#Startup/Shutdown files for details.

Pseudo-variables in code examples

Some code blocks may contain so-called pseudo-variables, which, as the name says, are not actual variables used in the code. Instead they are generic placeholders and have to be manually replaced with system-specific configuration items before the code may be run or parsed. Common shells such as bash and zsh provide tab-completion to auto-complete parameters for common commands such as systemctl.

In the articles that comply with Help:Style/Formatting and punctuation, pseudo-variables are formatted in italics. For example:

  • Enable the dhcpcd@interface_name.service for the network interface identified from the output of the ip link command.

In this case interface_name is used as a pseudo-variable placeholder in a systemd template unit. All systemd template units, identifiable by the @ sign, require a system-specific configuration item as argument. See Systemd#Using units.

  • The command dd if=data_source of=/dev/sd"X" bs=sector_size count=sector_number seek=partitions_start_sector can be run as root to wipe a partition with the specific parameters.

In this case the pseudo-variables are used to describe the parameters that must be substituted for them. Details on how to gather them are elaborated on in the section Securely wipe disk#Calculate blocks to wipe manually, which features the command.

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

Reason: Mention other examples, ideally from other device categories (e.g. storage), with links to background articles. The examples are meant to avoid duplicating existing explanations in other articles. (Discuss in Help talk:Reading#)

In case of file examples, pasting pseudo-variables in real configuration files might break the programs that use them.

Ellipses

In most cases ellipses (...) are not part of the actual file content or code output, and instead represent omitted or optional text that is not relevant for the discussed subject.

For example HOOKS="... encrypt ... filesystems ..." or:

/etc/X11/xorg.conf.d/50-synaptics.conf
Section "InputClass"
    ...
    Option      "CircularScrolling"          "on"
    Option      "CircScrollTrigger"          "0"
    ...
EndSection

Be aware though that, in a few instances, ellipses may be a meaningful part of the code syntax: attentive users will be able to easily recognize these cases by the context.