diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2022-12-06 11:27:31 +0100 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2022-12-07 10:26:31 +0100 |
commit | 269d17f9559a08b9801bd25d01840ce6ee42fc7f (patch) | |
tree | 537ea1056386945ab7a35fadc840c876981b3872 /man | |
parent | 9551c46a3db9090e6d8a8ee44feb53e10efd6a58 (diff) | |
download | systemd-269d17f9559a08b9801bd25d01840ce6ee42fc7f.tar.gz |
man: deemphasize "halt"
Systemd documents "halt" as the primary shutdown mechanism, redirecting
"reboot" and "shutdown" to the halt(8), but halt is a really strange and
obsolete concept. Who would want to really keep their machine running after
shutdown? I expect that halting is almost unused. Let's at least make it less
prominent in the docs.
While at it, use "power off" for a verb and "power-off" for noun (but "poweroff"
of the actual command name).
Diffstat (limited to 'man')
-rw-r--r-- | man/poweroff.xml (renamed from man/halt.xml) | 52 | ||||
-rw-r--r-- | man/rules/meson.build | 16 | ||||
-rw-r--r-- | man/systemd-poweroff.service.xml (renamed from man/systemd-halt.service.xml) | 30 |
3 files changed, 48 insertions, 50 deletions
diff --git a/man/halt.xml b/man/poweroff.xml index c13ee5c144..2841dc7769 100644 --- a/man/halt.xml +++ b/man/poweroff.xml @@ -3,37 +3,37 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> -<refentry id="halt" +<refentry id="poweroff" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> - <title>halt</title> + <title>poweroff</title> <productname>systemd</productname> </refentryinfo> <refmeta> - <refentrytitle>halt</refentrytitle> + <refentrytitle>poweroff</refentrytitle> <manvolnum>8</manvolnum> </refmeta> <refnamediv> - <refname>halt</refname> <refname>poweroff</refname> <refname>reboot</refname> - <refpurpose>Halt, power-off or reboot the machine</refpurpose> + <refname>halt</refname> + <refpurpose>Power off, reboot, or halt the machine</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>halt</command> + <command>poweroff</command> <arg choice="opt" rep="repeat">OPTIONS</arg> </cmdsynopsis> <cmdsynopsis> - <command>poweroff</command> + <command>reboot</command> <arg choice="opt" rep="repeat">OPTIONS</arg> </cmdsynopsis> <cmdsynopsis> - <command>reboot</command> + <command>halt</command> <arg choice="opt" rep="repeat">OPTIONS</arg> </cmdsynopsis> </refsynopsisdiv> @@ -41,8 +41,8 @@ <refsect1> <title>Description</title> - <para><command>halt</command>, <command>poweroff</command>, <command>reboot</command> may be used to - halt, power-off, or reboot the machine. All three commands take the same options.</para> + <para><command>poweroff</command>, <command>reboot</command>, and <command>halt</command> may be used to + power off, reboot, or halt the machine. All three commands take the same options.</para> </refsect1> @@ -69,7 +69,7 @@ <term><option>-p</option></term> <term><option>--poweroff</option></term> - <listitem><para>Power-off the machine, when either <command>halt</command> + <listitem><para>Power off the machine, when either <command>halt</command> or <command>poweroff</command> is invoked. This option is ignored when <command>reboot</command> is invoked.</para></listitem> </varlistentry> @@ -86,10 +86,11 @@ <term><option>--force</option></term> <listitem> - <para>Force immediate halt, power-off, reboot. If specified, the command does not contact the init - system. In most cases, filesystems are not properly unmounted before shutdown. For example, the - command <command>reboot -f</command> is mostly equivalent to <command>systemctl reboot -ff</command>, - instead of <command>systemctl reboot -f</command>.</para> + <para>Force immediate power-off, halt, or reboot. If specified, the command does not contact the + init system. In most cases, filesystems are not properly unmounted before shutdown. For example, + the command <command>reboot -f</command> is mostly equivalent to + <command>systemctl reboot -ff</command>, instead of <command>systemctl reboot -f</command>. + </para> </listitem> </varlistentry> @@ -97,31 +98,29 @@ <term><option>-w</option></term> <term><option>--wtmp-only</option></term> - <listitem><para>Only write wtmp shutdown entry, do not - actually halt, power-off, reboot.</para></listitem> + <listitem><para>Only write wtmp shutdown entry, do not actually power off, reboot, or halt. + </para></listitem> </varlistentry> <varlistentry> <term><option>-d</option></term> <term><option>--no-wtmp</option></term> - <listitem><para>Do not write wtmp shutdown - entry.</para></listitem> + <listitem><para>Do not write wtmp shutdown entry.</para></listitem> </varlistentry> <varlistentry> <term><option>-n</option></term> <term><option>--no-sync</option></term> - <listitem><para>Don't sync hard disks/storage media before - halt, power-off, reboot.</para></listitem> + <listitem><para>Don't sync hard disks/storage media before power-off, reboot, or halt. + </para></listitem> </varlistentry> <varlistentry> <term><option>--no-wall</option></term> - <listitem><para>Do not send wall message before halt, - power-off, reboot.</para></listitem> + <listitem><para>Do not send wall message before power-off, reboot, or halt.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -129,16 +128,15 @@ <refsect1> <title>Exit status</title> - <para>On success, 0 is returned, a non-zero failure code - otherwise.</para> + <para>On success, 0 is returned, a non-zero failure code otherwise.</para> </refsect1> <refsect1> <title>Notes</title> <para>These commands are implemented in a way that preserves basic compatibility with the original SysV - commands. <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - verbs <command>halt</command>, <command>poweroff</command>, <command>reboot</command> provide the same + commands. <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + verbs <command>poweroff</command>, <command>reboot</command>, <command>halt</command> provide the same functionality with some additional features.</para> <para>Note that on many SysV systems <command>halt</command> used to be synonymous to diff --git a/man/rules/meson.build b/man/rules/meson.build index ac4196e548..4c79c77e67 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -18,7 +18,6 @@ manpages = [ 'ENABLE_RESOLVE'], ['environment.d', '5', [], 'ENABLE_ENVIRONMENT_D'], ['file-hierarchy', '7', [], ''], - ['halt', '8', ['poweroff', 'reboot'], ''], ['homectl', '1', [], 'ENABLE_HOMED'], ['homed.conf', '5', ['homed.conf.d'], 'ENABLE_HOMED'], ['hostname', '5', [], ''], @@ -67,6 +66,7 @@ manpages = [ ['pam_systemd', '8', [], 'HAVE_PAM'], ['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'], ['portablectl', '1', [], 'ENABLE_PORTABLED'], + ['poweroff', '8', ['halt', 'reboot'], ''], ['pstore.conf', '5', ['pstore.conf.d'], 'ENABLE_PSTORE'], ['repart.d', '5', [], 'ENABLE_REPART'], ['resolvectl', '1', ['resolvconf'], 'ENABLE_RESOLVE'], @@ -897,13 +897,6 @@ manpages = [ ['systemd-fstab-generator', '8', [], ''], ['systemd-getty-generator', '8', [], ''], ['systemd-gpt-auto-generator', '8', [], 'HAVE_BLKID'], - ['systemd-halt.service', - '8', - ['systemd-kexec.service', - 'systemd-poweroff.service', - 'systemd-reboot.service', - 'systemd-shutdown'], - ''], ['systemd-hibernate-resume-generator', '8', [], 'ENABLE_HIBERNATE'], ['systemd-hibernate-resume@.service', '8', @@ -978,6 +971,13 @@ manpages = [ 'systemd-pcrphase-sysinit.service'], 'HAVE_GNU_EFI'], ['systemd-portabled.service', '8', ['systemd-portabled'], 'ENABLE_PORTABLED'], + ['systemd-poweroff.service', + '8', + ['systemd-halt.service', + 'systemd-kexec.service', + 'systemd-reboot.service', + 'systemd-shutdown'], + ''], ['systemd-pstore.service', '8', ['systemd-pstore'], 'ENABLE_PSTORE'], ['systemd-quotacheck.service', '8', diff --git a/man/systemd-halt.service.xml b/man/systemd-poweroff.service.xml index 0378418192..9adfcc5af0 100644 --- a/man/systemd-halt.service.xml +++ b/man/systemd-poweroff.service.xml @@ -3,21 +3,21 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> -<refentry id="systemd-halt.service"> +<refentry id="systemd-poweroff.service"> <refentryinfo> - <title>systemd-halt.service</title> + <title>systemd-poweroff.service</title> <productname>systemd</productname> </refentryinfo> <refmeta> - <refentrytitle>systemd-halt.service</refentrytitle> + <refentrytitle>systemd-poweroff.service</refentrytitle> <manvolnum>8</manvolnum> </refmeta> <refnamediv> - <refname>systemd-halt.service</refname> <refname>systemd-poweroff.service</refname> + <refname>systemd-halt.service</refname> <refname>systemd-reboot.service</refname> <refname>systemd-kexec.service</refname> <refname>systemd-shutdown</refname> @@ -25,8 +25,8 @@ </refnamediv> <refsynopsisdiv> - <para><filename>systemd-halt.service</filename></para> <para><filename>systemd-poweroff.service</filename></para> + <para><filename>systemd-halt.service</filename></para> <para><filename>systemd-reboot.service</filename></para> <para><filename>systemd-kexec.service</filename></para> <para><filename>/usr/lib/systemd/systemd-shutdown</filename></para> @@ -36,11 +36,11 @@ <refsect1> <title>Description</title> - <para><filename>systemd-halt.service</filename> is a system - service that is pulled in by <filename>halt.target</filename> and - is responsible for the actual system halt. Similarly, - <filename>systemd-poweroff.service</filename> is pulled in by - <filename>poweroff.target</filename>, + <para><filename>systemd-poweroff.service</filename> is a system + service that is pulled in by <filename>poweroff.target</filename> and + is responsible for the actual system power-off operation. Similarly, + <filename>systemd-halt.service</filename> is pulled in by + <filename>halt.target</filename>, <filename>systemd-reboot.service</filename> by <filename>reboot.target</filename> and <filename>systemd-kexec.service</filename> by @@ -62,19 +62,19 @@ cannot be re-mounted read-only.</para> <para>Immediately before executing the actual system - halt/poweroff/reboot/kexec <filename>systemd-shutdown</filename> + power-off/halt/reboot/kexec <filename>systemd-shutdown</filename> will run all executables in <filename>/usr/lib/systemd/system-shutdown/</filename> and pass - one arguments to them: either <literal>halt</literal>, - <literal>poweroff</literal>, <literal>reboot</literal> or + one arguments to them: either <literal>poweroff</literal>, + <literal>halt</literal>, <literal>reboot</literal>, or <literal>kexec</literal>, depending on the chosen action. All executables in this directory are executed in parallel, and execution of the action is not continued before all executables finished.</para> - <para>Note that <filename>systemd-halt.service</filename> (and the related units) should never be + <para>Note that <filename>systemd-poweroff.service</filename> (and the related units) should never be executed directly. Instead, trigger system shutdown with a command such as <literal>systemctl - halt</literal>.</para> + poweroff</literal>.</para> </refsect1> <refsect1> |