From 269d17f9559a08b9801bd25d01840ce6ee42fc7f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 6 Dec 2022 11:27:31 +0100 Subject: [PATCH] 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). --- man/{halt.xml => poweroff.xml} | 52 +++++++++---------- man/rules/meson.build | 16 +++--- ...rvice.xml => systemd-poweroff.service.xml} | 30 +++++------ 3 files changed, 48 insertions(+), 50 deletions(-) rename man/{halt.xml => poweroff.xml} (72%) rename man/{systemd-halt.service.xml => systemd-poweroff.service.xml} (80%) diff --git a/man/halt.xml b/man/poweroff.xml similarity index 72% rename from man/halt.xml rename to man/poweroff.xml index c13ee5c1448..2841dc77690 100644 --- a/man/halt.xml +++ b/man/poweroff.xml @@ -3,37 +3,37 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - halt + poweroff systemd - halt + poweroff 8 - halt poweroff reboot - Halt, power-off or reboot the machine + halt + Power off, reboot, or halt the machine - halt + poweroff OPTIONS - poweroff + reboot OPTIONS - reboot + halt OPTIONS @@ -41,8 +41,8 @@ Description - halt, poweroff, reboot may be used to - halt, power-off, or reboot the machine. All three commands take the same options. + poweroff, reboot, and halt may be used to + power off, reboot, or halt the machine. All three commands take the same options. @@ -69,7 +69,7 @@ - Power-off the machine, when either halt + Power off the machine, when either halt or poweroff is invoked. This option is ignored when reboot is invoked. @@ -86,10 +86,11 @@ - 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 reboot -f is mostly equivalent to systemctl reboot -ff, - instead of systemctl reboot -f. + 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 reboot -f is mostly equivalent to + systemctl reboot -ff, instead of systemctl reboot -f. + @@ -97,31 +98,29 @@ - Only write wtmp shutdown entry, do not - actually halt, power-off, reboot. + Only write wtmp shutdown entry, do not actually power off, reboot, or halt. + - Do not write wtmp shutdown - entry. + Do not write wtmp shutdown entry. - Don't sync hard disks/storage media before - halt, power-off, reboot. + Don't sync hard disks/storage media before power-off, reboot, or halt. + - Do not send wall message before halt, - power-off, reboot. + Do not send wall message before power-off, reboot, or halt. @@ -129,16 +128,15 @@ Exit status - On success, 0 is returned, a non-zero failure code - otherwise. + On success, 0 is returned, a non-zero failure code otherwise. Notes These commands are implemented in a way that preserves basic compatibility with the original SysV - commands. systemctl1 - verbs halt, poweroff, reboot provide the same + commands. systemctl1 + verbs poweroff, reboot, halt provide the same functionality with some additional features. Note that on many SysV systems halt used to be synonymous to diff --git a/man/rules/meson.build b/man/rules/meson.build index ac4196e548e..4c79c77e672 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 similarity index 80% rename from man/systemd-halt.service.xml rename to man/systemd-poweroff.service.xml index 0378418192e..9adfcc5af06 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"> - + - systemd-halt.service + systemd-poweroff.service systemd - systemd-halt.service + systemd-poweroff.service 8 - systemd-halt.service systemd-poweroff.service + systemd-halt.service systemd-reboot.service systemd-kexec.service systemd-shutdown @@ -25,8 +25,8 @@ - systemd-halt.service systemd-poweroff.service + systemd-halt.service systemd-reboot.service systemd-kexec.service /usr/lib/systemd/systemd-shutdown @@ -36,11 +36,11 @@ Description - systemd-halt.service is a system - service that is pulled in by halt.target and - is responsible for the actual system halt. Similarly, - systemd-poweroff.service is pulled in by - poweroff.target, + systemd-poweroff.service is a system + service that is pulled in by poweroff.target and + is responsible for the actual system power-off operation. Similarly, + systemd-halt.service is pulled in by + halt.target, systemd-reboot.service by reboot.target and systemd-kexec.service by @@ -62,19 +62,19 @@ cannot be re-mounted read-only. Immediately before executing the actual system - halt/poweroff/reboot/kexec systemd-shutdown + power-off/halt/reboot/kexec systemd-shutdown will run all executables in /usr/lib/systemd/system-shutdown/ and pass - one arguments to them: either halt, - poweroff, reboot or + one arguments to them: either poweroff, + halt, reboot, or kexec, 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. - Note that systemd-halt.service (and the related units) should never be + Note that systemd-poweroff.service (and the related units) should never be executed directly. Instead, trigger system shutdown with a command such as systemctl - halt. + poweroff. -- 2.47.3