man: add note about systemctl stop return value

Fixes #13104.

(I know a lot more could be added to that  man page. This patch only addresses that
once specific complaint.)

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 6f93e1cd2cd260b75e57165f8b0a36869a11fdbd..0f06a88f4243b412a3bea9f409727ef87fc86e71 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -816,8 +816,14 @@ Sun 2017-02-26 20:57:49 EST  2h 3min left  Sun 2017-02-26 11:56:36 EST  6h ago
           <term><command>stop <replaceable>PATTERN</replaceable>…</command></term>
 
           <listitem>
-            <para>Stop (deactivate) one or more units specified on the
-            command line.</para>
+            <para>Stop (deactivate) one or more units specified on the command line.</para>
+
+            <para>This command will fail if the unit does exist or if stopping of the unit is prohibited (see
+            <varname>RefuseManualStop=</varname> in
+            <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+            It will <emphasis>not</emphasis> fail if any of the commands configured to stop the unit
+            (<varname>ExecStop=</varname>, etc.) fail, because the manager will still forcibly terminate the
+            unit.</para>
           </listitem>
         </varlistentry>
         <varlistentry>