[DOCS] Rewrite bool query

docs/reference/query-dsl/bool-query.asciidoc

@@ -4,37 +4,15 @@
 <titleabbrev>Boolean</titleabbrev>
 ++++
 
-A query that matches documents matching boolean combinations of other
-queries. The bool query maps to Lucene `BooleanQuery`. It is built using
-one or more boolean clauses, each clause with a typed occurrence. The
-occurrence types are:
-
-[cols="<,<",options="header",]
-|=======================================================================
-|Occur |Description
-|`must` |The clause (query) must appear in matching documents and will
-contribute to the score.
-
-|`filter` |The clause (query) must appear in matching documents. However unlike
-`must` the score of the query will be ignored. Filter clauses are executed
-in <<query-filter-context,filter context>>, meaning that scoring is ignored
-and clauses are considered for caching.
-
-|`should` |The clause (query) should appear in the matching document.
-
-|`must_not` |The clause (query) must not appear in the matching
-documents.  Clauses are executed in <<query-filter-context,filter context>> meaning
-that scoring is ignored and clauses are considered for caching. Because scoring is
-ignored, a score of `0` for all documents is returned.
-|=======================================================================
-
-The `bool` query takes a _more-matches-is-better_ approach, so the score from
-each matching `must` or `should` clause will be added together to provide the
-final `_score` for each document.
+Returns documents matching one or more wrapped queries, called query clauses or
+clauses, using `and`, `or`, and `not` logic.
+
+[[bool-query-ex-request]]
+==== Example request
 
 [source,js]
---------------------------------------------------
-POST _search
+---------------------------------
+GET /_search
 {
   "query": {
     "bool" : {
@@ -58,23 +36,97 @@ POST _search
     }
   }
 }
---------------------------------------------------
+---------------------------------
 // CONSOLE
 
+[[bool-query-top-level-params]]
+==== Top-level parameters for `bool`
+
+`must`::
++
+--
+(Optional, query object) Contains one or more query clauses. Returned documents
+**must match all** of these queries.
+
+This parameter is like the `AND` boolean operator.
+
+{es} calculates <<relevance-scores,relevance scores>> for
+any returned documents. 
+--
+
+`must_not`::
++
+--
+(Optional, query object) Contains one or more query clauses. Returned documents
+**must not match any** of these queries.
+
+This parameter is like the `NOT` boolean operator.
+
+{es} runs `must_not` queries in the <<query-filter-context,filter context>>. To
+speed up performance, {es} automatically caches frequently used filter-context
+queries.
+--
+
+`should`::
++
+--
+(Optional, query object) Contains one or more query clauses. Returned documents
+**must match one or more** of these queries. You can adjust the number of
+required matches using the <<query-dsl-minimum-should-match,
+`minimum_should_match` parameter>>.
+
+This parameter is like the `OR` boolean operator.
+
+{es} calculates <<relevance-scores,relevance scores>> for
+any returned documents. 
+--
+
+`filter`::
++
+--
+(Optional, query object) Contains one or more query clauses. Returned documents
+**must match all** these queries. {es} does not calculate
+<<relevance-scores,relevance scores>> for any returned documents.
+
+The `filter` parameter is like the `must` parameter. Unlike the `must`
+parameter, filter queries do not calculate <<relevance-scores,relevance
+scores>>. Instead, the `filter` query assigns all matching documents a score of
+`0`.
+
+To speed up performance, {es} automatically caches frequently used filter
+queries.
+--
+
+`minimum_should_match`::
+(Optional, string) Number of `should` query clauses returned documents must
+match. For valid values and more information, see the
+<<query-dsl-minimum-should-match, `minimum_should_match` parameter>>.
+
+[[bool-query-notes]]
+==== Notes
+
+[[bool-query-more-matches-better]]
+===== Relevance scores for documents matching multiple query clauses
+When calculating <<relevance-scores,relevance scores>> for documents
+returned by multiple query clauses, the `bool` query takes a
+**more-matches-is-better** approach. {es} adds the score from each matching
+`must` or `should` clause, calculating a final relevance score for each
+document.
+
 [[score-bool-filter]]
-==== Scoring with `bool.filter`
+===== Scoring with `bool.filter`
 
 Queries specified under the `filter` element have no effect on scoring --
-scores are returned as `0`.  Scores are only affected by the query that has
-been specified.  For instance, all three of the following queries return
+scores are returned as `0`. Scores are only affected by the query that has
+been specified. For instance, all three of the following queries return
 all documents where the `status` field contains the term `active`.
 
 This first query assigns a score of `0` to all documents, as no scoring
 query has been specified:
 
 [source,js]
 ---------------------------------
-GET _search
+GET /_search
 {
   "query": {
     "bool": {
@@ -94,7 +146,7 @@ all documents.
 
 [source,js]
 ---------------------------------
-GET _search
+GET /_search
 {
   "query": {
     "bool": {
@@ -118,7 +170,7 @@ by the filter.
 
 [source,js]
 ---------------------------------
-GET _search
+GET /_search
 {
   "query": {
     "constant_score": {
@@ -133,7 +185,8 @@ GET _search
 ---------------------------------
 // CONSOLE
 
-==== Using named queries to see which clauses matched
+[[bool-query-named-queries]]
+===== Using named queries to see which clauses matched
 
 If you need to know which of the clauses in the bool query matched the documents
 returned from the query, you can use