man: extend documentation on systemctl isolate

Lennart has convinced me that it's more helpful to participate than to sit
on the sidelines and complain. So, hello everyone.

I'm starting by giving up the battle to change the systemctl "isolate"
command to "switch-to". Can't win them all. :) I've got a suggested patch
to expand the documentation a bit, hopefully making it more clear to new
systemd users.

Is there an easy way to list all units where AllowIsolate is enabled? That
should be included alongside this, I think.

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 768f3add59561647066ba8d8ed74124dc2fa213a..63598723bbc27875950bb9fd9935825ff6f2fa5b 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -342,9 +342,18 @@
 
                                 <listitem><para>Start the unit
                                 specified on the command line and its
-                                dependencies and stop all others. Note
-                                that this works only on units where
-                                <option>AllowIsolate=</option> is
+                                dependencies and stop all others.</para>
+
+                                <para>This is similar to changing the
+                                runlevel in a traditional init system. The
+                                <command>isolate</command> command will
+                                immediately stop processes that are not
+                                enabled in the new unit, possibly including
+                                the graphical environment or terminal you
+                                are currently using.</para>
+
+                                <para>Note that this works only on units
+                                where <option>AllowIsolate=</option> is
                                 enabled. See
                                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                 for details.</para></listitem>