doc: document problems with using xreflabel in XML docs

Reported-by: Peter Eisentraut
Discussion: https://postgr.es/m/8315c0ca-7758-8823-fcb6-f37f9413e6b6@2ndquadrant.com

Backpatch-through: master

diff --git a/doc/src/sgml/README.links b/doc/src/sgml/README.links
index c83488969620d1e6ead7095ae83c754b429082df..4181e0877b5b5cabb28fa3167ea33b340f936ac4 100644 (file)
--- a/doc/src/sgml/README.links
+++ b/doc/src/sgml/README.links
@@ -47,3 +47,7 @@ Guidelines
   usually have xreflabels.
 
 - For an external link, use , with or without link text.
+
+- xreflabels added to tags prevent the chapter/section for id's from being
+  referenced;  only the xreflabel is accessible.  Therefore, use xreflabels
+  only when linking is common, and chapter/section information is unneeded.