diff --git a/rest-api-spec/test/README.asciidoc b/rest-api-spec/test/README.asciidoc
index 4c8fe01eb13..604aad945cb 100644
--- a/rest-api-spec/test/README.asciidoc
+++ b/rest-api-spec/test/README.asciidoc
@@ -28,6 +28,7 @@ first entry in the list of tests should be called `skip`, and contain
 the range of versions to be skipped, and the reason why the tests are
 skipped.  For instance:
 
+....
     "Parent":
      - skip:
           version:     "0 - 0.90.2"
@@ -35,6 +36,7 @@ skipped.  For instance:
 
      - do:
        ... test definitions ...
+....
 
 All tests in the file should be skipped if: `min <= current <= max`.
 
@@ -54,9 +56,11 @@ Required operators:
 
 The `do` operator calls a method on the client. For instance:
 
+....
     - do:
         cluster.health:
             level: shards
+....
 
 The response from the `do` operator should be stored in the `response` var, which
 is reset (1) at the beginning of a file or (2) on the next `do`.
@@ -64,15 +68,18 @@ is reset (1) at the beginning of a file or (2) on the next `do`.
 If the arguments to `do` include `catch`, then we are expecting an error, which should
 be caught and tested.  For instance:
 
+....
     - do:
         catch:        missing
         get:
             index:    test
             type:    test
             id:        1
+....
 
 The argument to `catch` can be any of:
 
+[horizontal]
 `missing`::     a 404 response from ES
 `conflict`::     a 409 response from ES
 `request`::        a generic error response from ES
@@ -89,6 +96,7 @@ For some tests, it is necessary to extract a value from the previous `response`,
 order to reuse it in a subsequent `do` and other tests.  For instance, when
 testing indexing a document without a specified ID:
 
+....
     - do:
         index:
             index: test
@@ -100,6 +108,7 @@ testing indexing a document without a specified ID:
             type:  test
             id:    $id    # replace `$id` with the stashed value
     - match: { _id: $id } # the returned `response._id` matches the stashed `id`
+....
 
 The stash should be reset at the beginning of each test file.
 
@@ -108,40 +117,43 @@ The stash should be reset at the beginning of each test file.
 The specified key exists and has a true value (ie not `0`, `false`, `undefined`, `null`
 or the empty string), eg:
 
+....
     - is_true:  fields._parent  # the _parent key exists in the fields hash and is "true"
+....
 
 === `is_false`
 
 The specified key doesn't exist or has a false value (ie `0`, `false`, `undefined`,
 `null` or the empty string), eg:
 
-    - is_false:  fields._source  # the _source key doesn't exist in the fields hash
+....
+    - is_false:  fields._source  # the _source key doesn't exist in the fields hash or is "false"
+....
 
 === `match`
 
 Used to compare two variables (could be scalars, arrays or hashes).  The two variables
 should be identical, eg:
 
-    -
+....
+    - match: { _source: { foo: bar }}
+....
 
 === `lt` and `gt`
 
 Compares two numeric values, eg:
 
+....
     - lt: { fields._ttl: 10000 }  # the `_ttl` value is less than 10,000
+....
 
 === `length`
 
 This depends on the datatype of the value being examined, eg:
 
+....
     - length: { _id: 22    }   # the `_id` string is 22 chars long
     - length: { _tokens: 3 }   # the `_tokens` array has 3 elements
     - length: { _source: 5 }   # the `_source` hash has 5 keys
-
-
-
-
-
-
-
+....