man: extend documentation for timedatectl's set-ntp command

This extends on the relationship between timedatectl's set-ntp command
and its effect on the systemd-timesyncd.service unit. This also links
that unit back to the timedatectl man page.

Closes #798.

diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml
index ac1af2d136a032b5c56368c65d041fa17ad99ca0..01ed0b814928a37cc64809d5ccd1d7e980fd2e6a 100644 (file)
--- a/man/systemd-timesyncd.service.xml
+++ b/man/systemd-timesyncd.service.xml
@@ -71,6 +71,10 @@
     files, and the per-link dynamic settings received over DHCP. See
     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for more details.</para>
+
+    <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+    <command>set-ntp</command> command may be used to enable and
+    start, or disable and stop this service.</para>
   </refsect1>
 
   <refsect1>

diff --git a/man/timedatectl.xml b/man/timedatectl.xml
index 2d42b41d5e9c1df455fbe80b8cb4604950ee7c88..9a86c4126a932d3b2276121ffbbf7fcb2ccc7a42 100644 (file)
--- a/man/timedatectl.xml
+++ b/man/timedatectl.xml
@@ -166,12 +166,27 @@
         <term><command>set-ntp [BOOL]</command></term>
 
         <listitem><para>Takes a boolean argument. Controls whether
-        network time synchronization is enabled (if available). This
-        enables or disables the
-        <filename>systemd-timesyncd.service</filename> unit. Note that
-        even if this command turns time synchronization off a
-        different system service might still synchronize the clock
-        with the network.</para></listitem>
+        network time synchronization is active and enabled (if
+        available). This enables and starts, or disables and stops the
+        <filename>systemd-timesyncd.service</filename> unit. It does
+        not affect the state of any other, unrelated network time
+        synchronization services that might be installed on the
+        system. This command is hence mostly equivalent to:
+        <command>systemctl enable --now
+        systemd-timesyncd.service</command> and <command>systemctl
+        disable --now systemd-timesyncd.service</command>, but is
+        protected by a different access policy.</para>
+
+        <para>Note that even if time synchronization is turned off
+        with this command another, unrelated system service might
+        still synchronize the clock with the network. Also note that
+        strictly speaking
+        <filename>systemd-timesyncd.service</filename> does more than
+        just network time synchronization as it ensures a monotonic
+        clock on systems without RTC even if no network is
+        available. See
+        <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        for details about this.</para></listitem>
       </varlistentry>
 
     </variablelist>