diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index baef80d..451f0ec 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17796,7 +17796,11 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
     these functions return the name of the preceding transaction log file.
     This is usually the desired behavior for managing transaction log archiving
     behavior, since the preceding file is the last one that currently
-    needs to be archived.
+    needs to be archived. Note that these two functions use the timeline ID at
+    the time to construct the file name. Therefore they give wrong names for
+    transaction log locations on the other timelines. This can happen during
+    runtime on replication standby when a promotion occurs on itself or
+    upstreams.
    </para>
 
    <para>