svn commit: r1829420 - /jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md

[th...@apache.org]

Author: thomasm
Date: Wed Apr 18 08:25:14 2018
New Revision: 1829420

URL: http://svn.apache.org/viewvc?rev=1829420&view=rev
Log:
OAK-5051 Document XPath (and SQL-2) syntax as supported by Oak

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md?rev=1829420&r1=1829419&r2=1829420&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md Wed Apr 18 08:25:14 2018
@@ -342,18 +342,21 @@ If excerpts and highlighting is needed,
 
     /jcr:root/content//*[jcr:contains(., 'test')]/(rep:excerpt())
     
-That way, the excerpt and highlighting features of Lucene are used.
+If the excerpt is read using `row.getValue("rep:excerpt(.)")`, 
+then excerpt and highlighting features of Lucene are used.
 That is, if a Lucene index is configured for the query, and excerpts are generated
 (see <a href="lucene.html#Property_Definitions">useInExcerpt</a>).
-On the other hand, If the query doesn't contain the excerpt property, for example as follows:
+
+On the other hand, if the excerpt is requested for properties
+that are not specified in the query, as in `row.getValue("rep:excerpt(@title)")`, 
+or if the query doesn't contain the excerpt property, for example
 
     /jcr:root/content//*[jcr:contains(., 'test')]
 
-and the excerpt is requested after running the query, 
-then the SimpleExcerptProvider utility is used, which generates excerpt from the content, and does highlighting.
-This is not not recommended; specially highlighting is limited 
-(eg. stopwords are ignored, highlighting is case sensitive).
-The same problem occurs if excerpts for properties are requested that are not specified in the query.
+then the SimpleExcerptProvider utility is used, 
+which generates excerpt from the content, and does highlighting.
+Using the SimpleExcerptProvider is not recommended; specially highlighting is limited 
+(eg. the index configuration is ignored, stopwords are ignored, and highlighting is case sensitive).
 
 ### Native Queries