man: say more explicitly what to do in the SD_JOURNAL_INVALIDATE event

This rewords the section, explicitly distuingishing the cases of clients
that only want a continious log stream (which can simply treat
SD_JOURNAL_INVALIDATE the same way as SD_JOURNAL_APPEND) and those which
want to represent on screen the full state of the log data on disk.

This is an alternative to a part of PR #9060, but keeps an explanation
of the destinction of handling depending on the type of client.

Fixes: #8963

1 files changed, 21 insertions, 16 deletions

diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml
index ec1ba37f1e..c396c6a79b 100644
--- a/man/sd_journal_get_fd.xml
+++ b/man/sd_journal_get_fd.xml
@@ -199,22 +199,27 @@ else {
     immediately for all journal changes. Returns 0 if there might be a
     latency involved.</para>
 
-    <para><function>sd_journal_process()</function> and
-    <function>sd_journal_wait()</function> return one of
-    <constant>SD_JOURNAL_NOP</constant>,
-    <constant>SD_JOURNAL_APPEND</constant> or
-    <constant>SD_JOURNAL_INVALIDATE</constant> on success or a
-    negative errno-style error code. If
-    <constant>SD_JOURNAL_NOP</constant> is returned, the journal did
-    not change since the last invocation. If
-    <constant>SD_JOURNAL_APPEND</constant> is returned, new entries
-    have been appended to the end of the journal. If
-    <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were
-    added or removed (possibly due to rotation). In the latter event,
-    live-view UIs should probably refresh their entire display, while
-    in the case of <constant>SD_JOURNAL_APPEND</constant>, it is
-    sufficient to simply continue reading at the previous end of the
-    journal.</para>
+    <para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> return a negative
+    errno-style error code, or one of <constant>SD_JOURNAL_NOP</constant>, <constant>SD_JOURNAL_APPEND</constant> or
+    <constant>SD_JOURNAL_INVALIDATE</constant> on success:</para>
+
+    <itemizedlist>
+      <listitem><para>If <constant>SD_JOURNAL_NOP</constant> is returned, the journal did not change since the last
+      invocation.</para></listitem>
+
+      <listitem><para>If <constant>SD_JOURNAL_APPEND</constant> is returned, new entries have been appended to the end
+      of the journal. In this case it is sufficient to simply continue reading at the previous end location of the
+      journal, to read the newly added entries.</para></listitem>
+
+      <listitem><para>If <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were added to or removed from the
+      set of of journal files watched (e.g. due to rotation or vacuuming), and thus entries might have appeared or
+      disappeared at arbitrary places in the log stream, possibly before or after the previous end of the log
+      stream. If <constant>SD_JOURNAL_INVALIDATE</constant> is returned, live-view UIs that want to reflect on screen
+      the precise state of the log data on disk should probably refresh their entire display (relative to the cursor of
+      the log entry on the top of the screen). Programs only interested in a strictly sequencial stream of log data may
+      treat <constant>SD_JOURNAL_INVALIDATE</constant> the same way as <constant>SD_JOURNAL_APPEND</constant>, thus
+      ignoring any changes to the log view earlier than the old end of the log stream.</para></listitem>
+    </itemizedlist>
   </refsect1>
 
   <refsect1>