man/shutdown: document how to switch to single-user mode

Before Debian switched to systemd, `shutdown now` would reset the system into
single user mode, doing roughly the equivalent of `telinit 1`.

Now, systemd's `shutdown` command does not behave that way; it defaults to
`poweroff` which might be confusing for users (like me) used to the previous
method.

Because I don't use the command often, I keep being stumped by this behavior,
and every time I look at the `shutdown(1)` manpage, I don't understand why I
can't find what I am looking for. This patch should make sure that people like
me find their way back to some sort of reason.

Maybe the *proper* way to fix this would be to restore the more classic
behavior, but I'm definitely not going to climb that hill. Besides, I clearly
remember the time I found out about the `shutdown` command and was *really*
confused when it brought me back to a command-line prompt. That was really
counter-intuitive and I find that change to actually be a good thing. So I'm
not proposing to change this behavior, merely document it better.

I originally added this to the `-P` option but it was suggested adding a new
`COMPATIBILITY` section instead, where other such issues could be added.

The `COMPATIBILITY` section is not actually officially documented. `man(1)`
talks about a `CONFORMING TO` section, but `shutdown(1)` is not
POSIX (`shutdown(2)` is, of course), so there's no actual standard on how this
should work.

The other option I considered was to add a `BUGS` section, but that seemed to
inflammatory, and definitely counter-productive.

diff --git a/man/shutdown.xml b/man/shutdown.xml
index 97f33e802a9898725e3ed6f9cafd23a803f67661..24a934f45ec318f806bd9f9b37c0b8311db2eb2d 100644 (file)
--- a/man/shutdown.xml
+++ b/man/shutdown.xml
@@ -135,6 +135,14 @@
     otherwise.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Compatibility</title>
+
+    <para>The <command> shutdown</command> command in previous init systems (including sysvinit) defaulted to
+    single-user mode instead of powering off the machine. To change into single-user mode, use
+    <command>systemctl rescue</command> instead.</para>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
     <para>