analyze: add 'timestamp' verb

We had 'calendar' and 'timespan', but the third one was missing.
Also consistently order the verbs as calendar/timestamp/timespan in help.

The output from 'timespan' is highlighted more.

Fixes https://bugzilla.redhat.com/show_bug.cgi?id=1711065.

2 files changed, 48 insertions, 6 deletions

diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml
index abc05e9303..cc29e26240 100644
--- a/man/systemd-analyze.xml
+++ b/man/systemd-analyze.xml
@@ -93,7 +93,13 @@
       <command>systemd-analyze</command>
       <arg choice="opt" rep="repeat">OPTIONS</arg>
       <arg choice="plain">calendar</arg>
-      <arg choice="plain" rep="repeat"><replaceable>SPECS</replaceable></arg>
+      <arg choice="plain" rep="repeat"><replaceable>SPEC</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>systemd-analyze</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">timestamp</arg>
+      <arg choice="plain" rep="repeat"><replaceable>TIMESTAMP</replaceable></arg>
     </cmdsynopsis>
     <cmdsynopsis>
       <command>systemd-analyze</command>
@@ -360,7 +366,8 @@ $ eog targets.svg</programlisting>
       <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. By
       default, only the next time the calendar expression will elapse is shown; use
       <option>--iterations=</option> to show the specified number of next times the expression
-      elapses.</para>
+      elapses. Each time the expression elapses forms a timestamp, see the <command>timestamp</command>
+      verb below.</para>
 
       <example>
         <title>Show leap days in the near future</title>
@@ -383,12 +390,43 @@ Normalized form: *-02-29 00:00:00
     </refsect2>
 
     <refsect2>
+      <title><command>systemd-analyze timestamp <replaceable>TIMESTAMP</replaceable>...</command></title>
+
+      <para>This command parses a timestamp (i.e. a single point in time) and outputs the normalized form and
+      the difference between this timestamp and now. The timestamp should adhere to the syntax documented in
+      <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      section "PARSING TIMESTAMPS".</para>
+
+      <example>
+        <title>Show parsing of timestamps</title>
+
+        <programlisting>$ systemd-analyze timestamp yesterday now tomorrow
+  Original form: yesterday
+Normalized form: Thu 2019-05-16 00:00:00 CEST
+       (in UTC): Wed 2019-05-15 22:00:00 UTC
+       From now: 1 day 9h ago
+
+  Original form: now
+Normalized form: Fri 2019-05-17 09:34:14 CEST
+       (in UTC): Fri 2019-05-17 07:34:14 UTC
+       From now: 32us ago
+
+  Original form: tomorrow
+Normalized form: Sat 2019-05-18 00:00:00 CEST
+       (in UTC): Fri 2019-05-17 22:00:00 UTC
+       From now: 14h left
+</programlisting>
+      </example>
+    </refsect2>
+
+    <refsect2>
       <title><command>systemd-analyze timespan <replaceable>EXPRESSION</replaceable>...</command></title>
 
-      <para>This command parses a time span and outputs the normalized form and the equivalent value in
-      microseconds. The time span should adhere to the same syntax documented in
-      <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
-      Values without associated magnitudes are parsed as seconds.</para>
+      <para>This command parses a time span (i.e. a difference between two timestamps) and outputs the
+      normalized form and the equivalent value in microseconds. The time span should adhere to the syntax
+      documented in
+      <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      section "PARSING TIME SPANS". Values without units are parsed as seconds.</para>
 
       <example>
         <title>Show parsing of timespans</title>
diff --git a/man/systemd.time.xml b/man/systemd.time.xml
index 4a6b808c02..c7d5f24b3c 100644
--- a/man/systemd.time.xml
+++ b/man/systemd.time.xml
@@ -173,6 +173,10 @@ tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00
     <programlisting>2 months 5 days ago</programlisting>
 
     <para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para>
+
+    <para>Use the <command>timestamp</command> command of
+    <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
+    validate and normalize timestamps for testing purposes.</para>
   </refsect1>
 
   <refsect1>