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).

diff --git a/man/halt.xml b/man/halt.xml
deleted file mode 100644 (file)
index c13ee5c..0000000
--- a/man/halt.xml
+++ /dev/null
@@ -1,160 +0,0 @@
-<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-
-<refentry id="halt"
-    xmlns:xi="http://www.w3.org/2001/XInclude">
-
-  <refentryinfo>
-    <title>halt</title>
-    <productname>systemd</productname>
-  </refentryinfo>
-
-  <refmeta>
-    <refentrytitle>halt</refentrytitle>
-    <manvolnum>8</manvolnum>
-  </refmeta>
-
-  <refnamediv>
-    <refname>halt</refname>
-    <refname>poweroff</refname>
-    <refname>reboot</refname>
-    <refpurpose>Halt, power-off or reboot the machine</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>halt</command>
-      <arg choice="opt" rep="repeat">OPTIONS</arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>poweroff</command>
-      <arg choice="opt" rep="repeat">OPTIONS</arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>reboot</command>
-      <arg choice="opt" rep="repeat">OPTIONS</arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-
-  <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>
-
-  </refsect1>
-
-  <refsect1>
-    <title>Options</title>
-
-    <para>The following options are understood:</para>
-
-    <variablelist>
-      <varlistentry>
-        <term><option>--help</option></term>
-
-        <xi:include href="standard-options.xml" xpointer="help-text" />
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>--halt</option></term>
-
-        <listitem><para>Halt the machine, regardless of which one of
-        the three commands is invoked.</para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>-p</option></term>
-        <term><option>--poweroff</option></term>
-
-        <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>
-
-      <varlistentry>
-        <term><option>--reboot</option></term>
-
-        <listitem><para>Reboot the machine, regardless of which one of
-        the three commands is invoked.</para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>-f</option></term>
-        <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>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <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>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>-d</option></term>
-        <term><option>--no-wtmp</option></term>
-
-        <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>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>--no-wall</option></term>
-
-        <listitem><para>Do not send wall message before halt,
-        power-off, reboot.</para></listitem>
-      </varlistentry>
-    </variablelist>
-  </refsect1>
-
-  <refsect1>
-    <title>Exit status</title>
-
-    <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
-    functionality with some additional features.</para>
-
-    <para>Note that on many SysV systems <command>halt</command> used to be synonymous to
-    <command>poweroff</command>, i.e. both commands would equally result in powering the machine off. systemd
-    is more accurate here, and <command>halt</command> results in halting the machine only (leaving power
-    on), and <command>poweroff</command> is required to actually power it off.</para>
-  </refsect1>
-
-  <refsect1>
-    <title>See Also</title>
-    <para>
-      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    </para>
-  </refsect1>
-
-</refentry>

diff --git a/man/poweroff.xml b/man/poweroff.xml
new file mode 100644 (file)
index 0000000..2841dc7
--- /dev/null
+++ b/man/poweroff.xml
@@ -0,0 +1,158 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="poweroff"
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>poweroff</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>poweroff</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>poweroff</refname>
+    <refname>reboot</refname>
+    <refname>halt</refname>
+    <refpurpose>Power off, reboot, or halt the machine</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>poweroff</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>reboot</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>halt</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <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>
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>The following options are understood:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>--help</option></term>
+
+        <xi:include href="standard-options.xml" xpointer="help-text" />
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--halt</option></term>
+
+        <listitem><para>Halt the machine, regardless of which one of
+        the three commands is invoked.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-p</option></term>
+        <term><option>--poweroff</option></term>
+
+        <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>
+
+      <varlistentry>
+        <term><option>--reboot</option></term>
+
+        <listitem><para>Reboot the machine, regardless of which one of
+        the three commands is invoked.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-f</option></term>
+        <term><option>--force</option></term>
+
+        <listitem>
+          <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>
+
+      <varlistentry>
+        <term><option>-w</option></term>
+        <term><option>--wtmp-only</option></term>
+
+        <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>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-n</option></term>
+        <term><option>--no-sync</option></term>
+
+        <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 power-off, reboot, or halt.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Exit status</title>
+
+    <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>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
+    <command>poweroff</command>, i.e. both commands would equally result in powering the machine off. systemd
+    is more accurate here, and <command>halt</command> results in halting the machine only (leaving power
+    on), and <command>poweroff</command> is required to actually power it off.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>

diff --git a/man/rules/meson.build b/man/rules/meson.build
index ac4196e548e48f12f139a7e5caf613284c231d49..4c79c77e67219dcc0ef546635586b996248ee58f 100644 (file)
--- 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-halt.service.xml
deleted file mode 100644 (file)
index 0378418..0000000
--- a/man/systemd-halt.service.xml
+++ /dev/null
@@ -1,92 +0,0 @@
-<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-
-<refentry id="systemd-halt.service">
-
-  <refentryinfo>
-    <title>systemd-halt.service</title>
-    <productname>systemd</productname>
-  </refentryinfo>
-
-  <refmeta>
-    <refentrytitle>systemd-halt.service</refentrytitle>
-    <manvolnum>8</manvolnum>
-  </refmeta>
-
-  <refnamediv>
-    <refname>systemd-halt.service</refname>
-    <refname>systemd-poweroff.service</refname>
-    <refname>systemd-reboot.service</refname>
-    <refname>systemd-kexec.service</refname>
-    <refname>systemd-shutdown</refname>
-    <refpurpose>System shutdown logic</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <para><filename>systemd-halt.service</filename></para>
-    <para><filename>systemd-poweroff.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>
-    <para><filename>/usr/lib/systemd/system-shutdown/</filename></para>
-  </refsynopsisdiv>
-
-  <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>,
-    <filename>systemd-reboot.service</filename> by
-    <filename>reboot.target</filename> and
-    <filename>systemd-kexec.service</filename> by
-    <filename>kexec.target</filename> to execute the respective
-    actions.</para>
-
-    <para>When these services are run, they ensure that PID 1 is
-    replaced by the
-    <filename>/usr/lib/systemd/systemd-shutdown</filename> tool which
-    is then responsible for the actual shutdown. Before shutting down,
-    this binary will try to unmount all remaining file systems,
-    disable all remaining swap devices, detach all remaining storage
-    devices and kill all remaining processes.</para>
-
-    <para>It is necessary to have this code in a separate binary
-    because otherwise rebooting after an upgrade might be broken — the
-    running PID 1 could still depend on libraries which are not
-    available any more, thus keeping the file system busy, which then
-    cannot be re-mounted read-only.</para>
-
-    <para>Immediately before executing the actual system
-    halt/poweroff/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
-    <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
-    executed directly. Instead, trigger system shutdown with a command such as <literal>systemctl
-    halt</literal>.</para>
-  </refsect1>
-
-  <refsect1>
-    <title>See Also</title>
-    <para>
-      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-    </para>
-  </refsect1>
-
-</refentry>

diff --git a/man/systemd-poweroff.service.xml b/man/systemd-poweroff.service.xml
new file mode 100644 (file)
index 0000000..9adfcc5
--- /dev/null
+++ b/man/systemd-poweroff.service.xml
@@ -0,0 +1,92 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd-poweroff.service">
+
+  <refentryinfo>
+    <title>systemd-poweroff.service</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-poweroff.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-poweroff.service</refname>
+    <refname>systemd-halt.service</refname>
+    <refname>systemd-reboot.service</refname>
+    <refname>systemd-kexec.service</refname>
+    <refname>systemd-shutdown</refname>
+    <refpurpose>System shutdown logic</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <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>
+    <para><filename>/usr/lib/systemd/system-shutdown/</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <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
+    <filename>kexec.target</filename> to execute the respective
+    actions.</para>
+
+    <para>When these services are run, they ensure that PID 1 is
+    replaced by the
+    <filename>/usr/lib/systemd/systemd-shutdown</filename> tool which
+    is then responsible for the actual shutdown. Before shutting down,
+    this binary will try to unmount all remaining file systems,
+    disable all remaining swap devices, detach all remaining storage
+    devices and kill all remaining processes.</para>
+
+    <para>It is necessary to have this code in a separate binary
+    because otherwise rebooting after an upgrade might be broken — the
+    running PID 1 could still depend on libraries which are not
+    available any more, thus keeping the file system busy, which then
+    cannot be re-mounted read-only.</para>
+
+    <para>Immediately before executing the actual system
+    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>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-poweroff.service</filename> (and the related units) should never be
+    executed directly. Instead, trigger system shutdown with a command such as <literal>systemctl
+    poweroff</literal>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>