diff --git a/gnome/platform/tracker3-miners.xml b/gnome/platform/tracker3-miners.xml
index b7aca50f76..85d4f851bc 100644
--- a/gnome/platform/tracker3-miners.xml
+++ b/gnome/platform/tracker3-miners.xml
@@ -168,9 +168,13 @@ ninja</userinput></screen>
 
     <para>
       <parameter>-Dman=false</parameter>: This switch prevents the build process
-      from generating man pages. Omit this switch if you have
+      from generating man pages.  Building man pages will break the build
+      with a recent release of <application>Asciidoc</application>.
+      <!-- Restore the following when upgrading to tracker-miners-3.3.x
+           (https://gitlab.gnome.org/GNOME/tracker-miners/-/commit/cb87aa8):
+      Omit this switch if you have
       <xref linkend="asciidoc" role="nodep"/> installed and wish to generate and
-      install the man pages.
+      install the man pages. -->
     </para>
 
     <para revision="sysv">
diff --git a/gnome/platform/tracker3.xml b/gnome/platform/tracker3.xml
index 7a22f642e6..b9313ba351 100644
--- a/gnome/platform/tracker3.xml
+++ b/gnome/platform/tracker3.xml
@@ -171,9 +171,13 @@ ninja</userinput></screen>
 
     <para>
       <parameter>-Dman=false</parameter>: This switch prevents the build
-      process from generating man pages. Omit this switch if you have
+      process from generating man pages.  Building man pages will break the
+	  build with a recent release of <application>Asciidoc</application>.
+      <!-- Restore the following when upgrading to tracker-3.3.x
+           (https://gitlab.gnome.org/GNOME/tracker/-/issues/347)
+      Omit this switch if you have
       <xref linkend="asciidoc" role="nodep"/> installed and wish to generate
-      and install the man pages.
+      and install the man pages. -->
     </para>
 
     <para revision="sysv">