doc: clarify handling of ts_headline() operators & extra words

Reported-by: Ngigi Waithaka & Alex Malek
Bug: 15172

Discussion: https://postgr.es/m/152461454026.19805.6310947081647212894@wrigleys.postgresql.org

Backpatch-through: 16

diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index 1550be5695071bb8328a69700ad00648e7ae177d..a7767049c8c1b06ac3352444c7ae4e40bd3f2753 100644 (file)
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -1287,7 +1287,10 @@ ts_headline( config 
    
     ts_headline accepts a document along
     with a query, and returns an excerpt from
-    the document in which terms from the query are highlighted.  The
+    the document in which terms from the query are highlighted.
+    Specifically, the function will use the query to select relevant
+    text fragments, and then highlight all words that appear in the query,
+    even if those word positions do not match the query's restrictions.  The
     configuration to be used to parse the document can be specified by
     config; if config
     is omitted, the