Update reference docs for Highlighter fragmenter
Explain the fragmenter and add examples.
@@ -401,6 +401,128 @@ GET /_search
// CONSOLE
// TEST[setup:twitter]
+==== Fragmenter
+
+Fragmenter can control how text should be broken up in highlight snippets.
+However, this option is applicable only for the Plain Highlighter.
+There are two options:
+
+[horizontal]
+`simple`:: Breaks up text into same sized fragments.
+`span`:: Same as the simple fragmenter, but tries not to break up text between highlighted terms (this is applicable when using phrase like queries). This is the default.
+
+[source,js]
+--------------------------------------------------
+GET twitter/tweet/_search
+{
+ "query" : {
+ "match_phrase": { "message": "number 1" }
+ },
+ "highlight" : {
+ "fields" : {
+ "message" : {
+ "fragment_size" : 15,
+ "number_of_fragments" : 3,
+ "fragmenter": "simple"
+ }
+ }
+ }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:twitter]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+ ...
+ "hits": {
+ "total": 1,
+ "max_score": 1.4818809,
+ "hits": [
+ {
+ "_index": "twitter",
+ "_type": "tweet",
+ "_id": "1",
+ "_score": 1.4818809,
+ "_source": {
+ "user": "test",
+ "message": "some message with the number 1",
+ "date": "2009-11-15T14:12:12",
+ "likes": 1
+ },
+ "highlight": {
+ "message": [
+ " with the <em>number</em>",
+ " <em>1</em>"
+ ]
+ }
+ }
+ ]
+ }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,/]
+
+[source,js]
+--------------------------------------------------
+GET twitter/tweet/_search
+{
+ "query" : {
+ "match_phrase": { "message": "number 1" }
+ },
+ "highlight" : {
+ "fields" : {
+ "message" : {
+ "fragment_size" : 15,
+ "number_of_fragments" : 3,
+ "fragmenter": "span"
+ }
+ }
+ }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:twitter]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+ ...
+ "hits": {
+ "total": 1,
+ "max_score": 1.4818809,
+ "hits": [
+ {
+ "_index": "twitter",
+ "_type": "tweet",
+ "_id": "1",
+ "_score": 1.4818809,
+ "_source": {
+ "user": "test",
+ "message": "some message with the number 1",
+ "date": "2009-11-15T14:12:12",
+ "likes": 1
+ },
+ "highlight": {
+ "message": [
+ "some message with the <em>number</em> <em>1</em>"
+ ]
+ }
+ }
+ ]
+ }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,/]
+
+If the `number_of_fragments` option is set to `0`,
+`NullFragmenter` is used which does not fragment the text at all.
+This is useful for highlighting the entire content of a document or field.
==== Highlight query
