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.
- sd_journal_process() and
- sd_journal_wait() return one of
- SD_JOURNAL_NOP,
- SD_JOURNAL_APPEND or
- SD_JOURNAL_INVALIDATE on success or a
- negative errno-style error code. If
- SD_JOURNAL_NOP is returned, the journal did
- not change since the last invocation. If
- SD_JOURNAL_APPEND is returned, new entries
- have been appended to the end of the journal. If
- SD_JOURNAL_INVALIDATE, 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 SD_JOURNAL_APPEND, it is
- sufficient to simply continue reading at the previous end of the
- journal.
+ sd_journal_process() and sd_journal_wait() return a negative
+ errno-style error code, or one of SD_JOURNAL_NOP, SD_JOURNAL_APPEND or
+ SD_JOURNAL_INVALIDATE on success:
+
+
+ If SD_JOURNAL_NOP is returned, the journal did not change since the last
+ invocation.
+
+ If SD_JOURNAL_APPEND 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.
+
+ If SD_JOURNAL_INVALIDATE, 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 SD_JOURNAL_INVALIDATE 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 SD_JOURNAL_INVALIDATE the same way as SD_JOURNAL_APPEND, thus
+ ignoring any changes to the log view earlier than the old end of the log stream.
+