man: extend on the usec/sec discrepancy

Let's document the discrepancy between the Sec and USec suffixing of
unit files and D-Bus properties at three places: in "systemctl show"
(where it already was briefly mentioned), in the D-Bus interface
description (at one place at least, i.e. the most prominent of
properties that encapsulate time values, there are many more) and in the
general man page explaining time values.

By documenting this at all three places I think we now do as much as we
can do about this highlighting the discrepancy of the naming and the
reasons behind it.

Fixes: #2047

1 files changed, 10 insertions, 0 deletions

diff --git a/man/systemd.time.xml b/man/systemd.time.xml
index 5b7800e78b..79fe9735c4 100644
--- a/man/systemd.time.xml
+++ b/man/systemd.time.xml
@@ -75,6 +75,16 @@
     <para>One can use the <command>timespan</command> command of
     <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     to normalise a textual time span for testing and validation purposes.</para>
+
+    <para>Internally, systemd generally operates with microsecond time granularity, while the default time
+    unit in user-configurable time spans is usually seconds (see above). This disparity becomes visible when
+    comparing the same settings in the (high-level) unit file syntax with the matching (more low-level) D-Bus
+    properties (which are what
+    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+    <command>show</command> command displays). The former typically are suffixed with <literal>…Sec</literal>
+    to indicate the default unit of seconds, the latter are typically suffixed with <literal>…USec</literal>
+    to indicate the underlying low-level time unit, even if they both encapsulate the very same
+    settings.</para>
   </refsect1>
 
   <refsect1>