📖 Improve chaining docs (#726)

Signed-off-by: Juan Manuel Leflet Estrada <jleflete@redhat.com>

docs/rules.md

@@ -371,9 +371,10 @@ when:
 
 #### Chaining Condition Variables
 
-You can also chain the variables from one condition to be used as input in another condition in a _or_ and _and_ block of conditions
+It is also possible to use the output of one condition as the input for filtering another one in an and/or condition. This is called
+*condition chaining*.
 
-What a given condition has in its output, can be seen in the openapi spec, by finding the `<provider>.<condition>.out` component. **NOTE** Every condition, has a list of files where the incidents occurred, and the output for a condition is in the extras section.
+The OpenAPI spec contains more information about what each condition can offer in its output; check the `<provider>.<condition>.out` component.
 
 Example:
 
@@ -382,7 +383,7 @@ when:
  or:
   - builtin.xml:
       xpath: "//dependencies/dependency"
-      filepaths: "{{poms.extras.filepaths}}"
+      filepaths: "{{poms.filepaths}}"
     from: poms
   - builtin.file:
       pattern: pom.xml
@@ -396,9 +397,9 @@ In the above example the output of `builtin.file` condition is saved `as` poms.
       as: poms
 ```
 
-The variables of `builtin.file` can then be used in the `builtin.xml` condition, by saying `from` and then using [mustache templates](https://mustache.github.io/mustache.5.html) in the _provider_ condition` block.
+The variables of `builtin.file` can then be used in the `builtin.xml` condition, by writing `from` and then using [mustache templates](https://mustache.github.io/mustache.5.html) in the _provider_ condition` block.
 
-This is how this particular condition, knows to use the variables set to the name `poms`. 
+This is how this particular condition knows how to use the variables set to the name `poms`. 
 
 ```yaml
     from: poms
@@ -415,6 +416,21 @@ Then you can use the variables by setting them as mustached templates in any of
     ignore: true
 ``` 
 
+#### Note about chaining in the Java provider
+In the java provider, the `filepaths` variable must be uppercased. For instance:
+```yaml
+  when:
+    and:
+      - java.referenced:
+          pattern: org.springframework.web.bind.annotation.RequestMapping
+          location: ANNOTATION
+        as: annotation
+      - java.referenced:
+          pattern: org.springframework.stereotype.Controller
+          location: ANNOTATION
+          filepaths: "{{annotation.Filepaths}}"
+```
+
 
 ## Ruleset