man: beef up description of systemctl list-units

Fixes https://bugs.freedesktop.org/show_bug.cgi?id=88135.

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 1588ca719da17c9819020f2db8a85b8ffa99eadb..3d641fa18d70a62bb94b2d6d6be7da9490ba1e68 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -692,6 +692,42 @@
             that are shown are additionally filtered by <option>--type=</option> and <option>--state=</option> if those
             options are specified.</para>
 
+            <para>Produces output similar to
+            <programlisting>  UNIT                         LOAD   ACTIVE SUB     DESCRIPTION
+  sys-module-fuse.device       loaded active plugged /sys/module/fuse
+  -.mount                      loaded active mounted Root Mount
+  boot-efi.mount               loaded active mounted /boot/efi
+  systemd-journald.service     loaded active running Journal Service
+  systemd-logind.service       loaded active running Login Service
+● user@1000.service            loaded active running User Manager for UID 1000
+...
+  systemd-tmpfiles-clean.timer loaded active waiting Daily Cleanup of Temporary Directories
+
+LOAD   = Reflects whether the unit definition was properly loaded.
+ACTIVE = The high-level unit activation state, i.e. generalization of SUB.
+SUB    = The low-level unit activation state, values depend on unit type.
+
+123 loaded units listed. Pass --all to see loaded but inactive units, too.
+To show all installed unit files use 'systemctl list-unit-files'.
+            </programlisting>
+            The header and the last unit of a given type are underlined if the
+            terminal supports that. A colored dot is shown next to services which
+            were masked, not found, or otherwise failed.</para>
+
+            <para>The LOAD column shows the load state, one of
+            <constant>loaded</constant>, <constant>not-found</constant>,
+            <constant>stub</constant>, <constant>error</constant>,
+            <constant>merged</constant>, <constant>masked</constant>. The ACTIVE
+            columns shows the general unit state, one of <constant>active</constant>,
+            <constant>reloading</constant>, <constant>inactive</constant>,
+            <constant>failed</constant>, <constant>activating</constant>,
+            <constant>deactivating</constant>. The SUB column shows the
+            unit-type-specific detailed state of the unit, possible values vary by
+            unit type. The list of possible LOAD, ACTIVE, and SUB states is not
+            constant and new systemd releases may both add and remove values.
+            <programlisting>systemctl --state=help</programlisting> command maybe be
+            used to display the current set of possible values.</para>
+
             <para>This is the default command.</para>
           </listitem>
         </varlistentry>