Author: thomasm
Date: Thu Feb  8 15:29:46 2018
New Revision: 1823566

URL: http://svn.apache.org/viewvc?rev=1823566&view=rev
Log:
OAK-6898 Query: grammar documentation / annotated railroad diagrams

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

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md?rev=1823566&r1=1823565&r2=1823566&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md 
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md Thu 
Feb  8 15:29:46 2018
@@ -76,6 +76,9 @@ Examples:
 
 It is recommended to enclose property names in square brackets.
 
+For the "excerpt" property, 
+see <a href="query-engine.html#Excerpts_and_Highlighting">Excerpts and 
Highlighting</a>.
+
 Not listed above are "special" properties such as "[jcr:path]" (the path), 
"[jcr:score]" (the score),
 "[rep:suggest()]".
 

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md?rev=1823566&r1=1823565&r2=1823566&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md 
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md Thu 
Feb  8 15:29:46 2018
@@ -140,9 +140,9 @@ rep:excerpt( [. | [ relativePath / ] @pr
 <br/> | rep:facet ( [ relativePath / ] @propertyName )
 </h4>
 
-"rep:excerpt": include the spellcheck column in the result.
+"rep:excerpt": include the excerpt in the result.
 Since Oak version 1.8.1, optionally a property name can be specified.
-See also <a href="lucene.html#Property_Definitions">useInExcerpt</a>.
+See <a href="query-engine.html#Excerpts_and_Highlighting">Excerpts and 
Highlighting</a>.
 
 "rep:spellcheck": Include the spellcheck in the result.
 See <a href="query-engine.html#Spellchecking">Spellchecking</a>.
@@ -155,6 +155,10 @@ See <a href="query-engine.html#Facets">F
 
 Examples:
 
+    /jcr:root/content//*[jcr:contains(., 'test')]/(rep:excerpt())
+
+    /jcr:root/content//*[jcr:contains(., 'test')]/(rep:excerpt(@jcr:title) | 
rep:excerpt())
+
     /jcr:root/content//*[rep:suggest('in ')]/(rep:suggest())
 
     /jcr:root/content//*[jcr:contains(@jcr:title, 'oak')]/(rep:facet(@tags))

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=1823566&r1=1823565&r2=1823566&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 Thu 
Feb  8 15:29:46 2018
@@ -34,6 +34,7 @@ grep "^#.*$" src/site/markdown/query/que
         * [Equality for Path Constraints](#Equality_for_Path_Constraints)
     * [Slow Queries and Read Limits](#Slow_Queries_and_Read_Limits)
     * [Full-Text Queries](#Full-Text_Queries)
+    * [Excerpts and Highlighting](#Excerpts_and_Highlighting)
     * [Native Queries](#Native_Queries)
     * [Similarity Queries](#Similarity_Queries)
     * [Spellchecking](#Spellchecking)
@@ -335,6 +336,24 @@ For compatibility with Jackrabbit 2.x, s
 That means the query `contains(., "word ''hello world'' word")` is supported.
 New applications should not rely on this feature.
 
+### Excerpts and Highlighting
+
+If excerpts and highlighting is needed, then queries should contains the 
"excerpt" property, as follows:
+
+    /jcr:root/content//*[jcr:contains(., 'test')]/(rep:excerpt())
+    
+That way, the 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:
+
+    /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.
 
 ### Native Queries
 


Reply via email to