diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
index 667a6876bd..994b58d435 100644
--- a/docs/Gemfile.lock
+++ b/docs/Gemfile.lock
@@ -6,8 +6,8 @@ GEM
       minitest (~> 5.1)
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    addressable (2.5.1)
-      public_suffix (~> 2.0, >= 2.0.2)
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
@@ -16,21 +16,21 @@ GEM
     ethon (0.10.1)
       ffi (>= 1.3.0)
     execjs (2.7.0)
-    faraday (0.13.0)
+    faraday (0.13.1)
       multipart-post (>= 1.2, < 3)
     ffi (1.9.18)
     forwardable-extended (2.6.0)
     gemoji (3.0.0)
-    github-pages (151)
+    github-pages (158)
       activesupport (= 4.2.8)
       github-pages-health-check (= 1.3.5)
-      jekyll (= 3.5.1)
+      jekyll (= 3.5.2)
       jekyll-avatar (= 0.4.2)
       jekyll-coffeescript (= 1.0.1)
       jekyll-default-layout (= 0.1.4)
       jekyll-feed (= 0.9.2)
       jekyll-gist (= 1.4.1)
-      jekyll-github-metadata (= 2.6.0)
+      jekyll-github-metadata (= 2.9.1)
       jekyll-mentions (= 1.2.0)
       jekyll-optional-front-matter (= 0.2.0)
       jekyll-paginate (= 1.1.0)
@@ -38,7 +38,7 @@ GEM
       jekyll-redirect-from (= 0.12.1)
       jekyll-relative-links (= 0.4.1)
       jekyll-sass-converter (= 1.5.0)
-      jekyll-seo-tag (= 2.2.3)
+      jekyll-seo-tag (= 2.3.0)
       jekyll-sitemap (= 1.0.0)
       jekyll-swiss (= 0.4.0)
       jekyll-theme-architect (= 0.1.0)
@@ -50,7 +50,7 @@ GEM
       jekyll-theme-midnight (= 0.1.0)
       jekyll-theme-minimal (= 0.1.0)
       jekyll-theme-modernist (= 0.1.0)
-      jekyll-theme-primer (= 0.4.0)
+      jekyll-theme-primer (= 0.5.2)
       jekyll-theme-slate (= 0.1.0)
       jekyll-theme-tactile (= 0.1.0)
       jekyll-theme-time-machine (= 0.1.0)
@@ -69,11 +69,11 @@ GEM
       octokit (~> 4.0)
       public_suffix (~> 2.0)
       typhoeus (~> 0.7)
-    html-pipeline (2.6.0)
+    html-pipeline (2.7.0)
       activesupport (>= 2)
       nokogiri (>= 1.4)
     i18n (0.8.6)
-    jekyll (3.5.1)
+    jekyll (3.5.2)
       addressable (~> 2.4)
       colorator (~> 1.0)
       jekyll-sass-converter (~> 1.0)
@@ -94,7 +94,7 @@ GEM
       jekyll (~> 3.3)
     jekyll-gist (1.4.1)
       octokit (~> 4.2)
-    jekyll-github-metadata (2.6.0)
+    jekyll-github-metadata (2.9.1)
       jekyll (~> 3.1)
       octokit (~> 4.0, != 4.4.0)
     jekyll-mentions (1.2.0)
@@ -112,7 +112,7 @@ GEM
       jekyll (~> 3.3)
     jekyll-sass-converter (1.5.0)
       sass (~> 3.4)
-    jekyll-seo-tag (2.2.3)
+    jekyll-seo-tag (2.3.0)
       jekyll (~> 3.3)
     jekyll-sitemap (1.0.0)
       jekyll (~> 3.3)
@@ -144,8 +144,9 @@ GEM
     jekyll-theme-modernist (0.1.0)
       jekyll (~> 3.5)
       jekyll-seo-tag (~> 2.0)
-    jekyll-theme-primer (0.4.0)
+    jekyll-theme-primer (0.5.2)
       jekyll (~> 3.5)
+      jekyll-github-metadata (~> 2.9)
       jekyll-seo-tag (~> 2.2)
     jekyll-theme-slate (0.1.0)
       jekyll (~> 3.5)
@@ -214,4 +215,4 @@ DEPENDENCIES
   jekyll
 
 BUNDLED WITH
-   1.13.6
+   1.15.1
diff --git a/docs/README.md b/docs/README.md
index 17c8437056..a183bdfa9a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,15 +7,16 @@ This site was built using the tomjohnson1492/documentation-theme-jekyll theme
 
 A Jekyll-based theme designed for documentation and help systems. See the link for detailed instructions on setting up and configuring everything. http://idratherbewriting.com/documentation-theme-jekyll/
 
+## Building using Bundler
 
-Build the site to see the instructions for using it. Or just go here: [http://idratherbewriting.com/documentation-theme-jekyll/](http://idratherbewriting.com/documentation-theme-jekyll/)
-
-Run `bundle exec jekyll serve --watch` to fire up Jekyll on local machine
-
-## Using Docker
-
-One time: `docker build --no-cache -t mydocs .`
-
-Now run the site with `docker run --rm=true -v "$PWD:/src" -p 4005:4005 mydocs serve -H 0.0.0.0`
+    bundle install # once
+    bundle exec jekyll serve
+
+Go to: http://localhost:4005/
+
+## Building using Docker
+
+    docker build --no-cache -t pmd-doc . # once
+    docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
 
 Go to: http://localhost:4005/
diff --git a/docs/_config.yml b/docs/_config.yml
index 67e10eb08d..2064c7c9d4 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -2,6 +2,7 @@ repository: pmd/pmd
 
 pmd:
     version: 6.0.0
+    date: to-be-defined
 
 output: web
 # this property is useful for conditional filtering of content that is separate from the PDF.
diff --git a/docs/_data/sidebars/pmd_sidebar.yml b/docs/_data/sidebars/pmd_sidebar.yml
index 1effd4022e..c3099fd0ea 100644
--- a/docs/_data/sidebars/pmd_sidebar.yml
+++ b/docs/_data/sidebars/pmd_sidebar.yml
@@ -45,9 +45,20 @@ entries:
     - title: Suppressing
       url: /pmd_userdocs_suppressing.html
       output: web, pdf
-    - title: Tools / Integrations
-      url: /pmd_userdocs_tools.html
-      output: web, pdf
+      subfolders:
+      - title: Tools / Integrations
+        output: web, pdf
+        subfolderitems:
+        - title: Maven PMD Plugin
+          output: web, pdf
+          url: /pmd_userdocs_tools_maven.html
+        - title: Ant
+          output: web, pdf
+          url: /pmd_userdocs_tools_ant.html
+        - title: Other Tools / Integrations
+          output: web, pdf
+          url: /pmd_userdocs_tools.html
+
     - title: FAQ
       url: /pmd_userdocs_faq.html
       output: web, pdf
@@ -123,6 +134,12 @@ entries:
   - title: Developer Documentation
     output: web, pdf
     folderitems:
+    - title: Developer Resources
+      url: /pmd_devdocs_development.html
+      output: web, pdf
+    - title: Writing Documentation
+      url: /pmd_devdocs_writing_documentation.html
+      output: web, pdf
     - title: Code Style
       url: /pmd_devdocs_codestyle.html
       output: web, pdf
diff --git a/docs/_includes/sidebar.html b/docs/_includes/sidebar.html
index 30adf87229..51bfa69a32 100644
--- a/docs/_includes/sidebar.html
+++ b/docs/_includes/sidebar.html
@@ -6,7 +6,11 @@
     {% for folder in entry.folders %}
     {% if folder.output contains "web" %}
     <li>
+        {% if folder.url %}
+        <a href="{{ folder.url | remove: "/" }}">{{ folder.title }}</a>
+        {% else %}
         <a href="#">{{ folder.title }}</a>
+        {% endif %}
         <ul>
             {% for folderitem in folder.folderitems %}
             {% if folderitem.output contains "web" %}
diff --git a/docs/index.md b/docs/index.md
index 89247e9ed1..2f63d0f86d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,38 +2,97 @@
 title: PMD Introduction
 keywords: java
 tags: [getting_started]
-sidebar: pmd_sidebar
 permalink: index.html
-summary: Welcome to PMD, an extensible cross-language static code analyzer.
+toc: false
+summary: >
+    Welcome to PMD, an extensible cross-language static code analyzer.
+    It finds common programming flaws like unused variables, empty catch blocks, unnecessary object creation,
+    and so forth. Additionally it includes CPD, the copy-paste-detector. CPD finds duplicated code.
+last_updated: August 2017
+author: Jeff Jensen <jjensen@apache.org>, Andreas Dangel <andreas.dangel@adangel.org>
 ---
 
 {% include image.html file="pmd-logo-big.png" alt="PMD Logo" %}
 
-# Welcome to PMD
+<br>
 
-PMD scans source code in Java and other languages and looks for potential problems like:
+**PMD** scans source code in Java and other languages and looks for potential problems like:
 
 *   Possible bugs - empty try/catch/finally/switch statements
 *   Dead code - unused local variables, parameters and private methods
 *   Suboptimal code - wasteful String/StringBuffer usage
 *   Overcomplicated expressions - unnecessary if statements, for loops that could be while loops
-*   Duplicate code - copied/pasted code means copied/pasted bugs
 
-## Download
+**CPD**, the copy-paste-detector, finds duplicated code in many languages:
 
-You can [download everything from here](https://github.com/pmd/pmd/releases).
+*   Duplicate code is often just copied and pasted. This means, the bugs are also copied and pasted. Fixing
+    them means, fix all duplicated code locations.
 
-You can get an overview of all the rules for e.g. Java at the [rulesets index](pmd_rules_java.html) page.
+## Features
 
-PMD is [integrated](pmd_userdocs_tools.html) with JDeveloper, Eclipse, JEdit, JBuilder, BlueJ, CodeGuide, NetBeans/Sun Java Studio Enterprise/Creator, IntelliJ IDEA, TextPad, Maven, Ant, Gel, JCreator, and Emacs.
+{::options parse_block_html="true" /}
+
+<div class="row"><div class="col-lg-6">
+### PMD
+
+Features:
+
+*   Supporting 8 languages
+*   Many ready-to-use built-in rules.
+*   Custom rules can be written in Java
+*   Custom rules can be written using XPath expression that query the AST of the sources
+*   Many output formats
+*   Many integrations into IDEs, build tools
+
+Supported Languages:
+
+*   [Java](pmd_rules_java.html)
+*   [JavaScript](pmd_rules_ecmascript.html)
+*   [Salesforce.com Apex](pmd_rules_apex.html) and [Visualforce](pmd_rules_vf.html)
+*   [PLSQL](pmd_rules_plsql.html)
+*   [Apache Velocity](pmd_rules_vm.html)
+*   [XML](pmd_rules_xml.html) and [Maven POM](pmd_rules_pom.html)
+*   [XSL](pmd_rules_xsl.html)
+
+</div><div class="col-lg-6">
+### CPD
+
+Features:
+
+*   Supporting 19 languages
+*   Simple GUI
+*   Fast
+*   Many integrations
+
+Supported Languages:
+
+*   Java
+*   C, C++
+*   C#
+*   Groovy
+*   PHP
+*   Ruby
+*   Fortran
+*   JavaScript
+*   PLSQL
+*   Apache Velocity
+*   Scala
+*   Objective C
+*   Matlab
+*   Python
+*   Go
+*   Swift
+*   Salesforce.com Apex and Visualforce
+
+</div></div>
+
+## Download PMD {{ site.pmd.version }}
+
+Latest Version: {{ site.pmd.version }} ({{ site.pmd.date }})
+
+*   [Release Notes](pmd_release_notes.html)
+*   [Download](https://github.com/pmd/pmd/releases)
 
 
-## Future Releases
-
-The next version of PMD will be developed in parallel with this release. We will release additional bugfix versions as needed.
-
-A [snapshot](http://pmd.sourceforge.net/snapshot) of the web site for the new version is generated daily by our continuous integration server.
-
-Maven packages are also generated regularly and uploaded to [Sonatypes OSS snapshot repository](https://oss.sonatype.org/content/repositories/snapshots/net/sourceforge/pmd/pmd/).
 
 {% include links.html %}
diff --git a/docs/pages/pmd/devdocs/adding_metrics_support_to_language.md b/docs/pages/pmd/devdocs/adding_metrics_support_to_language.md
index 7773d1a1ee..2e14e78412 100644
--- a/docs/pages/pmd/devdocs/adding_metrics_support_to_language.md
+++ b/docs/pages/pmd/devdocs/adding_metrics_support_to_language.md
@@ -2,13 +2,12 @@
 title: Adding support for metrics to a language
 short_title: Implement a metrics framework
 tags: [customizing]
-summary: "PMD's Java module has an extensive framework for the calculation of metrics, which allows rule developers 
-to implement and use new code metrics very simply. Most of the functionality of this framework is abstracted in such 
+summary: "PMD's Java module has an extensive framework for the calculation of metrics, which allows rule developers
+to implement and use new code metrics very simply. Most of the functionality of this framework is abstracted in such
 a way that any PMD supported language can implement such a framework without too much trouble. Here's how."
 last_updated: August 2017
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_adding_metrics_support_to_language.html
-folder: pmd/devdocs
+author: Clément Fournier <clement.fournier76@gmail.com>
 ---
 
 {% include warning.html content="WIP, unstable API" %}
@@ -18,100 +17,100 @@ folder: pmd/devdocs
 ### Overview of the Java framework
 
 The framework has several subsystems, the two most easily identifiable being:
-* A **project memoizer** (`ProjectMemoizer`). When a metric is computed, it's stored back in this structure and can be 
-reused later. This 
- reduces the overhead on the calculation of e.g. aggregate results (`ResultOption` calculations). The contents of 
- this data structure are indexed with fully qualified names (`JavaQualifiedName`), which must identify unambiguously 
+* A **project memoizer** (`ProjectMemoizer`). When a metric is computed, it's stored back in this structure and can be
+reused later. This
+ reduces the overhead on the calculation of e.g. aggregate results (`ResultOption` calculations). The contents of
+ this data structure are indexed with fully qualified names (`JavaQualifiedName`), which must identify unambiguously
  classes and methods.
 
-* The **façade**. The static end-user façade (`JavaMetrics`) is backed by an instance of a `JavaMetricsFaçade`. This 
-  allows us to abstract the functionality of the façade into `pmd-core` for other frameworks to use. The façade 
-  instance contains a project memoizer for the analysed project, and a metrics computer 
-  (`JavaMetricsComputer`). It's this last object which really computes the metric and stores back its result in the 
+* The **façade**. The static end-user façade (`JavaMetrics`) is backed by an instance of a `JavaMetricsFaçade`. This
+  allows us to abstract the functionality of the façade into `pmd-core` for other frameworks to use. The façade
+  instance contains a project memoizer for the analysed project, and a metrics computer
+  (`JavaMetricsComputer`). It's this last object which really computes the metric and stores back its result in the
   project mirror, while the façade only handles parameters.
 
-Metrics (`Metric<N>`) plug in to this static system and only provide behaviour that's executed by the metrics computer. 
-Internally, metric keys (`MetricKey<N>`) are parameterized with their version (`MetricVersion`) to index memoisation 
-maps (see `ParameterizedMetricKey<N>`). This allows us to memoise several versions of the same metric without conflict. 
+Metrics (`Metric<N>`) plug in to this static system and only provide behaviour that's executed by the metrics computer.
+Internally, metric keys (`MetricKey<N>`) are parameterized with their version (`MetricVersion`) to index memoisation
+maps (see `ParameterizedMetricKey<N>`). This allows us to memoise several versions of the same metric without conflict.
 
 {% include important.html content="The following will be moved when multifile analysis and metrics are separated" %}
 <!-- We should probably create a dedicated page about the architecture of multifile analysis/ signature matching and how
  to implement that -->
 
-At the very least, a metrics framework has those two components and is just a convenient way to compute and memoize 
-metrics on a single file. Yet, one of the goals of the metrics framework is to allow for **multi-file analysis**, which 
-make it possible, for instance, to compute the coupling between two classes. This feature uses two major 
+At the very least, a metrics framework has those two components and is just a convenient way to compute and memoize
+metrics on a single file. Yet, one of the goals of the metrics framework is to allow for **multi-file analysis**, which
+make it possible, for instance, to compute the coupling between two classes. This feature uses two major
 components:
-* A **project mirror**. This data structure that stores info about all classes and operations (and other relevant 
+* A **project mirror**. This data structure that stores info about all classes and operations (and other relevant
   entities, such as fields, packages, etc.) of the analysed project. This is implemented by `PackageStats` in the Java
   framework. The role of this structure is to make info about other files available to rules. It's filled by a visitor before rules apply.
 
-  The information stored in this data structure that's accessible to metrics is mainly comprised of method and field 
-  signatures (e.g. `JavaOperationSignature`), which describes concisely the characteristics of the method or field 
+  The information stored in this data structure that's accessible to metrics is mainly comprised of method and field
+  signatures (e.g. `JavaOperationSignature`), which describes concisely the characteristics of the method or field
   (roughly, its modifiers).
-  
-* Some kind of method and field **usage resolution**, i.e. some way to find the fully qualified name of a method from a 
+
+* Some kind of method and field **usage resolution**, i.e. some way to find the fully qualified name of a method from a
   method call expression node. This is the trickiest part to implement. In Java it depends on type resolution.
 
 ### Abstraction layer
 
-As you may have seen, most of the functionality of the first two components are abstracted into `pmd-core`. This 
-allows us to implement new metrics frameworks quite quickly. These abstract components are parameterized by the 
-node types of the class and operation AST nodes. Moreover, it makes the external behaviour of the framework is very 
+As you may have seen, most of the functionality of the first two components are abstracted into `pmd-core`. This
+allows us to implement new metrics frameworks quite quickly. These abstract components are parameterized by the
+node types of the class and operation AST nodes. Moreover, it makes the external behaviour of the framework is very
 stable across languages, yet each component can easily be customized by adding methods or overriding existing ones.
 
-The signature matching aspect is framed by generic interfaces, but it can't really be abstracted more 
+The signature matching aspect is framed by generic interfaces, but it can't really be abstracted more
 than that. For instance, the project mirror is very language specific. Java's implementation uses the natural structure
-provided by the language's package system to structure the project's content. Apex, on the other, has no package 
-system and thus can't use the same mechanism. That explains why the interfaces framing the project mirror are very 
+provided by the language's package system to structure the project's content. Apex, on the other, has no package
+system and thus can't use the same mechanism. That explains why the interfaces framing the project mirror are very
 loose. Their main goal is to provide type safety through generics.
- 
-Moreover, usage resolution depends on the availability of type resolution for the given language, which is only implemented in 
-Java. For these reasons, signature matching is considered an optional feature of the metrics framework. But despite 
-this limitation, signature matching still provides a elegant way to find information about the class we're in. This 
-feature requires no usage resolution and can be used to implement sophisticated metrics, that already give access to 
+
+Moreover, usage resolution depends on the availability of type resolution for the given language, which is only implemented in
+Java. For these reasons, signature matching is considered an optional feature of the metrics framework. But despite
+this limitation, signature matching still provides a elegant way to find information about the class we're in. This
+feature requires no usage resolution and can be used to implement sophisticated metrics, that already give access to
 detection strategies.
 
 ## Implementation of a new framework
 
 ### 1. Groundwork
 
-* Create a class implementing `QualifiedName`. This implementation must be tailored to the target language so 
-  that it can indentify unambiguously any class and operation in the analysed project. You 
+* Create a class implementing `QualifiedName`. This implementation must be tailored to the target language so
+  that it can indentify unambiguously any class and operation in the analysed project. You
   must implement `equals`, `hashCode` and `toString`.
   [Example](https://github.com/pmd/pmd/blob/52d78d2fa97913cf73814d0307a1c1ae6125a437/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/JavaQualifiedName.java)
-* Determine the AST nodes that correspond to class and method declaration in your language. These types are 
-  referred hereafter as `T` and `O`, respectively. Both these types must implement the interface `QualifiableNode`, 
+* Determine the AST nodes that correspond to class and method declaration in your language. These types are
+  referred hereafter as `T` and `O`, respectively. Both these types must implement the interface `QualifiableNode`,
   which means they must expose a `getQualifiedName` method to give access to their qualified name.
 
 ### 2. Implement and wire the project memoizer
 * Create a class extending `BasicProjectMemoizer<T, O>`. There's no abstract functionality to implement.
   [Example](https://github.com/pmd/pmd/blob/52d78d2fa97913cf73814d0307a1c1ae6125a437/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/metrics/JavaProjectMemoizer.java)
-* Create an AST visitor that fills the project memoizer with memoizers. For that, you use `BasicProjectMemoizer`'s 
-  `addClassMemoizer` and `addOperationMemoizer` methods with a qualified name. 
+* Create an AST visitor that fills the project memoizer with memoizers. For that, you use `BasicProjectMemoizer`'s
+  `addClassMemoizer` and `addOperationMemoizer` methods with a qualified name.
   [Example](https://github.com/pmd/pmd/blob/master/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/metrics/JavaMetricsVisitor.java)
-* Create a façade class for your visitor. This class extends a `*ParserVisitorAdapter` class and only overrides the 
-  `initializeWith(Node)` method. It's supposed to make your real visitor accept the node in parameter. 
+* Create a façade class for your visitor. This class extends a `*ParserVisitorAdapter` class and only overrides the
+  `initializeWith(Node)` method. It's supposed to make your real visitor accept the node in parameter.
   [Example](https://github.com/pmd/pmd/blob/52d78d2fa97913cf73814d0307a1c1ae6125a437/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/metrics/JavaMetricsVisitorFacade.java)
-* Override the `getMetricsVisitorFacade()` method in your language's handler (e.g. `ApexHandler`). This method gives 
-  back a `VisitorStarter` which initializes your façade with a `Node`. 
+* Override the `getMetricsVisitorFacade()` method in your language's handler (e.g. `ApexHandler`). This method gives
+  back a `VisitorStarter` which initializes your façade with a `Node`.
   [Example](https://github.com/pmd/pmd/blob/52d78d2fa97913cf73814d0307a1c1ae6125a437/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/AbstractJavaHandler.java#L100-L108)
 * Your project memoizer should now get filled when the `metrics` attribute is set to `true` in the rule XML.
 
 ### 3. Implement the façade
-* Create a class extending `AbstractMetricsComputer<T, O>`. This object will be responsible for calculating metrics 
-  given a memoizer, a node and info about the metric. Typically, this object is stateless so you might as well make it 
+* Create a class extending `AbstractMetricsComputer<T, O>`. This object will be responsible for calculating metrics
+  given a memoizer, a node and info about the metric. Typically, this object is stateless so you might as well make it
   a singleton.
   [Example](https://github.com/pmd/pmd/blob/52d78d2fa97913cf73814d0307a1c1ae6125a437/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/metrics/JavaMetricsComputer.java)
-* Create a class extending `AbstractMetricsFacade<T, O>`. This class needs a reference to your `ProjectMemoizer` and 
-  your `MetricsComputer`. It backs the real end user façade, and handles user provided parameters before delegating to 
+* Create a class extending `AbstractMetricsFacade<T, O>`. This class needs a reference to your `ProjectMemoizer` and
+  your `MetricsComputer`. It backs the real end user façade, and handles user provided parameters before delegating to
   your `MetricsComputer`.
   [Example](https://github.com/pmd/pmd/blob/52d78d2fa97913cf73814d0307a1c1ae6125a437/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/metrics/JavaMetricsFacade.java)
-* Create the static façade of your framework. This one has an instance of your `MetricsFaçade` object and delegates 
+* Create the static façade of your framework. This one has an instance of your `MetricsFaçade` object and delegates
   static methods to that instance.
   [Example](https://github.com/pmd/pmd/blob/52d78d2fa97913cf73814d0307a1c1ae6125a437/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/metrics/JavaMetrics.java)
-* Create classes `AbstractOperationMetric` and `AbstractClassMetric`. These must implement `Metric<T>` and 
-  `Metric<O>`, respectively. They typically provide defaults for the `supports` method of each metric. 
+* Create classes `AbstractOperationMetric` and `AbstractClassMetric`. These must implement `Metric<T>` and
+  `Metric<O>`, respectively. They typically provide defaults for the `supports` method of each metric.
   [Example](https://github.com/pmd/pmd/blob/52d78d2fa97913cf73814d0307a1c1ae6125a437/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/metrics/impl/AbstractJavaOperationMetric.java)
 * Create enums `ClassMetricKey` and `OperationMetricKey`. These must implement `MetricKey<T>` and `MetricKey<O>`. The
   enums list all available metric keys for your language.
@@ -122,21 +121,20 @@ detection strategies.
 {% include important.html content="The following section will be moved when multifile analysis and metrics are separated" %}
 
 ### Optional: Signature matching
- 
-You can match the signature of anything: method, field, class, package... It depends on what's useful for you. 
-Suppose you want to be able to match signatures for nodes of type `N`. What you have to do then is the following: 
- 
-* Create a class implementing the interface `Signature<N>`. Signatures describe basic information about the node, 
-which typically includes most of the modifiers they declare (eg visibility, abstract or virtual, etc.). 
+
+You can match the signature of anything: method, field, class, package... It depends on what's useful for you.
+Suppose you want to be able to match signatures for nodes of type `N`. What you have to do then is the following:
+
+* Create a class implementing the interface `Signature<N>`. Signatures describe basic information about the node,
+which typically includes most of the modifiers they declare (eg visibility, abstract or virtual, etc.).
 It's up to you to define the right level of detail, depending on the accuracy of the pattern matching required.
-* Make type `N` implement `SignedNode<N>`. This makes the node capable of giving its signature. Factory methods to 
+* Make type `N` implement `SignedNode<N>`. This makes the node capable of giving its signature. Factory methods to
 build a `Signature<N>` from a `N` are a good idea.
 * Create signature masks. A mask is an object that matches some signatures based on their features. For example, with
- the Java framework, you can build a `JavaOperationSigMask` that matches all method signatures with visibility 
+ the Java framework, you can build a `JavaOperationSigMask` that matches all method signatures with visibility
  `public`. A sigmask implements `SigMask<S>`, where `S` is the type of signature your mask handles.
 * Typically, the project mirror stores the signatures, so you have to implement it in a way that makes it possible to
- associate a signature with the qualified name of its node. 
-* If you want to implement signature matching, create an `AbstractMetric` class, which gives access to a 
-`SignatureMatcher` to your metrics. Typically, your implementation of `ProjectMirror` implements a 
+ associate a signature with the qualified name of its node.
+* If you want to implement signature matching, create an `AbstractMetric` class, which gives access to a
+`SignatureMatcher` to your metrics. Typically, your implementation of `ProjectMirror` implements a
 custom `SignatureMatcher` interface, and your façade can give back its instance of the project mirror.
-
diff --git a/docs/pages/pmd/devdocs/adding_new_cpd_language.md b/docs/pages/pmd/devdocs/adding_new_cpd_language.md
index ee89261caa..7286b5ce57 100644
--- a/docs/pages/pmd/devdocs/adding_new_cpd_language.md
+++ b/docs/pages/pmd/devdocs/adding_new_cpd_language.md
@@ -4,9 +4,8 @@ short_title: Add a New CPD Language
 tags: [customizing]
 summary: How to Add a New CPD Language
 last_updated: July 3, 2016
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_adding_new_cpd_language.html
-folder: pmd/devdocs
+author: Romain PELISSE <belaran@gmail.com>
 ---
 
 # How to Add a New Language to CPD
diff --git a/docs/pages/pmd/devdocs/building.md b/docs/pages/pmd/devdocs/building.md
index 2e91e2837d..35b4e5e676 100644
--- a/docs/pages/pmd/devdocs/building.md
+++ b/docs/pages/pmd/devdocs/building.md
@@ -1,8 +1,7 @@
 ---
 title: Building PMD from source
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_building.html
-folder: pmd/devdocs
+author: Tom Copeland, Xavier Le Vourch <xlv@users.sourceforge.net>
 ---
 
 # Compiling PMD
diff --git a/docs/pages/pmd/devdocs/development.md b/docs/pages/pmd/devdocs/development.md
new file mode 100644
index 0000000000..d3acec6821
--- /dev/null
+++ b/docs/pages/pmd/devdocs/development.md
@@ -0,0 +1,36 @@
+---
+title: Developer Resources
+permalink: pmd_devdocs_development.html
+last_updated: August 2017
+---
+The next version of PMD will be developed in parallel with this release. We will release additional bugfix versions as needed.
+
+## Source Code
+
+The complete source code can be found on github:
+
+*   [github.com/pmd/pmd](https://github.com/pmd/pmd) - main PMD repository. Includes all the code to support all languages, including this documentation.
+*   [github.com/pmd/pmd.github.io](https://github.com/pmd/pmd.github.io) - Contains the landing page [https://pmd.github.io](https://pmd.github.io)
+*   [github.com/pmd/build-tools](https://github.com/pmd/build-tools) - Contains the checkstyle rules we use
+*   [github.com/pmd/pmd-eclipse-plugin](https://github.com/pmd/pmd-eclipse-plugin) - The PMD eclipse plugin
+*   [github.com/pmd](https://github.com/pmd) - PMD Organization at github. There are a couple of more repositories
+
+## Continuous Integration
+
+We use [Travis CI](https://travis-ci.org/pmd) as our ci service. The main repo and the eclipse plugin are built for
+every push. Each pull request is built as well.
+
+The maven snapshot artifacts are deployed at [Sonatypes OSS snapshot repository](https://oss.sonatype.org/content/repositories/snapshots/net/sourceforge/pmd/pmd/).
+
+Ready-to-use binary packages are uploaded to sourceforge at <https://sourceforge.net/projects/pmd/files/pmd/>.
+
+## Documentation and Webpages
+
+A [snapshot](http://pmd.sourceforge.net/snapshot) of the web site for the new version is generated travis-ci as well.
+
+## Contributing
+
+First off, thanks for taking the time to contribute!
+
+Please have a look at [CONTRIBUTING.md](https://github.com/pmd/pmd/blob/master/CONTRIBUTING.md) and
+[BUILDING.md](https://github.com/pmd/pmd/blob/master/BUILDING.md).
diff --git a/docs/pages/pmd/devdocs/how_pmd_works.md b/docs/pages/pmd/devdocs/how_pmd_works.md
index c54c9e4c41..a0ea2ddb57 100644
--- a/docs/pages/pmd/devdocs/how_pmd_works.md
+++ b/docs/pages/pmd/devdocs/how_pmd_works.md
@@ -3,9 +3,8 @@ title: PMD How it Works
 tags: [customizing]
 summary: How PMD Works
 last_updated: July 3, 2016
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_how_pmd_works.html
-folder: pmd/devdocs
+author: Tom Copeland
 ---
 
 # How it works
diff --git a/docs/pages/pmd/devdocs/info_for_developers.md b/docs/pages/pmd/devdocs/info_for_developers.md
index 6911d0014b..425db6a2c4 100644
--- a/docs/pages/pmd/devdocs/info_for_developers.md
+++ b/docs/pages/pmd/devdocs/info_for_developers.md
@@ -4,9 +4,8 @@ short_title: Info for Developers
 tags: [customizing]
 summary: Info for PMD Developers
 last_updated: July 3, 2016
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_info_for_developers.html
-folder: pmd/devdocs
+author: Hooper Bloob <hooperbloob@users.sourceforge.net>, Romain Pelisse <rpelisse@users.sourceforge.net>
 ---
 
 # Information for PMD Developers
diff --git a/docs/pages/pmd/devdocs/making_rulesets.md b/docs/pages/pmd/devdocs/making_rulesets.md
index 91b17daedc..8ee2c766d6 100644
--- a/docs/pages/pmd/devdocs/making_rulesets.md
+++ b/docs/pages/pmd/devdocs/making_rulesets.md
@@ -3,9 +3,8 @@ title:  PMD Making Rulesets
 tags: [customizing]
 summary: Making Custom Rulesets for PMD
 last_updated: July 3, 2016
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_making_rulesets.html
-folder: pmd/devdocs
+author: Tom Copeland <tomcopeland@users.sourceforge.net>
 ---
 
 # How to make a new rule set
diff --git a/docs/pages/pmd/devdocs/metrics_howto.md b/docs/pages/pmd/devdocs/metrics_howto.md
index b2530dba42..8c7045e062 100644
--- a/docs/pages/pmd/devdocs/metrics_howto.md
+++ b/docs/pages/pmd/devdocs/metrics_howto.md
@@ -1,22 +1,29 @@
 ---
 title:  Using code metrics in custom rules
 tags: [customizing]
-summary: "PMD was recently enhanced with the ability to compute code metrics on Java and Apex source (the so-called 
-Metrics Framework). This framework provides developers with a straightforward interface to use code metrics in their 
+summary: "PMD was recently enhanced with the ability to compute code metrics on Java and Apex source (the so-called
+Metrics Framework). This framework provides developers with a straightforward interface to use code metrics in their
 rules, and to extend the framework with their own custom metrics."
 last_updated: July 20, 2017
 permalink: pmd_devdocs_metrics_howto.html
+author: Clément Fournier <clement.fournier76@gmail.com>
 ---
 # Using code metrics in custom rules
 
 ## Using the metrics framework
 
-{%include note.html content="The following explains how to use the Java metrics framework. The Apex framework 
+{%include note.html content="Using the metrics framework is for now restricted to Java rules (with plans to support
+XPath rules later)." %}
+
+To use the metrics framework in a custom rule, the first thing to do would be to **enable metrics by adding the
+`metrics="true"` attribute** to your rule's XML element.
+
+{%include note.html content="The following explains how to use the Java metrics framework. The Apex framework
 differs only by the name of its classes." %}
 
-In PMD's Metrics framework, a metric is an operation that can be carried out on nodes of a certain type and produces 
-a numeric result. In the Java framework, metrics can be computed on operation declaration nodes (constructor and 
-method declaration), and type declaration nodes (class, interface, enum, and annotation declarations). A metric 
+In PMD's Metrics framework, a metric is an operation that can be carried out on nodes of a certain type and produces
+a numeric result. In the Java framework, metrics can be computed on operation declaration nodes (constructor and
+method declaration), and type declaration nodes (class, interface, enum, and annotation declarations). A metric
 object in the framework can only handle either types or operations, but not both.
 
 PMD ships with a library of already implemented metrics. These metrics are referenced by `MetricKey` objects,
@@ -27,9 +34,6 @@ each enum.
 
 ## For XPath rules
 
-To use the metrics framework in a custom rule, the first thing to do would be to enable metrics by adding the
-`metrics="true"` attribute to your rule's XML element.
-
 XPath rules can compute metrics using the `metric` function. This function takes a single **string argument**,
 which is the name of the metric key as defined in  `JavaClassMetricKey` or `JavaOperationMetricKey`. The metric
  will be **computed on the context node**.
@@ -56,12 +60,13 @@ or `ConstructorDeclaration`.
 First, similarly to XPath rules, you should add the `metrics="true"` attribute to your rule's XML element.
 
 The static façade class `JavaMetrics` is the single entry point to compute metrics in the Java framework. 
+
 This class provides the method `get` and its overloads. The following sections describes the interface of this class.
 
 ### Basic usage
 
-The simplest overloads of `JavaMetrics.get` take two parameters: **a `MetricKey` and a node of the corresponding type.** 
-Say you want to write a rule to report methods that have a high cyclomatic complexity. In your rule's visitor, you 
+The simplest overloads of `JavaMetrics.get` take two parameters: **a `MetricKey` and a node of the corresponding type.**
+Say you want to write a rule to report methods that have a high cyclomatic complexity. In your rule's visitor, you
 can get the value of Cyclo for a method node like so:
 ```java
 public Object visit(ASTMethodDeclaration method, Object data) {
@@ -74,18 +79,18 @@ public Object visit(ASTMethodDeclaration method, Object data) {
 ```
 
 The same goes for class metrics: you select one among `JavaClassMetricKey`'s constants and pass it along with the node
- to `JavaMetrics.get`.
- 
- {%include tip.html
+to `JavaMetrics.get`.
+
+{%include tip.html
            content="A specific base rule class (`AbstractJavaMetricsRule`) exists
            to e.g. check constructors and method nodes completely alike. This comes
            in handy for metrics, as they usually don't make the distinction" %}
- 
+
 ### Capability checking
 
-Metrics are not necessarily computable on any node of the type they handle. For example, Cyclo cannot be computed on 
+Metrics are not necessarily computable on any node of the type they handle. For example, Cyclo cannot be computed on
 abstract methods. Metric keys provides a `supports(Node)` boolean method to find out if the metric can be computed on
-the specified node. **If the metric cannot be computed on the given node, `JavaMetrics.get` will return `Double.NaN` .** 
+the specified node. **If the metric cannot be computed on the given node, `JavaMetrics.get` will return `Double.NaN` .**
 If you're concerned about that, you can condition your call on whether the node is supported or not:
 ```java
 public Object visit(ASTMethodDeclaration method, Object data) {
@@ -101,16 +106,16 @@ public Object visit(ASTMethodDeclaration method, Object data) {
 
 ### Metric options
 
-Some metrics define options that can be used to slightly modify the computation. You'll typically see these options 
-gathered inside an enum in the implementation class of the metric, for example `CycloMetric.CycloOptions`. They're 
+Some metrics define options that can be used to slightly modify the computation. You'll typically see these options
+gathered inside an enum in the implementation class of the metric, for example `CycloMetric.CycloOptions`. They're
 also documented on the [index of metrics](pmd_java_metrics_index.html).
 
-To use options with a metric, you must first bundle them into a `MetricOptions` object. `MetricOptions` provides the 
-utility method `ofOptions` to get a `MetricOptions` bundle from a collection or with varargs parameters. You can then 
+To use options with a metric, you must first bundle them into a `MetricOptions` object. `MetricOptions` provides the
+utility method `ofOptions` to get a `MetricOptions` bundle from a collection or with varargs parameters. You can then
 pass this bundle as a parameter to `JavaMetrics.get`:
 ```java
 public Object visit(ASTMethodDeclaration method, Object data) {
-  int cyclo = (int) JavaMetrics.get(JavaOperationMetricKey.CYCLO, method, 
+  int cyclo = (int) JavaMetrics.get(JavaOperationMetricKey.CYCLO, method,
                                     MetricOptions.ofOptions(CycloOptions.IGNORE_BOOLEAN_PATHS));
   if (cyclo > 10) {
       // add violation
@@ -119,18 +124,18 @@ public Object visit(ASTMethodDeclaration method, Object data) {
 }
 ```
 
-The version of `MetricOptions.ofOptions` using a collection is useful when you're building a `MetricOptions` from eg 
-the value of an `EnumeratedMultiProperty`, which gives users control of the options they use. See 
+The version of `MetricOptions.ofOptions` using a collection is useful when you're building a `MetricOptions` from eg
+the value of an `EnumeratedMultiProperty`, which gives users control of the options they use. See
 [CyclomaticComplexityRule]( https://github.com/pmd/pmd/blob/master/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/metrics/rule/CyclomaticComplexityRule.java)
 for an example usage.
 
 ### Result options
 
-The Metrics API also gives you the possibility to aggregate the result of an operation metric on all operations of a 
+The Metrics API also gives you the possibility to aggregate the result of an operation metric on all operations of a
 class very simply. You can for example get the highest value of the metric over a class that way:
 ```java
 public Object visit(ASTClassOrInterfaceDeclaration clazz, Object data) {
-  int highest = (int) JavaMetrics.get(JavaOperationMetricKey.CYCLO, clazz, 
+  int highest = (int) JavaMetrics.get(JavaOperationMetricKey.CYCLO, clazz,
                                       ResultOption.HIGHEST);
   if (highest > 10) {
       // add violation
@@ -139,8 +144,8 @@ public Object visit(ASTClassOrInterfaceDeclaration clazz, Object data) {
 }
 ```
 
-Notice that **we use an operation metric and a class node**. The `ResultOption` parameter controls what result will be 
-computed: you can choose among `HIGHEST`, `SUM` and `AVERAGE`. You can use metric options together with a result 
+Notice that **we use an operation metric and a class node**. The `ResultOption` parameter controls what result will be
+computed: you can choose among `HIGHEST`, `SUM` and `AVERAGE`. You can use metric options together with a result
 option too.
 
 ### Complete use case
@@ -297,4 +302,3 @@ Language   | Java | Apex |
 -----------|------|------|
 Operation metrics| supports constructors and non abstract methods| supports any non abstract method except `<init>`, `<clinit>`, and `clone`
 Type declaration|supports classes and enums|supports classes
-
diff --git a/docs/pages/pmd/devdocs/pull_requests.md b/docs/pages/pmd/devdocs/pull_requests.md
index 965a2b6267..3580a8d757 100644
--- a/docs/pages/pmd/devdocs/pull_requests.md
+++ b/docs/pages/pmd/devdocs/pull_requests.md
@@ -1,6 +1,173 @@
 ---
-title: Pull Requests
-sidebar: pmd_sidebar
+title: Pull-Request Merge
 permalink: pmd_devdocs_pull_requests.html
-folder: pmd/devdocs
+last_updated: August 2017
+author: Andreas Dangel <andreas.dangel@adangel.org>
 ---
+
+## Contributing via pull requests
+
+First off, thanks for taking the time to contribute!
+
+*   Please create your pull request against the `master` branch. We will rebase/merge it to the maintenance
+    branches, if necessary. Just fork the [pmd repo](https://github.com/pmd/pmd/) and
+    create a [pull request](https://github.com/pmd/pmd/pulls).
+
+*   We are using [checkstyle](http://checkstyle.sourceforge.net/) to enforce a common code style.
+    The check is integrated into the default build - so, make sure, you can [build PMD](pmd_devdocs_building.html)
+    without errors.
+
+    See [code style](pmd_devdocs_codestyle.html) for more info.
+
+## Merging pull requests
+
+### Example 1: Merging PR #123 into master
+
+1.  Review the pull request
+
+    *   Compilation and checkstyle is verified already by travis build: PRs are automatically checked.
+    *   If it is a bug fix, a new unit test, that reproduces the bug, is mandatory. Without such a test, we might accidentally reintroduce the bug again.
+    *   Add the appropriate labels on the github issue: If the PR fixes a bug, the label "a:bug" should be used.
+    *   Make sure, the PR is added to the appropriate milestone. If the PR fixes a bug, make sure, that the bug issue is added to the same milestone.
+
+2.  The actual merge commands:
+
+    We assume, that the PR has been created from the master branch. If this is not the case,
+    then we'll either need to rebase or ask for rebasing before merging.
+
+    ```
+    git checkout master && git pull origin master                    # make sure, you have the latest code
+    git fetch origin pull/123/head:pr-123 && git checkout pr-123     # creates a new temporary branch
+    ```
+
+3.  Update the [release notes](https://github.com/pmd/pmd/blob/master/docs/pages/release_notes.md):
+
+    *   Are there any API changes, that need to be documented? (Section "API Changes")
+    *   Are there any significant changes to existing rules, that should be mentioned?
+        (Section "Modified Rules" / "New Rules" / "Removed Rules")
+    *   If the PR fixes a bug, make sure, it is listed under the section "Fixed Issues".
+    *   In any case, add the PR to the section "External Contributions"
+    *   Commit these changes with the message:
+
+            git add docs/pages/release_notes.md
+            git commit -m "Update release notes, refs #123"
+
+    {% include note.html content="If the PR fixes a bug, verify, that we have a commit with the message
+    \"Fixes #issue-number\". If this doesn't exist, you can add it to the commit message when
+    updating the release notes: `Update release notes, refs #123, fixes #issue-number`.
+    This will automatically close the github issue." %}
+
+4.  Now merge the pull request into the master branch:
+
+    ```
+    git checkout master
+    git merge --no-ff pr-123
+    ```
+
+    {%include note.html content="If there are merge conflicts, you'll need to deal with them here." %}
+
+5.  Run the complete build: `./mvnw clean verify`
+
+    {% include note.html content="This will execute all the unit tests and the checkstyle tests. It ensures,
+    that the complete project can be build and is functioning on top of the current master." %}
+
+6.  If the build was successful, you are ready to push:
+
+    ```
+    git push origin master
+    ```
+
+    Since the temporary branch is now not needed anymore, you can delete it:
+    `git branch -d pr-123`.
+
+
+### Example 2: Merging PR #124 into a maintenance branch
+
+We ask, to create every pull request against master, to make it easier to contribute.
+But if a pull request is intended to fix a bug in an older version of PMD, then we need to backport this pull request.
+
+#### Creating a maintenance branch
+
+For older versions, we use maintenance branches, like `pmd/5.8.x`. If there is no maintenance branch for
+the specific version, then we'll have to create it first. Let's say, we want a maintenance branch for
+PMD version 5.8.0, so that we can create a bugfix release 5.8.1.
+
+1.  We'll simply create a new branch off of the release tag:
+
+    ```
+    git branch pmd/5.8.x pmd_releases/5.8.0 && git checkout pmd/5.8.x
+    ```
+
+2.  Now we'll need to adjust the version, since it's currently the same as the release version.
+    We'll change the version to the next patch version: "5.8.1-SNAPSHOT".
+
+    ```
+    ./mvnw versions:set -DnewVersion=5.8.1-SNAPSHOT
+    git add pom.xml \*/pom.xml
+    git commit -m "prepare next version 5.8.1-SNAPSHOT"
+    ```
+
+#### Merging the PR
+
+1.  As above: Review the PR
+
+2.  Fetch the PR and rebase it onto the maintenance branch:
+
+    ```
+    git fetch origin pull/124/head:pr-124 && git checkout pr-124     # creates a new temporary branch
+    git rebase master --onto pmd/5.8.x
+    ./mvnw clean verify                                # make sure, everything works after the rebase
+    ```
+
+    {%include note.html content="You might need to fix conflicts / backport the commits for the older
+    PMD version." %}
+
+3.  Update the release notes. See above for details.
+
+4.  Now merge the pull request into the maintenance branch:
+
+    ```
+    git checkout pmd/5.8.x
+    git merge --no-ff pr-124
+    ```
+
+5.  Just to be sure, run the complete build again: `./mvnw clean verify`.
+
+6.  If the build was successful, you are ready to push:
+
+    ```
+    git push origin pmd/5.8.x
+    ```
+
+7.  Since we have rebased the pull request, it won't appear as merged on github.
+    You need to manually close the pull request. Leave a comment, that it has been
+    rebased onto the maintenance branch.
+
+#### Merging into master
+
+Now the PR has been merged into the maintenance branch, but it is missing in any later version of PMD.
+Therefore, we merge first into the next minor version maintenance branch (if existing):
+
+    git checkout pmd/5.9.x
+    git merge pmd/5.8.x
+
+After that, we merge the changes into the master branch:
+
+    git checkout master
+    git merge pmd/5.9.x
+
+{%include note.html content="This ensures, that every change on the maintenance branch eventually ends
+up in the master branch and therefore in any future version of PMD.<br>
+The downside is however, that there are inevitable merge conflicts for the maven `pom.xml` files, since
+every branch changed the version number differently.<br>
+We could avoid this by merging only the temporary branch \"pr-124\" into each maintenance branch and
+eventually into master, with the risk of missing single commits in a maintenance branch, that have been
+done outside the temporary branch." %}
+
+#### Merging vs. Cherry-Picking
+
+We are not using cherry-picking, so that each fix is represented by a single commit.
+Cherry-picking would duplicate the commit and you can't see in the log, on which branches the fix has been
+integrated (e.g. gitk and github show the branches, from which the specific commit is reachable).
+
+The downside is a more complex history - the maintenance branches and master branch are "connected" and not separate.
diff --git a/docs/pages/pmd/devdocs/releasing.md b/docs/pages/pmd/devdocs/releasing.md
index ad14d84757..cf911cc79d 100644
--- a/docs/pages/pmd/devdocs/releasing.md
+++ b/docs/pages/pmd/devdocs/releasing.md
@@ -1,8 +1,7 @@
 ---
 title: Releasing
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_releasing.html
-folder: pmd/devdocs
+author: Romain Pelisse <rpelisse@users.sourceforge.net>, Andreas Dangel <adangel@users.sourceforge.net>
 ---
 
 This page describes the current status of the release process.
@@ -172,7 +171,7 @@ Maybe there are some milestones on sourceforge, too: <https://sourceforge.net/p/
 ### Merging
 
 If the release was done on a maintenance branch, such as `pmd/5.4.x`, then this branch should be
-merge into the next "higher" branches, such as `pmd/5.5.x` and `master`.
+merged into the next "higher" branches, such as `pmd/5.5.x` and `master`.
 
 This ensures, that all fixes done on the maintenance branch, finally end up in the other branches.
 In theory, the fixes should already be there, but you never now.
@@ -180,7 +179,7 @@ In theory, the fixes should already be there, but you never now.
 
 ### Multiple releases
 
-If releases from multiple branches are being done, the order matters. You should start from the "oldes" branch,
+If releases from multiple branches are being done, the order matters. You should start from the "oldest" branch,
 e.g. `pmd/5.4.x`, release from there. Then merge (see above) into the next branch, e.g. `pmd/5.5.x` and release
 from there. Then merge into the `master` branch and release from there. This way, the last release done, becomes
 automatically the latest release on <https://pmd.github.io/latest/> and on sourceforge.
diff --git a/docs/pages/pmd/devdocs/roadmap.md b/docs/pages/pmd/devdocs/roadmap.md
index e963dd9069..ee08fcc41a 100644
--- a/docs/pages/pmd/devdocs/roadmap.md
+++ b/docs/pages/pmd/devdocs/roadmap.md
@@ -1,8 +1,9 @@
 ---
 title: Roadmap
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_roadmap.html
-folder: pmd/devdocs
+author: >
+    Tom Copeland <tom@infoether.com>, Ryan Gustavson, Romain Pelisse <belaran@gmail.com>,
+    Juan Martín Sotuyo Dodero <juansotuyo@gmail.com>, Andreas Dangel <adangel@users.sourceforge.net>
 ---
 
 
diff --git a/docs/pages/pmd/devdocs/rule_guidelines.md b/docs/pages/pmd/devdocs/rule_guidelines.md
index 88dc5b643a..791830bcc3 100644
--- a/docs/pages/pmd/devdocs/rule_guidelines.md
+++ b/docs/pages/pmd/devdocs/rule_guidelines.md
@@ -3,9 +3,8 @@ title: PMD Rule Guidelines
 tags: [customizing]
 summary: Rule Guidelines
 last_updated: July 3, 2016
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_rule_guidelines.html
-folder: pmd/devdocs
+author: Xavier Le Vourch, Ryan Gustafson, Romain Pelisse
 ---
 
 # Rule Guidelines
diff --git a/docs/pages/pmd/devdocs/writing_documentation.md b/docs/pages/pmd/devdocs/writing_documentation.md
new file mode 100644
index 0000000000..078477f278
--- /dev/null
+++ b/docs/pages/pmd/devdocs/writing_documentation.md
@@ -0,0 +1,143 @@
+---
+title: Writing Documentation
+last_update: August 2017
+permalink: pmd_devdocs_writing_documentation.html
+keywords: documentation, jekyll, markdown
+author: Andreas Dangel <andreas.dangel@adangel.org>
+---
+
+PMD's documentation uses [Jekyll](https://jekyllrb.com/) with
+the [I'd rather be writing Jekyll Theme](http://idratherbewriting.com/documentation-theme-jekyll/index.html).
+
+Here are some quick tips.
+
+## Format
+
+The pages are in general in [Github Flavored Markdown](https://kramdown.gettalong.org/parser/gfm.html).
+
+## Structure
+
+All documentation is stored in the folder `docs/`. This is the folder, that github and the travis-ci scripts
+use to render the site.
+
+New pages are stored in the different subfolders under `pages`. The folder structure resembles the sidebar structure.
+Since all pages use a simple *permalink*, in the rendered html pages, all pages are flattened in one directory.
+This makes it easy to view the documentation also offline.
+
+## Building
+
+There are two ways, to execute jekyll:
+
+1.  Using [bundler](http://bundler.io/). This will install all the needed ruby packages locally and execute jekyll:
+
+        # this is required only once, to download and install the dependencies
+        bundle install
+        # this builds the documentation under _site
+        bundle exec jekyll build
+        # this runs a local webserver as http://localhost:4005
+        bundle exec jekyll serve
+
+2.  Using [docker](https://www.docker.com/). This will create a local docker image, into which all needed ruby
+    packages and jekyll is installed.
+
+        # this is required only once to create a local docker image named "pmd-doc"
+        docker build --no-cache -t pmd-doc .
+        # this builds the documentation under _site
+        docker run --rm=true -v "$PWD:/src" pmd-doc build -H 0.0.0.0
+        # this runs a local webserver as http://localhost:4005
+        docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
+
+The built site is stored locally in the (git ignored) directory `_site`. You can
+point your browser to `_site/index.html` to see the pmd documentation.
+
+Alternatively, you can start the local webserver, that will serve the documentation.
+Just go to http://localhost:4005.
+If a page is modified, the documentation will automatically be rendered again and
+all you need to do, is refreshing the page in your browser.
+
+See also the script [pmd-jekyll.sh](https://gist.github.com/oowekyala/ee6f8801138861072c59ce683bdf737b).
+It starts the jekyll server in the background and doesn't block the current shell.
+
+## The sidebar
+
+The sidebar is stored as a YAML document under `_data/sidebars/pmd_sidebar.yml`.
+
+Make sure to add an entry there, whenever you create a new page.
+
+
+## The frontmatter
+
+Each page in jekyll begins with a YAML section at the beginning. This section
+is separated by 3 dashes (`---`). Example:
+
+    ---
+    title: Writing Documentation
+    last_update: August 2017
+    permalink: pmd_devdocs_writing_documentation.html
+    ---
+
+    Some Text
+
+    # Some header
+
+There are a couple of possible fields. Most important and always
+required are **title** and **permalink**.
+
+By default, a page **toc** (table of contents) is automatically generated.
+You can prevent this with "toc: false".
+
+You can add **keywords**, that will be used for the on-site search: "keywords: documentation, jekyll, markdown"
+
+It's useful to maintain a **last_update** field. This will be added at the bottom of the
+page.
+
+A **summary** can also be provided. It will be added in a box before the content.
+
+For a more exhaustive list, see [Pages - Frontmatter](http://idratherbewriting.com/documentation-theme-jekyll/mydoc_pages.html#frontmatter).
+
+
+## Alerts and Callouts
+
+See [Alerts](http://idratherbewriting.com/documentation-theme-jekyll/mydoc_alerts.html).
+
+For example, a info-box can be created like this:
+
+    {%raw%}{% include note.html content="This is a note." %}{%endraw%}
+
+It renders as:
+
+{% include note.html content="This is a note." %}
+
+Other available types are:
+
+*   note.html
+*   tip.html
+*   warning.html
+*   important.html
+
+
+A callout is created like this:
+
+    {%raw%}{% include callout.html content="This is a callout of type default.<br/><br/>There are the following types available: danger, default, primary, success, info, and warning." type="default" %}{%endraw%}
+
+It renders as:
+
+{% include callout.html content="This is a callout of type default.<br/><br/>There are the following types available: danger, default, primary, success, info, and warning." type="default" %}
+
+## Code samples with syntax highlighting
+
+This is as easy as:
+
+    ``` java
+    public class Foo {
+        public void bar() { System.out.println("x"); }
+    }
+    ```
+
+This looks as follows:
+
+``` java
+public class Foo {
+    public void bar() { System.out.println("x"); }
+}
+```
diff --git a/docs/pages/pmd/devdocs/writing_pmd_rules.md b/docs/pages/pmd/devdocs/writing_pmd_rules.md
index cec80bd9b5..a6ec0ea893 100644
--- a/docs/pages/pmd/devdocs/writing_pmd_rules.md
+++ b/docs/pages/pmd/devdocs/writing_pmd_rules.md
@@ -3,9 +3,8 @@ title:  PMD Writing a Custom Rule
 tags: [customizing]
 summary: Writing a Custom Rule for PMD
 last_updated: July 3, 2016
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_writing_pmd_rules.html
-folder: pmd/devdocs
+author: Tom Copeland <tomcopeland@users.sourceforge.net>
 ---
 
 # How to write a PMD rule
diff --git a/docs/pages/pmd/devdocs/writing_xpath_rules.md b/docs/pages/pmd/devdocs/writing_xpath_rules.md
index 29fabd43cb..ccbc1982c1 100644
--- a/docs/pages/pmd/devdocs/writing_xpath_rules.md
+++ b/docs/pages/pmd/devdocs/writing_xpath_rules.md
@@ -1,11 +1,10 @@
 ---
-title:  PMD Writing XPath Rules
+title:  Writing XPath Rules
 tags: [customizing]
 summary: "Writing XPath rules for PMD"
 last_updated: July 3, 2016
-sidebar: pmd_sidebar
 permalink: pmd_devdocs_writing_xpath_rules.html
-folder: pmd/devdocs
+author: Miguel Griffa <mikkey@users.sourceforge.net>
 ---
 
 # XPath Rule tutorial
@@ -151,4 +150,50 @@ The following expression does the magic we need:
 
 We recommend at this point that you experiment with Designer putting the final modifier to the Factory and verifying that the results produced are those expected.
 
+## Creating a new rule definition
+
+To actually use your new XPath rule, it needs to be in a ruleset. You can create a new custom ruleset which just
+contains your new XPath rule. You can use the following template. Just make sure, to replace the `xpath` property,
+the example code and give your rule a useful name and message.
+
+``` xml
+<?xml version="1.0"?>
+
+<ruleset name="Custom Rules"
+    xmlns="http://pmd.sourceforge.net/ruleset/3.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/3.0.0 http://pmd.sourceforge.net/ruleset_3_0_0.xsd">
+    <description>
+Custom rules
+    </description>
+
+    <rule name="My Rule"
+          language="java"
+          message="violation message"
+          class="net.sourceforge.pmd.lang.rule.XPathRule">
+        <description>
+Rule Description
+         </description>
+         <priority>3</priority>
+         <properties>
+             <property name="xpath">
+                 <value><![CDATA[
+--- here comes your XPath expression
+]]></value>
+             </property>
+         </properties>
+         <example>
+ <![CDATA[
+public class ExampleCode {
+    public void foo() {
+    }
+}
+]]>
+        </example>
+    </rule>
+</ruleset>
+```
+
+
+
 Finally, for many more details on writing XPath rules, pick up [PMD Applied](http://pmdapplied.com/)!
diff --git a/docs/pages/pmd/languages/jsp.md b/docs/pages/pmd/languages/jsp.md
index 6a1a589fed..771f7af06a 100644
--- a/docs/pages/pmd/languages/jsp.md
+++ b/docs/pages/pmd/languages/jsp.md
@@ -1,8 +1,7 @@
 ---
 title: JSP Support
-sidebar: pmd_sidebar
 permalink: pmd_languages_jsp.html
-folder: pmd/languages
+author: Pieter Vanraemdonck
 ---
 
 ## What is currently supported and what is not
diff --git a/docs/pages/pmd/rules/apex/apexunit.md b/docs/pages/pmd/rules/apex/apexunit.md
index 64e984532c..b6b26fda98 100644
--- a/docs/pages/pmd/rules/apex/apexunit.md
+++ b/docs/pages/pmd/rules/apex/apexunit.md
@@ -40,6 +40,11 @@ public class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/apexunit.xml/ApexUnitTestClassShouldHaveAsserts" />
+```
+
 ## ApexUnitTestShouldNotUseSeeAllDataTrue
 
 **Since:** PMD 5.5.1
@@ -72,3 +77,8 @@ public class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/apexunit.xml/ApexUnitTestShouldNotUseSeeAllDataTrue" />
+```
+
diff --git a/docs/pages/pmd/rules/apex/braces.md b/docs/pages/pmd/rules/apex/braces.md
index f07d7b466b..5f4b7e565a 100644
--- a/docs/pages/pmd/rules/apex/braces.md
+++ b/docs/pages/pmd/rules/apex/braces.md
@@ -42,6 +42,11 @@ for (int i = 0; i < 42; i++) { // preferred approach
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/braces.xml/ForLoopsMustUseBraces" />
+```
+
 ## IfElseStmtsMustUseBraces
 
 **Since:** PMD 5.6.0
@@ -79,6 +84,11 @@ else
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/braces.xml/IfElseStmtsMustUseBraces" />
+```
+
 ## IfStmtsMustUseBraces
 
 **Since:** PMD 5.6.0
@@ -112,6 +122,11 @@ if (foo) {  // preferred approach
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/braces.xml/IfStmtsMustUseBraces" />
+```
+
 ## WhileLoopsMustUseBraces
 
 **Since:** PMD 5.6.0
@@ -145,3 +160,8 @@ while (true) {  // preferred approach
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/braces.xml/WhileLoopsMustUseBraces" />
+```
+
diff --git a/docs/pages/pmd/rules/apex/complexity.md b/docs/pages/pmd/rules/apex/complexity.md
index 96aab8d53b..b3832f5631 100644
--- a/docs/pages/pmd/rules/apex/complexity.md
+++ b/docs/pages/pmd/rules/apex/complexity.md
@@ -42,6 +42,11 @@ public class Foo {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |problemDepth|3|The if statement depth reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/AvoidDeeplyNestedIfStmts" />
+```
+
 ## ExcessiveClassLength
 
 **Since:** PMD 5.5.0
@@ -84,6 +89,11 @@ public class Foo {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/ExcessiveClassLength" />
+```
+
 ## ExcessiveParameterList
 
 **Since:** PMD 5.5.0
@@ -119,6 +129,11 @@ public void addPerson(Date birthdate, BodyMeasurements measurements, int ssn) {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/ExcessiveParameterList" />
+```
+
 ## ExcessivePublicCount
 
 **Since:** PMD 5.5.0
@@ -159,6 +174,11 @@ public class Foo {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/ExcessivePublicCount" />
+```
+
 ## NcssConstructorCount
 
 **Since:** PMD 5.5.0
@@ -198,6 +218,11 @@ public class Foo extends Bar {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/NcssConstructorCount" />
+```
+
 ## NcssMethodCount
 
 **Since:** PMD 5.5.0
@@ -236,6 +261,11 @@ public class Foo extends Bar {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/NcssMethodCount" />
+```
+
 ## NcssTypeCount
 
 **Since:** PMD 5.5.0
@@ -276,6 +306,11 @@ public class Foo extends Bar {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/NcssTypeCount" />
+```
+
 ## StdCyclomaticComplexity
 
 **Since:** PMD 5.5.0
@@ -341,6 +376,11 @@ public class Foo {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |reportLevel|10|Cyclomatic Complexity reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/StdCyclomaticComplexity" />
+```
+
 ## TooManyFields
 
 **Since:** PMD 5.5.0
@@ -381,3 +421,8 @@ public class Person {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |maxfields|15|Max allowable fields|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/complexity.xml/TooManyFields" />
+```
+
diff --git a/docs/pages/pmd/rules/apex/performance.md b/docs/pages/pmd/rules/apex/performance.md
index e0615d60c8..6cf6388106 100644
--- a/docs/pages/pmd/rules/apex/performance.md
+++ b/docs/pages/pmd/rules/apex/performance.md
@@ -39,6 +39,11 @@ public class Something {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/performance.xml/AvoidDmlStatementsInLoops" />
+```
+
 ## AvoidSoqlInLoops
 
 **Since:** PMD 5.5.0
@@ -69,3 +74,8 @@ public class Something {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/performance.xml/AvoidSoqlInLoops" />
+```
+
diff --git a/docs/pages/pmd/rules/apex/security.md b/docs/pages/pmd/rules/apex/security.md
index 9bcb42d431..09ca5f3905 100644
--- a/docs/pages/pmd/rules/apex/security.md
+++ b/docs/pages/pmd/rules/apex/security.md
@@ -37,6 +37,11 @@ public without sharing class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexBadCrypto" />
+```
+
 ## ApexCRUDViolation
 
 **Since:** PMD 5.5.3
@@ -76,6 +81,11 @@ public class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexCRUDViolation" />
+```
+
 ## ApexCSRF
 
 **Since:** PMD 5.5.3
@@ -109,6 +119,11 @@ public class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexCSRF" />
+```
+
 ## ApexDangerousMethods
 
 **Since:** PMD 5.5.3
@@ -144,6 +159,11 @@ public class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexDangerousMethods" />
+```
+
 ## ApexInsecureEndpoint
 
 **Since:** PMD 5.5.3
@@ -174,6 +194,11 @@ public without sharing class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexInsecureEndpoint" />
+```
+
 ## ApexOpenRedirect
 
 **Since:** PMD 5.5.3
@@ -204,6 +229,11 @@ public without sharing class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexOpenRedirect" />
+```
+
 ## ApexSharingViolations
 
 **Since:** PMD 5.5.3
@@ -231,6 +261,11 @@ public without sharing class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexSharingViolations" />
+```
+
 ## ApexSOQLInjection
 
 **Since:** PMD 5.5.3
@@ -259,6 +294,11 @@ public class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexSOQLInjection" />
+```
+
 ## ApexSuggestUsingNamedCred
 
 **Since:** PMD 5.5.3
@@ -301,6 +341,11 @@ public class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexSuggestUsingNamedCred" />
+```
+
 ## ApexXSSFromEscapeFalse
 
 **Since:** PMD 5.5.3
@@ -329,6 +374,11 @@ public without sharing class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexXSSFromEscapeFalse" />
+```
+
 ## ApexXSSFromURLParam
 
 **Since:** PMD 5.5.3
@@ -357,3 +407,8 @@ public without sharing class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/security.xml/ApexXSSFromURLParam" />
+```
+
diff --git a/docs/pages/pmd/rules/apex/style.md b/docs/pages/pmd/rules/apex/style.md
index 9e96f7c354..660db734fd 100644
--- a/docs/pages/pmd/rules/apex/style.md
+++ b/docs/pages/pmd/rules/apex/style.md
@@ -36,6 +36,11 @@ global class Unchangeable {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/style.xml/AvoidGlobalModifier" />
+```
+
 ## AvoidLogicInTrigger
 
 **Since:** PMD 5.5.0
@@ -75,6 +80,11 @@ trigger Accounts on Account (before insert, before update, before delete, after
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/style.xml/AvoidLogicInTrigger" />
+```
+
 ## ClassNamingConventions
 
 **Since:** PMD 5.5.0
@@ -99,6 +109,11 @@ public class Foo {}
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/style.xml/ClassNamingConventions" />
+```
+
 ## MethodNamingConventions
 
 **Since:** PMD 5.5.0
@@ -126,6 +141,11 @@ public class Foo {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/style.xml/MethodNamingConventions" />
+```
+
 ## MethodWithSameNameAsEnclosingClass
 
 **Since:** PMD 5.5.0
@@ -155,6 +175,11 @@ public class MyClass {
 |cc_remediation_points_multiplier|1|Code Climate Remediation Points multiplier|
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/style.xml/MethodWithSameNameAsEnclosingClass" />
+```
+
 ## VariableNamingConventions
 
 **Since:** PMD 5.5.0
@@ -196,3 +221,8 @@ public class Foo {
 |cc_block_highlighting|false|Code Climate Block Highlighting|
 |checkMembers|true|Check member variables|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/apex/style.xml/VariableNamingConventions" />
+```
+
diff --git a/docs/pages/pmd/rules/ecmascript/basic.md b/docs/pages/pmd/rules/ecmascript/basic.md
index 4276ff36e2..9663b6c9d0 100644
--- a/docs/pages/pmd/rules/ecmascript/basic.md
+++ b/docs/pages/pmd/rules/ecmascript/basic.md
@@ -55,6 +55,11 @@ function getX() {
 |allowTernaryResults|false|Allow assignment within the result expressions of a ternary operator|
 |allowIncrementDecrement|false|Allow increment or decrement operators within the conditional expression of an if, for, or while statement|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/AssignmentInOperand" />
+```
+
 ## AvoidTrailingComma
 
 **Since:** PMD 5.1
@@ -88,6 +93,11 @@ function(arg) {
 |allowObjectLiteral|false|Allow a trailing comma within an object literal|
 |allowArrayLiteral|false|Allow a trailing comma within an array literal|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/AvoidTrailingComma" />
+```
+
 ## ConsistentReturn
 
 **Since:** PMD 5.0
@@ -128,6 +138,11 @@ function bar() {
 |recordingLocalJsDocComments|true|Specifies that JsDoc comments are produced in the AST.|
 |recordingComments|true|Specifies that comments are produced in the AST.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/ConsistentReturn" />
+```
+
 ## EqualComparison
 
 **Since:** PMD 5.0
@@ -167,6 +182,11 @@ if (someVar != 3) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/EqualComparison" />
+```
+
 ## GlobalVariable
 
 **Since:** PMD 5.0
@@ -192,6 +212,11 @@ function(arg) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/GlobalVariable" />
+```
+
 ## InnaccurateNumericLiteral
 
 **Since:** PMD 5.0
@@ -221,6 +246,11 @@ var y = 1.1234567890123; // Ok
 var z = 1.12345678901234567; // Not good
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/InnaccurateNumericLiteral" />
+```
+
 ## ScopeForInVariable
 
 **Since:** PMD 5.0
@@ -269,6 +299,11 @@ function bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/ScopeForInVariable" />
+```
+
 ## UnreachableCode
 
 **Since:** PMD 5.0
@@ -303,6 +338,11 @@ function bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/UnreachableCode" />
+```
+
 ## UseBaseWithParseInt
 
 **Since:** PMD 5.0.1
@@ -331,3 +371,8 @@ parseInt("010");    // unclear, could be interpreted as 10 or 7 (with a base of
 parseInt("10", 10); // good
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/basic.xml/UseBaseWithParseInt" />
+```
+
diff --git a/docs/pages/pmd/rules/ecmascript/braces.md b/docs/pages/pmd/rules/ecmascript/braces.md
index 9b294698b2..5f67d6dcf7 100644
--- a/docs/pages/pmd/rules/ecmascript/braces.md
+++ b/docs/pages/pmd/rules/ecmascript/braces.md
@@ -34,6 +34,11 @@ for (var i = 0; i < 42; i++)
     foo();
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/braces.xml/ForLoopsMustUseBraces" />
+```
+
 ## IfElseStmtsMustUseBraces
 
 **Since:** PMD 5.0
@@ -65,6 +70,11 @@ else
     y++;
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/braces.xml/IfElseStmtsMustUseBraces" />
+```
+
 ## IfStmtsMustUseBraces
 
 **Since:** PMD 5.0
@@ -90,6 +100,11 @@ if (foo)
     x++;
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/braces.xml/IfStmtsMustUseBraces" />
+```
+
 ## WhileLoopsMustUseBraces
 
 **Since:** PMD 5.0
@@ -115,3 +130,8 @@ while (true)
     x++;
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/braces.xml/WhileLoopsMustUseBraces" />
+```
+
diff --git a/docs/pages/pmd/rules/ecmascript/controversial.md b/docs/pages/pmd/rules/ecmascript/controversial.md
index 611a49bc54..b73ea9d35b 100644
--- a/docs/pages/pmd/rules/ecmascript/controversial.md
+++ b/docs/pages/pmd/rules/ecmascript/controversial.md
@@ -27,3 +27,8 @@ with (object) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/controversial.xml/AvoidWithStatement" />
+```
+
diff --git a/docs/pages/pmd/rules/ecmascript/unnecessary.md b/docs/pages/pmd/rules/ecmascript/unnecessary.md
index a88dd7df01..6c5c0f5ec0 100644
--- a/docs/pages/pmd/rules/ecmascript/unnecessary.md
+++ b/docs/pages/pmd/rules/ecmascript/unnecessary.md
@@ -39,6 +39,11 @@ if (x) {
 return z;
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/unnecessary.xml/NoElseReturn" />
+```
+
 ## UnnecessaryBlock
 
 **Since:** PMD 5.0
@@ -70,6 +75,11 @@ if (bar) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/unnecessary.xml/UnnecessaryBlock" />
+```
+
 ## UnnecessaryParentheses
 
 **Since:** PMD 5.0
@@ -90,3 +100,8 @@ var y = (1 + 1); // Ok
 var z = ((1 + 1)); // Bad
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/ecmascript/unnecessary.xml/UnnecessaryParentheses" />
+```
+
diff --git a/docs/pages/pmd/rules/java.md b/docs/pages/pmd/rules/java.md
index a2bf7348cc..92c8d37e80 100644
--- a/docs/pages/pmd/rules/java.md
+++ b/docs/pages/pmd/rules/java.md
@@ -263,6 +263,7 @@ List of rulesets and rules contained in each ruleset.
 *   [AvoidAssertAsIdentifier](pmd_rules_java_migrating.html#avoidassertasidentifier): Use of the term 'assert' will conflict with newer versions of Java since it is a reserved word.
 *   [AvoidEnumAsIdentifier](pmd_rules_java_migrating.html#avoidenumasidentifier): Use of the term 'enum' will conflict with newer versions of Java since it is a reserved word.
 *   [ByteInstantiation](pmd_rules_java_migrating.html#byteinstantiation): Calling new Byte() causes memory allocation that can be avoided by the static Byte.valueOf().It m...
+*   [ForLoopCanBeForeach](pmd_rules_java_migrating.html#forloopcanbeforeach): Reports loops that can be safely replaced with the foreach syntax. The rule considers loops over ...
 *   [IntegerInstantiation](pmd_rules_java_migrating.html#integerinstantiation): Calling new Integer() causes memory allocation that can be avoided by the static Integer.valueOf(...
 *   [JUnit4SuitesShouldUseSuiteAnnotation](pmd_rules_java_migrating.html#junit4suitesshouldusesuiteannotation): In JUnit 3, test suites are indicated by the suite() method. In JUnit 4, suites are indicatedthro...
 *   [JUnit4TestShouldUseAfterAnnotation](pmd_rules_java_migrating.html#junit4testshoulduseafterannotation): In JUnit 3, the tearDown method was used to clean up all data entities required in running tests....
diff --git a/docs/pages/pmd/rules/java/android.md b/docs/pages/pmd/rules/java/android.md
index c62a608e96..a2ae5d4ed4 100644
--- a/docs/pages/pmd/rules/java/android.md
+++ b/docs/pages/pmd/rules/java/android.md
@@ -46,6 +46,11 @@ public class DummyActivity extends Activity {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/android.xml/CallSuperFirst" />
+```
+
 ## CallSuperLast
 
 **Since:** PMD 4.2.5
@@ -83,6 +88,11 @@ public class DummyActivity extends Activity {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/android.xml/CallSuperLast" />
+```
+
 ## DoNotHardCodeSDCard
 
 **Since:** PMD 4.2.6
@@ -107,3 +117,8 @@ public class MyActivity extends Activity {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/android.xml/DoNotHardCodeSDCard" />
+```
+
diff --git a/docs/pages/pmd/rules/java/basic.md b/docs/pages/pmd/rules/java/basic.md
index b465d2f469..70130b5879 100644
--- a/docs/pages/pmd/rules/java/basic.md
+++ b/docs/pages/pmd/rules/java/basic.md
@@ -45,6 +45,11 @@ for (int i = 0; i < 10; i++) {
 |checkContinueLoopTypes|[for, do, while]|Check for continue statements in loop types|
 |checkBreakLoopTypes|[for, do, while]|Check for break statements in loop types|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/AvoidBranchingStatementAsLastInLoop" />
+```
+
 ## AvoidDecimalLiteralsInBigDecimalConstructor
 
 **Since:** PMD 3.4
@@ -93,6 +98,11 @@ BigDecimal bd = new BigDecimal("1.123");     // preferred approach
 BigDecimal bd = new BigDecimal(12);          // preferred approach, ok for integer values
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/AvoidDecimalLiteralsInBigDecimalConstructor" />
+```
+
 ## AvoidMultipleUnaryOperators
 
 **Since:** PMD 4.2
@@ -126,6 +136,11 @@ int i = ~-2;
 int j = -~7;
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/AvoidMultipleUnaryOperators" />
+```
+
 ## AvoidThreadGroup
 
 **Since:** PMD 3.6
@@ -153,6 +168,11 @@ public class Bar {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/AvoidThreadGroup" />
+```
+
 ## AvoidUsingHardCodedIP
 
 **Since:** PMD 4.1
@@ -179,6 +199,11 @@ public class Foo {
 |checkAddressTypes|[IPv4, IPv6, IPv4 mapped IPv6]|Check for IP address types.|
 |pattern|^"[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}"$|Regular Expression|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/AvoidUsingHardCodedIP" />
+```
+
 ## AvoidUsingOctalValues
 
 **Since:** PMD 3.9
@@ -204,6 +229,11 @@ k = i * j;      // set k with 80 not 120
 |----|-------------|-----------|
 |strict|false|Detect violations between 00 and 07|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/AvoidUsingOctalValues" />
+```
+
 ## BigIntegerInstantiation
 
 **Since:** PMD 3.9
@@ -225,6 +255,11 @@ BigInteger bi4;
 bi4 = new BigInteger(0);                 // reference BigInteger.ZERO instead
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/BigIntegerInstantiation" />
+```
+
 ## BooleanInstantiation
 
 **Since:** PMD 1.2
@@ -242,6 +277,11 @@ Boolean bar = new Boolean("true");        // unnecessary creation, just referenc
 Boolean buz = Boolean.valueOf(false);    // ...., just reference Boolean.FALSE;
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/BooleanInstantiation" />
+```
+
 ## BrokenNullCheck
 
 **Since:** PMD 3.8
@@ -266,6 +306,11 @@ public String bar(String string) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/BrokenNullCheck" />
+```
+
 ## CheckResultSet
 
 **Since:** PMD 4.1
@@ -294,6 +339,11 @@ if (rst.next()) {    // result is properly examined and used
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/CheckResultSet" />
+```
+
 ## CheckSkipResult
 
 **Since:** PMD 5.0
@@ -325,6 +375,11 @@ public class Foo {
    }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/CheckSkipResult" />
+```
+
 ## ClassCastExceptionWithToArray
 
 **Since:** PMD 3.4
@@ -361,6 +416,11 @@ Integer[] a = (Integer [])c.toArray();
 Integer[] b = (Integer [])c.toArray(new Integer[c.size()]);
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/ClassCastExceptionWithToArray" />
+```
+
 ## CollapsibleIfStatements
 
 **Since:** PMD 3.1
@@ -396,6 +456,11 @@ void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/CollapsibleIfStatements" />
+```
+
 ## DontCallThreadRun
 
 **Since:** PMD 4.3
@@ -427,6 +492,11 @@ t.run();            // use t.start() instead
 new Thread().run(); // same violation
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/DontCallThreadRun" />
+```
+
 ## DontUseFloatTypeForLoopIndices
 
 **Since:** PMD 4.3
@@ -458,6 +528,11 @@ public class Count {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/DontUseFloatTypeForLoopIndices" />
+```
+
 ## DoubleCheckedLocking
 
 **Since:** PMD 1.04
@@ -493,6 +568,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/DoubleCheckedLocking" />
+```
+
 ## ExtendsObject
 
 **Since:** PMD 5.0
@@ -512,6 +592,11 @@ public class Foo extends Object {     // not required
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/ExtendsObject" />
+```
+
 ## ForLoopShouldBeWhileLoop
 
 **Since:** PMD 1.02
@@ -539,6 +624,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/ForLoopShouldBeWhileLoop" />
+```
+
 ## JumbledIncrementer
 
 **Since:** PMD 1.0
@@ -570,6 +660,11 @@ public class JumbledIncrementerRule1 {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/JumbledIncrementer" />
+```
+
 ## MisplacedNullCheck
 
 **Since:** PMD 3.5
@@ -617,6 +712,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/MisplacedNullCheck" />
+```
+
 ## OverrideBothEqualsAndHashcode
 
 **Since:** PMD 0.4
@@ -652,6 +752,11 @@ public class Foo {        // perfect, both methods provided
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/OverrideBothEqualsAndHashcode" />
+```
+
 ## ReturnFromFinallyBlock
 
 **Since:** PMD 1.05
@@ -680,6 +785,11 @@ public class Bar {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/ReturnFromFinallyBlock" />
+```
+
 ## SimplifiedTernary
 
 **Since:** PMD 5.4.0
@@ -724,6 +834,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/SimplifiedTernary" />
+```
+
 ## UnconditionalIfStatement
 
 **Since:** PMD 1.5
@@ -750,3 +865,8 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/basic.xml/UnconditionalIfStatement" />
+```
+
diff --git a/docs/pages/pmd/rules/java/braces.md b/docs/pages/pmd/rules/java/braces.md
index 86aef41add..a2ea2bab6b 100644
--- a/docs/pages/pmd/rules/java/braces.md
+++ b/docs/pages/pmd/rules/java/braces.md
@@ -28,6 +28,11 @@ for (int i = 0; i < 42; i++)
    foo();
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/braces.xml/ForLoopsMustUseBraces" />
+```
+
 ## IfElseStmtsMustUseBraces
 
 **Since:** PMD 0.2
@@ -58,6 +63,11 @@ if (foo)
        x = x-1;
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/braces.xml/IfElseStmtsMustUseBraces" />
+```
+
 ## IfStmtsMustUseBraces
 
 **Since:** PMD 1.0
@@ -83,6 +93,11 @@ if (foo) {  // preferred approach
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/braces.xml/IfStmtsMustUseBraces" />
+```
+
 ## WhileLoopsMustUseBraces
 
 **Since:** PMD 0.7
@@ -108,3 +123,8 @@ while (true) {  // preferred approach
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/braces.xml/WhileLoopsMustUseBraces" />
+```
+
diff --git a/docs/pages/pmd/rules/java/clone.md b/docs/pages/pmd/rules/java/clone.md
index af33883b92..7091400db3 100644
--- a/docs/pages/pmd/rules/java/clone.md
+++ b/docs/pages/pmd/rules/java/clone.md
@@ -43,6 +43,11 @@ public class Foo implements Cloneable {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/clone.xml/CloneMethodMustBePublic" />
+```
+
 ## CloneMethodMustImplementCloneable
 
 **Since:** PMD 1.9
@@ -76,6 +81,11 @@ public class MyClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/clone.xml/CloneMethodMustImplementCloneable" />
+```
+
 ## CloneMethodReturnTypeMustMatchClassName
 
 **Since:** PMD 5.4.0
@@ -114,6 +124,11 @@ public class Foo implements Cloneable {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/clone.xml/CloneMethodReturnTypeMustMatchClassName" />
+```
+
 ## CloneThrowsCloneNotSupportedException
 
 **Since:** PMD 1.9
@@ -146,6 +161,11 @@ public class MyClass implements Cloneable{
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/clone.xml/CloneThrowsCloneNotSupportedException" />
+```
+
 ## ProperCloneImplementation
 
 **Since:** PMD 1.4
@@ -176,3 +196,8 @@ class Foo{
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/clone.xml/ProperCloneImplementation" />
+```
+
diff --git a/docs/pages/pmd/rules/java/codesize.md b/docs/pages/pmd/rules/java/codesize.md
index bad1edbc14..de62bd2e1d 100644
--- a/docs/pages/pmd/rules/java/codesize.md
+++ b/docs/pages/pmd/rules/java/codesize.md
@@ -71,6 +71,11 @@ public class Foo {      // This has a Cyclomatic Complexity = 12
 |showClassesComplexity|true|Add class average violations to the report|
 |reportLevel|10|Cyclomatic Complexity reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/CyclomaticComplexity" />
+```
+
 ## ExcessiveClassLength
 
 **Since:** PMD 0.6
@@ -111,6 +116,11 @@ public class Foo {
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/ExcessiveClassLength" />
+```
+
 ## ExcessiveMethodLength
 
 **Since:** PMD 0.6
@@ -142,6 +152,11 @@ public void doSomething() {
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/ExcessiveMethodLength" />
+```
+
 ## ExcessiveParameterList
 
 **Since:** PMD 0.9
@@ -177,6 +192,11 @@ public void addPerson(      // preferred approach
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/ExcessiveParameterList" />
+```
+
 ## ExcessivePublicCount
 
 **Since:** PMD 1.04
@@ -214,6 +234,11 @@ public class Foo {
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/ExcessivePublicCount" />
+```
+
 ## ModifiedCyclomaticComplexity
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -279,6 +304,11 @@ public class Foo {    // This has a Cyclomatic Complexity = 9
 |showClassesComplexity|true|Add class average violations to the report|
 |reportLevel|10|Cyclomatic Complexity reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/ModifiedCyclomaticComplexity" />
+```
+
 ## NcssConstructorCount
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -318,6 +348,11 @@ public class Foo extends Bar {
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/NcssConstructorCount" />
+```
+
 ## NcssCount
 
 **Since:** PMD 6.0
@@ -369,6 +404,11 @@ class Foo {                         // +1, total Ncss = 12
 |methodReportLevel|12|Metric reporting threshold for methods|
 |classReportLevel|250|Metric reporting threshold for classes|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/NcssCount" />
+```
+
 ## NcssMethodCount
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -407,6 +447,11 @@ public class Foo extends Bar {
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/NcssMethodCount" />
+```
+
 ## NcssTypeCount
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -446,6 +491,11 @@ public class Foo extends Bar {
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/NcssTypeCount" />
+```
+
 ## NPathComplexity
 
 **Since:** PMD 3.9
@@ -498,6 +548,11 @@ void bar() {    // this is something more complex than it needs to be,
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/NPathComplexity" />
+```
+
 ## StdCyclomaticComplexity
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -562,6 +617,11 @@ public class Foo {    // This has a Cyclomatic Complexity = 12
 |showClassesComplexity|true|Add class average violations to the report|
 |reportLevel|10|Cyclomatic Complexity reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/StdCyclomaticComplexity" />
+```
+
 ## TooManyFields
 
 **Since:** PMD 3.0
@@ -597,6 +657,11 @@ public class Person {   // this is more manageable
 |----|-------------|-----------|
 |maxfields|15|Max allowable fields|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/TooManyFields" />
+```
+
 ## TooManyMethods
 
 **Since:** PMD 4.2
@@ -627,3 +692,8 @@ complexity and find a way to have more fine grained objects.
 |----|-------------|-----------|
 |maxmethods|10|The method count reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/codesize.xml/TooManyMethods" />
+```
+
diff --git a/docs/pages/pmd/rules/java/comments.md b/docs/pages/pmd/rules/java/comments.md
index fc3a75425d..ac237f75f6 100644
--- a/docs/pages/pmd/rules/java/comments.md
+++ b/docs/pages/pmd/rules/java/comments.md
@@ -31,6 +31,11 @@ A rule for the politically correct... we don't want to offend anyone.
 |caseSensitive|false|Case sensitive|
 |wordsAreRegex|false|Use regular expressions|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/comments.xml/CommentContent" />
+```
+
 ## CommentDefaultAccessModifier
 
 **Since:** PMD 5.4.0
@@ -74,6 +79,11 @@ public class Foo {
 |----|-------------|-----------|
 |regex||Regular expression|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/comments.xml/CommentDefaultAccessModifier" />
+```
+
 ## CommentRequired
 
 **Since:** PMD 5.1
@@ -105,6 +115,11 @@ Denotes whether comments are required (or unwanted) for specific language elemen
 |fieldCommentRequirement|Required|Field comments. Possible values: [Required, Ignored, Unwanted]|
 |headerCommentRequirement|Required|Header comments. Possible values: [Required, Ignored, Unwanted]|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/comments.xml/CommentRequired" />
+```
+
 ## CommentSize
 
 **Since:** PMD 5.0
@@ -143,3 +158,8 @@ Determines whether the dimensions of non-header comments found are within the sp
 |maxLines|6|Maximum lines|
 |maxLineLength|80|Maximum line length|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/comments.xml/CommentSize" />
+```
+
diff --git a/docs/pages/pmd/rules/java/controversial.md b/docs/pages/pmd/rules/java/controversial.md
index e403df606c..ec1ec4e7f6 100644
--- a/docs/pages/pmd/rules/java/controversial.md
+++ b/docs/pages/pmd/rules/java/controversial.md
@@ -37,6 +37,11 @@ public void bar() {
 |allowFor|false|Allow assignment within the conditional expression of a for statement|
 |allowIf|false|Allow assignment within the conditional expression of an if statement|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AssignmentInOperand" />
+```
+
 ## AtLeastOneConstructor
 
 **Since:** PMD 1.04
@@ -66,6 +71,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AtLeastOneConstructor" />
+```
+
 ## AvoidAccessibilityAlteration
 
 **Since:** PMD 4.1
@@ -133,6 +143,11 @@ public class Violation {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AvoidAccessibilityAlteration" />
+```
+
 ## AvoidFinalLocalVariable
 
 **Since:** PMD 4.1
@@ -164,6 +179,11 @@ public class MyClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AvoidFinalLocalVariable" />
+```
+
 ## AvoidLiteralsInIfCondition
 
 **Since:** PMD 4.2.6
@@ -178,7 +198,7 @@ More exceptions can be defined with the property "ignoreMagicNumbers".
 //IfStatement/Expression/*/PrimaryExpression/PrimaryPrefix/Literal
 [not(NullLiteral)]
 [not(BooleanLiteral)]
-[empty(index-of(tokenize($ignoreMagicNumbers, ','), @Image))]
+[empty(index-of(tokenize($ignoreMagicNumbers, '\s*,\s*'), @Image))]
 ```
 
 **Example(s):**
@@ -210,6 +230,11 @@ public void checkRequests() {
 |----|-------------|-----------|
 |ignoreMagicNumbers|-1,0|Comma-separated list of magic numbers, that should be ignored|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AvoidLiteralsInIfCondition" />
+```
+
 ## AvoidPrefixingMethodParameters
 
 **Since:** PMD 5.0
@@ -255,6 +280,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AvoidPrefixingMethodParameters" />
+```
+
 ## AvoidUsingNativeCode
 
 **Since:** PMD 4.1
@@ -287,6 +317,11 @@ public class SomeJNIClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AvoidUsingNativeCode" />
+```
+
 ## AvoidUsingShortType
 
 **Since:** PMD 4.1
@@ -315,6 +350,11 @@ public class UsingShort {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AvoidUsingShortType" />
+```
+
 ## AvoidUsingVolatile
 
 **Since:** PMD 4.1
@@ -338,6 +378,11 @@ public class ThrDeux {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/AvoidUsingVolatile" />
+```
+
 ## CallSuperInConstructor
 
 **Since:** PMD 3.0
@@ -370,6 +415,11 @@ public class Foo extends Bar{
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/CallSuperInConstructor" />
+```
+
 ## DataflowAnomalyAnalysis
 
 **Since:** PMD 3.9
@@ -403,6 +453,11 @@ public void foo() {
 |maxViolations|100|Maximum number of anomalies per class|
 |maxPaths|1000|Maximum number of checked paths per method. A lower value will increase the performance of the rule but may decrease anomalies found.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/DataflowAnomalyAnalysis" />
+```
+
 ## DefaultPackage
 
 **Since:** PMD 3.4
@@ -423,6 +478,11 @@ or MethodDeclaration[@PackagePrivate='true']
 ]
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/DefaultPackage" />
+```
+
 ## DoNotCallGarbageCollectionExplicitly
 
 **Since:** PMD 4.2
@@ -472,6 +532,11 @@ public class GCCall {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/DoNotCallGarbageCollectionExplicitly" />
+```
+
 ## DontImportSun
 
 **Since:** PMD 1.5
@@ -489,6 +554,11 @@ import sun.misc.foo;
 public class Foo {}
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/DontImportSun" />
+```
+
 ## NullAssignment
 
 **Since:** PMD 1.02
@@ -514,6 +584,11 @@ public void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/NullAssignment" />
+```
+
 ## OneDeclarationPerLine
 
 **Since:** PMD 5.0
@@ -548,6 +623,11 @@ String name,
 |----|-------------|-----------|
 |strictMode|false|If true, mark combined declaration even if the declarations are on separate lines.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/OneDeclarationPerLine" />
+```
+
 ## OnlyOneReturn
 
 **Since:** PMD 1.0
@@ -571,6 +651,11 @@ public class OneReturnOnly1 {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/OnlyOneReturn" />
+```
+
 ## SuspiciousOctalEscape
 
 **Since:** PMD 1.5
@@ -599,6 +684,11 @@ public void foo() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/SuspiciousOctalEscape" />
+```
+
 ## UnnecessaryConstructor
 
 **Since:** PMD 1.0
@@ -626,6 +716,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/UnnecessaryConstructor" />
+```
+
 ## UnnecessaryParentheses
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -711,6 +806,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/UnnecessaryParentheses" />
+```
+
 ## UseConcurrentHashMap
 
 **Since:** PMD 4.2.6
@@ -739,6 +839,11 @@ public class ConcurrentApp {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/UseConcurrentHashMap" />
+```
+
 ## UseObjectForClearerAPI
 
 **Since:** PMD 4.2.6
@@ -776,3 +881,8 @@ public class MyClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/controversial.xml/UseObjectForClearerAPI" />
+```
+
diff --git a/docs/pages/pmd/rules/java/coupling.md b/docs/pages/pmd/rules/java/coupling.md
index 40fdfa9e0a..2139ff4786 100644
--- a/docs/pages/pmd/rules/java/coupling.md
+++ b/docs/pages/pmd/rules/java/coupling.md
@@ -45,6 +45,11 @@ public class Foo {
 |----|-------------|-----------|
 |threshold|20|Unique type reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/coupling.xml/CouplingBetweenObjects" />
+```
+
 ## ExcessiveImports
 
 **Since:** PMD 1.04
@@ -76,6 +81,11 @@ public class Foo {
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/coupling.xml/ExcessiveImports" />
+```
+
 ## LawOfDemeter
 
 **Since:** PMD 5.0
@@ -120,6 +130,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/coupling.xml/LawOfDemeter" />
+```
+
 ## LooseCoupling
 
 **Since:** PMD 0.7
@@ -150,6 +165,11 @@ public Set<SomeType> getFoo() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/coupling.xml/LooseCoupling" />
+```
+
 ## LoosePackageCoupling
 
 **Since:** PMD 5.0
@@ -180,3 +200,8 @@ public class Bar {
 |classes|[]|Allowed classes|
 |packages|[]|Restricted packages|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/coupling.xml/LoosePackageCoupling" />
+```
+
diff --git a/docs/pages/pmd/rules/java/design.md b/docs/pages/pmd/rules/java/design.md
index 881af2b79a..a7f58258a6 100644
--- a/docs/pages/pmd/rules/java/design.md
+++ b/docs/pages/pmd/rules/java/design.md
@@ -37,6 +37,11 @@ public abstract class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AbstractClassWithoutAbstractMethod" />
+```
+
 ## AbstractClassWithoutAnyMethod
 
 **Since:** PMD 4.2
@@ -63,6 +68,11 @@ public class abstract Example {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AbstractClassWithoutAnyMethod" />
+```
+
 ## AccessorClassGeneration
 
 **Since:** PMD 1.04
@@ -90,6 +100,11 @@ public class Outer {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AccessorClassGeneration" />
+```
+
 ## AccessorMethodGeneration
 
 **Since:** PMD 5.5.4
@@ -121,6 +136,11 @@ public class OuterClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AccessorMethodGeneration" />
+```
+
 ## AssignmentToNonFinalStatic
 
 **Since:** PMD 2.2
@@ -142,6 +162,11 @@ public class StaticField {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AssignmentToNonFinalStatic" />
+```
+
 ## AvoidDeeplyNestedIfStmts
 
 **Since:** PMD 1.0
@@ -174,6 +199,11 @@ public class Foo {
 |----|-------------|-----------|
 |problemDepth|3|The if statement depth reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AvoidDeeplyNestedIfStmts" />
+```
+
 ## AvoidInstanceofChecksInCatchClause
 
 **Since:** PMD 3.0
@@ -209,6 +239,11 @@ try {  // Prefer this:
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AvoidInstanceofChecksInCatchClause" />
+```
+
 ## AvoidProtectedFieldInFinalClass
 
 **Since:** PMD 2.1
@@ -234,6 +269,11 @@ public final class Bar {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AvoidProtectedFieldInFinalClass" />
+```
+
 ## AvoidProtectedMethodInFinalClassNotExtending
 
 **Since:** PMD 5.1
@@ -259,6 +299,11 @@ public final class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AvoidProtectedMethodInFinalClassNotExtending" />
+```
+
 ## AvoidReassigningParameters
 
 **Since:** PMD 1.0
@@ -279,6 +324,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AvoidReassigningParameters" />
+```
+
 ## AvoidSynchronizedAtMethodLevel
 
 **Since:** PMD 3.0
@@ -318,6 +368,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/AvoidSynchronizedAtMethodLevel" />
+```
+
 ## BadComparison
 
 **Since:** PMD 1.8
@@ -339,6 +394,11 @@ precision when comparing floating point numbers these are likely to cause logic
 boolean x = (y == Double.NaN);
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/BadComparison" />
+```
+
 ## ClassWithOnlyPrivateConstructorsShouldBeFinal
 
 **Since:** PMD 4.1
@@ -364,6 +424,11 @@ public class Foo {  //Should be final
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/ClassWithOnlyPrivateConstructorsShouldBeFinal" />
+```
+
 ## CloseResource
 
 **Since:** PMD 1.2.2
@@ -400,6 +465,11 @@ public class Bar {
 |types|[java.sql.Connection, java.sql.Statement, java.sql.ResultSet]|Affected types|
 |closeTargets|[]|Methods which may close this resource|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/CloseResource" />
+```
+
 ## CompareObjectsWithEquals
 
 **Since:** PMD 3.2
@@ -420,6 +490,11 @@ class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/CompareObjectsWithEquals" />
+```
+
 ## ConfusingTernary
 
 **Since:** PMD 1.9
@@ -449,6 +524,11 @@ boolean bar(int x, int y) {
 |----|-------------|-----------|
 |ignoreElseIf|false|Ignore conditions with an else-if case|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/ConfusingTernary" />
+```
+
 ## ConstantsInInterface
 
 **Since:** PMD 5.5
@@ -493,6 +573,11 @@ public interface YetAnotherConstantInterface {
 |----|-------------|-----------|
 |ignoreIfHasMethods|true|Whether to ignore constants in interfaces if the interface defines any methods|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/ConstantsInInterface" />
+```
+
 ## ConstructorCallsOverridableMethod
 
 **Since:** PMD 1.04
@@ -532,6 +617,11 @@ public class JuniorClass extends SeniorClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/ConstructorCallsOverridableMethod" />
+```
+
 ## DefaultLabelNotLastInSwitchStmt
 
 **Since:** PMD 1.5
@@ -563,6 +653,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/DefaultLabelNotLastInSwitchStmt" />
+```
+
 ## EmptyMethodInAbstractClassShouldBeAbstract
 
 **Since:** PMD 4.1
@@ -604,6 +699,11 @@ public abstract class ShouldBeAbstract {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/EmptyMethodInAbstractClassShouldBeAbstract" />
+```
+
 ## EqualsNull
 
 **Since:** PMD 1.9
@@ -642,6 +742,11 @@ if (x == null) {        // preferred
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/EqualsNull" />
+```
+
 ## FieldDeclarationsShouldBeAtStartOfClass
 
 **Since:** PMD 5.0
@@ -677,6 +782,11 @@ public class HelloWorldBean {
 |ignoreAnonymousClassDeclarations|true|Ignore Field Declarations, that are initialized with anonymous class declarations|
 |ignoreEnumDeclarations|true|Ignore Enum Declarations that precede fields.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/FieldDeclarationsShouldBeAtStartOfClass" />
+```
+
 ## FinalFieldCouldBeStatic
 
 **Since:** PMD 1.1
@@ -701,6 +811,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/FinalFieldCouldBeStatic" />
+```
+
 ## GodClass
 
 **Since:** PMD 5.0
@@ -720,6 +835,11 @@ of Object-Oriented Systems. Springer, Berlin, 1 edition, October 2006. Page 80.
 
 **This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.java.rule.design.GodClassRule](https://github.com/pmd/pmd/blob/master/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/design/GodClassRule.java)
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/GodClass" />
+```
+
 ## IdempotentOperations
 
 **Since:** PMD 2.0
@@ -741,6 +861,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/IdempotentOperations" />
+```
+
 ## ImmutableField
 
 **Since:** PMD 2.0
@@ -766,6 +891,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/ImmutableField" />
+```
+
 ## InstantiationToGetClass
 
 **Since:** PMD 2.0
@@ -793,6 +923,11 @@ Class c = new String().getClass();
 Class c = String.class;
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/InstantiationToGetClass" />
+```
+
 ## LogicInversion
 
 **Since:** PMD 5.0
@@ -822,6 +957,11 @@ public boolean bar(int a, int b) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/LogicInversion" />
+```
+
 ## MissingBreakInSwitch
 
 **Since:** PMD 3.0
@@ -865,6 +1005,11 @@ public void bar(int status) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/MissingBreakInSwitch" />
+```
+
 ## MissingStaticMethodInNonInstantiatableClass
 
 **Since:** PMD 3.0
@@ -913,6 +1058,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/MissingStaticMethodInNonInstantiatableClass" />
+```
+
 ## NonCaseLabelInSwitchStatement
 
 **Since:** PMD 1.5
@@ -944,6 +1094,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/NonCaseLabelInSwitchStatement" />
+```
+
 ## NonStaticInitializer
 
 **Since:** PMD 1.5
@@ -969,6 +1124,11 @@ public class MyClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/NonStaticInitializer" />
+```
+
 ## NonThreadSafeSingleton
 
 **Since:** PMD 3.4
@@ -1010,6 +1170,11 @@ public static Foo getFoo() {
 |checkNonStaticFields|false|Check for non-static fields.  Do not set this to true and checkNonStaticMethods to false.|
 |checkNonStaticMethods|true|Check for non-static methods.  Do not set this to false and checkNonStaticFields to true.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/NonThreadSafeSingleton" />
+```
+
 ## OptimizableToArrayCall
 
 **Since:** PMD 1.8
@@ -1043,6 +1208,11 @@ Foo[] fooArray = foos.toArray(new Foo[0]);
 Foo[] fooArray = foos.toArray(new Foo[foos.size()]);
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/OptimizableToArrayCall" />
+```
+
 ## PositionLiteralsFirstInCaseInsensitiveComparisons
 
 **Since:** PMD 5.1
@@ -1079,6 +1249,11 @@ class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/PositionLiteralsFirstInCaseInsensitiveComparisons" />
+```
+
 ## PositionLiteralsFirstInComparisons
 
 **Since:** PMD 3.3
@@ -1111,6 +1286,11 @@ class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/PositionLiteralsFirstInComparisons" />
+```
+
 ## PreserveStackTrace
 
 **Since:** PMD 3.7
@@ -1149,6 +1329,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/PreserveStackTrace" />
+```
+
 ## ReturnEmptyArrayRatherThanNull
 
 **Since:** PMD 4.2
@@ -1186,6 +1371,11 @@ public class Example {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/ReturnEmptyArrayRatherThanNull" />
+```
+
 ## SimpleDateFormatNeedsLocale
 
 **Since:** PMD 2.0
@@ -1210,6 +1400,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SimpleDateFormatNeedsLocale" />
+```
+
 ## SimplifyBooleanExpressions
 
 **Since:** PMD 1.05
@@ -1235,6 +1430,11 @@ public class Bar {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SimplifyBooleanExpressions" />
+```
+
 ## SimplifyBooleanReturns
 
 **Since:** PMD 0.9
@@ -1262,6 +1462,11 @@ public boolean isBarEqualTo(int x) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SimplifyBooleanReturns" />
+```
+
 ## SimplifyConditional
 
 **Since:** PMD 3.1
@@ -1309,6 +1514,11 @@ class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SimplifyConditional" />
+```
+
 ## SingleMethodSingleton
 
 **Since:** PMD 5.4
@@ -1341,6 +1551,11 @@ public class Singleton {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SingleMethodSingleton" />
+```
+
 ## SingletonClassReturningNewInstance
 
 **Since:** PMD 5.4
@@ -1366,6 +1581,11 @@ class Singleton {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SingletonClassReturningNewInstance" />
+```
+
 ## SingularField
 
 **Since:** PMD 3.1
@@ -1397,6 +1617,11 @@ public class Foo {
 |disallowNotAssignment|false|Disallow violations where the first usage is not an assignment|
 |checkInnerClasses|false|Check inner classes|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SingularField" />
+```
+
 ## SwitchDensity
 
 **Since:** PMD 1.02
@@ -1435,6 +1660,11 @@ public class Foo {
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SwitchDensity" />
+```
+
 ## SwitchStmtsShouldHaveDefault
 
 **Since:** PMD 1.0
@@ -1460,6 +1690,11 @@ public void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/SwitchStmtsShouldHaveDefault" />
+```
+
 ## TooFewBranchesForASwitchStatement
 
 **Since:** PMD 4.2
@@ -1499,6 +1734,11 @@ public class Foo {
 |----|-------------|-----------|
 |minimumNumberCaseForASwitch|3|Minimum number of branches for a switch|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/TooFewBranchesForASwitchStatement" />
+```
+
 ## UncommentedEmptyConstructor
 
 **Since:** PMD 3.4
@@ -1530,6 +1770,11 @@ public Foo() {
 |----|-------------|-----------|
 |ignoreExplicitConstructorInvocation|false|Ignore explicit constructor invocation when deciding whether constructor is empty or not|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UncommentedEmptyConstructor" />
+```
+
 ## UncommentedEmptyMethodBody
 
 **Since:** PMD 3.4
@@ -1552,6 +1797,11 @@ public void doSomething() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UncommentedEmptyMethodBody" />
+```
+
 ## UnnecessaryLocalBeforeReturn
 
 **Since:** PMD 3.3
@@ -1579,6 +1829,11 @@ public class Foo {
 |----|-------------|-----------|
 |statementOrderMatters|true|If set to false this rule no longer requires the variable declaration and return statement to be on consecutive lines. Any variable that is used solely in a return statement will be reported.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UnnecessaryLocalBeforeReturn" />
+```
+
 ## UnsynchronizedStaticDateFormatter
 
 **Since:** PMD 3.6
@@ -1605,6 +1860,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UnsynchronizedStaticDateFormatter" />
+```
+
 ## UseCollectionIsEmpty
 
 **Since:** PMD 3.9
@@ -1636,6 +1896,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UseCollectionIsEmpty" />
+```
+
 ## UseLocaleWithCaseConversions
 
 **Since:** PMD 2.0
@@ -1680,6 +1945,11 @@ class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UseLocaleWithCaseConversions" />
+```
+
 ## UseNotifyAllInsteadOfNotify
 
 **Since:** PMD 3.0
@@ -1712,6 +1982,11 @@ void bar() {
   }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UseNotifyAllInsteadOfNotify" />
+```
+
 ## UseUtilityClass
 
 **Since:** PMD 0.3
@@ -1735,6 +2010,11 @@ public class MaybeAUtility {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UseUtilityClass" />
+```
+
 ## UseVarargs
 
 **Since:** PMD 5.0
@@ -1780,3 +2060,8 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/design.xml/UseVarargs" />
+```
+
diff --git a/docs/pages/pmd/rules/java/empty.md b/docs/pages/pmd/rules/java/empty.md
index 279456ca7f..818df1c477 100644
--- a/docs/pages/pmd/rules/java/empty.md
+++ b/docs/pages/pmd/rules/java/empty.md
@@ -45,6 +45,11 @@ public void doSomething() {
 |allowCommentedBlocks|false|Empty blocks containing comments will be skipped|
 |allowExceptionNameRegex|^$|Empty blocks catching exceptions with names matching this regular expression will be skipped|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyCatchBlock" />
+```
+
 ## EmptyFinallyBlock
 
 **Since:** PMD 0.4
@@ -71,6 +76,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyFinallyBlock" />
+```
+
 ## EmptyIfStmt
 
 **Since:** PMD 0.1
@@ -96,6 +106,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyIfStmt" />
+```
+
 ## EmptyInitializer
 
 **Since:** PMD 5.0
@@ -120,6 +135,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyInitializer" />
+```
+
 ## EmptyStatementBlock
 
 **Since:** PMD 5.0
@@ -147,6 +167,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyStatementBlock" />
+```
+
 ## EmptyStatementNotInLoop
 
 **Since:** PMD 1.5
@@ -181,6 +206,11 @@ public void doit() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyStatementNotInLoop" />
+```
+
 ## EmptyStaticInitializer
 
 **Since:** PMD 1.5
@@ -203,6 +233,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyStaticInitializer" />
+```
+
 ## EmptySwitchStatements
 
 **Since:** PMD 1.0
@@ -227,6 +262,11 @@ public void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptySwitchStatements" />
+```
+
 ## EmptySynchronizedBlock
 
 **Since:** PMD 1.3
@@ -251,6 +291,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptySynchronizedBlock" />
+```
+
 ## EmptyTryBlock
 
 **Since:** PMD 0.4
@@ -276,6 +321,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyTryBlock" />
+```
+
 ## EmptyWhileStmt
 
 **Since:** PMD 0.2
@@ -300,3 +350,8 @@ void bar(int a, int b) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/empty.xml/EmptyWhileStmt" />
+```
+
diff --git a/docs/pages/pmd/rules/java/finalizers.md b/docs/pages/pmd/rules/java/finalizers.md
index f74be2739d..019fe9e051 100644
--- a/docs/pages/pmd/rules/java/finalizers.md
+++ b/docs/pages/pmd/rules/java/finalizers.md
@@ -27,6 +27,11 @@ void foo() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/finalizers.xml/AvoidCallingFinalize" />
+```
+
 ## EmptyFinalizer
 
 **Since:** PMD 1.5
@@ -48,6 +53,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/finalizers.xml/EmptyFinalizer" />
+```
+
 ## FinalizeDoesNotCallSuperFinalize
 
 **Since:** PMD 1.5
@@ -82,6 +92,11 @@ protected void finalize() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/finalizers.xml/FinalizeDoesNotCallSuperFinalize" />
+```
+
 ## FinalizeOnlyCallsSuperFinalize
 
 **Since:** PMD 1.5
@@ -108,6 +123,11 @@ protected void finalize() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/finalizers.xml/FinalizeOnlyCallsSuperFinalize" />
+```
+
 ## FinalizeOverloaded
 
 **Since:** PMD 1.5
@@ -132,6 +152,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/finalizers.xml/FinalizeOverloaded" />
+```
+
 ## FinalizeShouldBeProtected
 
 **Since:** PMD 1.1
@@ -155,3 +180,8 @@ public void finalize() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/finalizers.xml/FinalizeShouldBeProtected" />
+```
+
diff --git a/docs/pages/pmd/rules/java/imports.md b/docs/pages/pmd/rules/java/imports.md
index f927469235..d9fb36d2ef 100644
--- a/docs/pages/pmd/rules/java/imports.md
+++ b/docs/pages/pmd/rules/java/imports.md
@@ -31,6 +31,11 @@ import java.lang.*;         // this is bad
 public class Foo {}
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/imports.xml/DontImportJavaLang" />
+```
+
 ## DuplicateImports
 
 **Since:** PMD 0.5
@@ -49,6 +54,11 @@ import java.lang.*;
 public class Foo {}
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/imports.xml/DuplicateImports" />
+```
+
 ## ImportFromSamePackage
 
 **Since:** PMD 1.02
@@ -70,6 +80,11 @@ import foo.*;       // or this
 public class Bar{}
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/imports.xml/ImportFromSamePackage" />
+```
+
 ## TooManyStaticImports
 
 **Since:** PMD 4.1
@@ -101,6 +116,11 @@ import static Yoko; // Too much !
 |----|-------------|-----------|
 |maximumStaticImports|4|All static imports can be disallowed by setting this to 0|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/imports.xml/TooManyStaticImports" />
+```
+
 ## UnnecessaryFullyQualifiedName
 
 **Since:** PMD 5.0
@@ -123,6 +143,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/imports.xml/UnnecessaryFullyQualifiedName" />
+```
+
 ## UnusedImports
 
 **Since:** PMD 1.0
@@ -141,3 +166,8 @@ import java.io.File;
 public class Foo {}
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/imports.xml/UnusedImports" />
+```
+
diff --git a/docs/pages/pmd/rules/java/j2ee.md b/docs/pages/pmd/rules/java/j2ee.md
index 6e460f5561..b9a697099f 100644
--- a/docs/pages/pmd/rules/java/j2ee.md
+++ b/docs/pages/pmd/rules/java/j2ee.md
@@ -35,6 +35,11 @@ public void foo() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/DoNotCallSystemExit" />
+```
+
 ## DoNotUseThreads
 
 **Since:** PMD 4.1
@@ -64,6 +69,11 @@ public class OtherThread implements Runnable {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/DoNotUseThreads" />
+```
+
 ## LocalHomeNamingConvention
 
 **Since:** PMD 4.0
@@ -94,6 +104,11 @@ public interface MyBeautifulLocalHome extends javax.ejb.EJBLocalHome {} // prope
 public interface MissingProperSuffix extends javax.ejb.EJBLocalHome {}  // non-standard name
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/LocalHomeNamingConvention" />
+```
+
 ## LocalInterfaceSessionNamingConvention
 
 **Since:** PMD 4.0
@@ -124,6 +139,11 @@ public interface MyLocal extends javax.ejb.EJBLocalObject {}                // p
 public interface MissingProperSuffix extends javax.ejb.EJBLocalObject {}    // non-standard name
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/LocalInterfaceSessionNamingConvention" />
+```
+
 ## MDBAndSessionBeanNamingConvention
 
 **Since:** PMD 4.0
@@ -156,6 +176,11 @@ public class SomeBean implements SessionBean{}                  // proper name
 public class MissingTheProperSuffix implements SessionBean {}   // non-standard name
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/MDBAndSessionBeanNamingConvention" />
+```
+
 ## RemoteInterfaceNamingConvention
 
 **Since:** PMD 4.0
@@ -194,6 +219,11 @@ public interface BadSuffixEJB extends javax.ejb.EJBObject {}
 public interface BadSuffixBean extends javax.ejb.EJBObject {}
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/RemoteInterfaceNamingConvention" />
+```
+
 ## RemoteSessionInterfaceNamingConvention
 
 **Since:** PMD 4.0
@@ -224,6 +254,11 @@ public interface MyBeautifulHome extends javax.ejb.EJBHome {}       // proper na
 public interface MissingProperSuffix extends javax.ejb.EJBHome {}   // non-standard name
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/RemoteSessionInterfaceNamingConvention" />
+```
+
 ## StaticEJBFieldShouldBeFinal
 
 **Since:** PMD 4.1
@@ -267,6 +302,11 @@ public class SomeEJB extends EJBObject implements EJBLocalHome {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/StaticEJBFieldShouldBeFinal" />
+```
+
 ## UseProperClassLoader
 
 **Since:** PMD 3.7
@@ -288,3 +328,8 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/j2ee.xml/UseProperClassLoader" />
+```
+
diff --git a/docs/pages/pmd/rules/java/javabeans.md b/docs/pages/pmd/rules/java/javabeans.md
index 1bb0aa7403..8a8a05afd6 100644
--- a/docs/pages/pmd/rules/java/javabeans.md
+++ b/docs/pages/pmd/rules/java/javabeans.md
@@ -43,6 +43,11 @@ private int getMoreFoo(){
 |----|-------------|-----------|
 |prefix||A variable prefix to skip, i.e., m_|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/javabeans.xml/BeanMembersShouldSerialize" />
+```
+
 ## MissingSerialVersionUID
 
 **Since:** PMD 3.0
@@ -75,3 +80,8 @@ public class Foo implements java.io.Serializable {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/javabeans.xml/MissingSerialVersionUID" />
+```
+
diff --git a/docs/pages/pmd/rules/java/junit.md b/docs/pages/pmd/rules/java/junit.md
index 8750d98195..b3d9bc0f40 100644
--- a/docs/pages/pmd/rules/java/junit.md
+++ b/docs/pages/pmd/rules/java/junit.md
@@ -31,6 +31,11 @@ public class Foo extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/JUnitAssertionsShouldIncludeMessage" />
+```
+
 ## JUnitSpelling
 
 **Since:** PMD 1.0
@@ -59,6 +64,11 @@ public class Foo extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/JUnitSpelling" />
+```
+
 ## JUnitStaticSuite
 
 **Since:** PMD 1.0
@@ -85,6 +95,11 @@ public class Foo extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/JUnitStaticSuite" />
+```
+
 ## JUnitTestContainsTooManyAsserts
 
 **Since:** PMD 5.0
@@ -124,6 +139,11 @@ public class MyTestCase extends TestCase {
 |----|-------------|-----------|
 |maximumAsserts|1|Maximum number of Asserts in a test method|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/JUnitTestContainsTooManyAsserts" />
+```
+
 ## JUnitTestsShouldIncludeAssert
 
 **Since:** PMD 2.0
@@ -148,6 +168,11 @@ public class Foo extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/JUnitTestsShouldIncludeAssert" />
+```
+
 ## SimplifyBooleanAssertion
 
 **Since:** PMD 3.6
@@ -187,6 +212,11 @@ public class SimpleTest extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/SimplifyBooleanAssertion" />
+```
+
 ## TestClassWithoutTestCases
 
 **Since:** PMD 3.0
@@ -211,6 +241,11 @@ public class CarTest {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/TestClassWithoutTestCases" />
+```
+
 ## UnnecessaryBooleanAssertion
 
 **Since:** PMD 3.0
@@ -246,6 +281,11 @@ public class SimpleTest extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/UnnecessaryBooleanAssertion" />
+```
+
 ## UseAssertEqualsInsteadOfAssertTrue
 
 **Since:** PMD 3.1
@@ -276,6 +316,11 @@ public class FooTest extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/UseAssertEqualsInsteadOfAssertTrue" />
+```
+
 ## UseAssertNullInsteadOfAssertTrue
 
 **Since:** PMD 3.5
@@ -310,6 +355,11 @@ public class FooTest extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/UseAssertNullInsteadOfAssertTrue" />
+```
+
 ## UseAssertSameInsteadOfAssertTrue
 
 **Since:** PMD 3.1
@@ -342,6 +392,11 @@ public class FooTest extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/UseAssertSameInsteadOfAssertTrue" />
+```
+
 ## UseAssertTrueInsteadOfAssertEquals
 
 **Since:** PMD 5.0
@@ -380,3 +435,8 @@ public class MyTestCase extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/junit.xml/UseAssertTrueInsteadOfAssertEquals" />
+```
+
diff --git a/docs/pages/pmd/rules/java/logging-jakarta-commons.md b/docs/pages/pmd/rules/java/logging-jakarta-commons.md
index 41dcdf068b..6e3473fe19 100644
--- a/docs/pages/pmd/rules/java/logging-jakarta-commons.md
+++ b/docs/pages/pmd/rules/java/logging-jakarta-commons.md
@@ -51,6 +51,11 @@ public class Test {
 |guardsMethods|[]|method use to guard the log statement|
 |logLevels|[]|LogLevels to guard|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-jakarta-commons.xml/GuardDebugLogging" />
+```
+
 ## GuardLogStatement
 
 **Since:** PMD 5.1.0
@@ -77,6 +82,11 @@ otherwise skip the associate String creation and manipulation.
 |guardsMethods|[]|method use to guard the log statement|
 |logLevels|[]|LogLevels to guard|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-jakarta-commons.xml/GuardLogStatement" />
+```
+
 ## ProperLogger
 
 **Since:** PMD 3.3
@@ -116,6 +126,11 @@ public class Foo {
 |----|-------------|-----------|
 |staticLoggerName|LOG|Name of the static Logger variable|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-jakarta-commons.xml/ProperLogger" />
+```
+
 ## UseCorrectExceptionLogging
 
 **Since:** PMD 3.2
@@ -150,3 +165,8 @@ public class Main {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-jakarta-commons.xml/UseCorrectExceptionLogging" />
+```
+
diff --git a/docs/pages/pmd/rules/java/logging-java.md b/docs/pages/pmd/rules/java/logging-java.md
index a5f35147ed..20d350c430 100644
--- a/docs/pages/pmd/rules/java/logging-java.md
+++ b/docs/pages/pmd/rules/java/logging-java.md
@@ -35,6 +35,11 @@ class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-java.xml/AvoidPrintStackTrace" />
+```
+
 ## GuardLogStatementJavaUtil
 
 **Since:** PMD 5.1.0
@@ -63,6 +68,11 @@ if (log.isLoggable(Level.FINE)) {
 |guardsMethods|[]|method use to guard the log statement|
 |logLevels|[]|LogLevels to guard|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-java.xml/GuardLogStatementJavaUtil" />
+```
+
 ## InvalidSlf4jMessageFormat
 
 **Since:** PMD 5.5.0
@@ -81,6 +91,11 @@ LOGGER.error("too many args {}", "arg1", "arg2");
 LOGGER.error("param {}", "arg1", new IllegalStateException("arg")); //The exception is shown separately, so is correct.
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-java.xml/InvalidSlf4jMessageFormat" />
+```
+
 ## LoggerIsNotStaticFinal
 
 **Since:** PMD 2.0
@@ -108,6 +123,11 @@ public class Foo{
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-java.xml/LoggerIsNotStaticFinal" />
+```
+
 ## MoreThanOneLogger
 
 **Since:** PMD 2.0
@@ -129,6 +149,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-java.xml/MoreThanOneLogger" />
+```
+
 ## SystemPrintln
 
 **Since:** PMD 2.1
@@ -160,3 +185,8 @@ class Foo{
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/logging-java.xml/SystemPrintln" />
+```
+
diff --git a/docs/pages/pmd/rules/java/migrating.md b/docs/pages/pmd/rules/java/migrating.md
index 0f8d5ec791..ae8f19c849 100644
--- a/docs/pages/pmd/rules/java/migrating.md
+++ b/docs/pages/pmd/rules/java/migrating.md
@@ -5,7 +5,7 @@ permalink: pmd_rules_java_migrating.html
 folder: pmd/rules/java
 sidebaractiveurl: /pmd_rules_java.html
 editmepath: ../pmd-java/src/main/resources/rulesets/java/migrating.xml
-keywords: Migration, ReplaceVectorWithList, ReplaceHashtableWithMap, ReplaceEnumerationWithIterator, AvoidEnumAsIdentifier, AvoidAssertAsIdentifier, IntegerInstantiation, ByteInstantiation, ShortInstantiation, LongInstantiation, JUnit4TestShouldUseBeforeAnnotation, JUnit4TestShouldUseAfterAnnotation, JUnit4TestShouldUseTestAnnotation, JUnit4SuitesShouldUseSuiteAnnotation, JUnitUseExpected
+keywords: Migration, ReplaceVectorWithList, ReplaceHashtableWithMap, ReplaceEnumerationWithIterator, AvoidEnumAsIdentifier, AvoidAssertAsIdentifier, IntegerInstantiation, ByteInstantiation, ShortInstantiation, LongInstantiation, JUnit4TestShouldUseBeforeAnnotation, JUnit4TestShouldUseAfterAnnotation, JUnit4TestShouldUseTestAnnotation, JUnit4SuitesShouldUseSuiteAnnotation, JUnitUseExpected, ForLoopCanBeForeach
 ---
 ## AvoidAssertAsIdentifier
 
@@ -29,6 +29,11 @@ public class A {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/AvoidAssertAsIdentifier" />
+```
+
 ## AvoidEnumAsIdentifier
 
 **Since:** PMD 3.4
@@ -51,6 +56,11 @@ public class A {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/AvoidEnumAsIdentifier" />
+```
+
 ## ByteInstantiation
 
 **Since:** PMD 4.0
@@ -75,6 +85,47 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/ByteInstantiation" />
+```
+
+## ForLoopCanBeForeach
+
+**Since:** PMD 6.0
+
+**Priority:** Medium (3)
+
+**Minimum Language Version:** Java 1.5
+
+Reports loops that can be safely replaced with the foreach syntax. The rule considers loops over
+            lists, arrays and iterators. A loop is safe to replace if it only uses the index variable to
+            access an element of the list or array, only has one update statement, and loops through *every*
+            element of the list or array left to right.
+
+**This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.java.rule.migrating.ForLoopCanBeForeachRule](https://github.com/pmd/pmd/blob/master/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/migrating/ForLoopCanBeForeachRule.java)
+
+**Example(s):**
+
+``` java
+public class MyClass {
+  void loop(List<String> l) {
+    for (int i = 0; i < l.size(); i++) { // pre Java 1.5
+      System.out.println(l.get(i));
+    }
+
+    for (String s : l) {        // post Java 1.5
+      System.out.println(s);
+    }
+  }
+}
+```
+
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/ForLoopCanBeForeach" />
+```
+
 ## IntegerInstantiation
 
 **Since:** PMD 3.5
@@ -100,6 +151,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/IntegerInstantiation" />
+```
+
 ## JUnit4SuitesShouldUseSuiteAnnotation
 
 **Since:** PMD 4.0
@@ -131,6 +187,11 @@ public class GoodTest {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/JUnit4SuitesShouldUseSuiteAnnotation" />
+```
+
 ## JUnit4TestShouldUseAfterAnnotation
 
 **Since:** PMD 4.0
@@ -161,6 +222,11 @@ public class MyTest2 {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/JUnit4TestShouldUseAfterAnnotation" />
+```
+
 ## JUnit4TestShouldUseBeforeAnnotation
 
 **Since:** PMD 4.0
@@ -191,6 +257,11 @@ public class MyTest2 {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/JUnit4TestShouldUseBeforeAnnotation" />
+```
+
 ## JUnit4TestShouldUseTestAnnotation
 
 **Since:** PMD 4.0
@@ -220,6 +291,11 @@ public class MyTest {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/JUnit4TestShouldUseTestAnnotation" />
+```
+
 ## JUnitUseExpected
 
 **Since:** PMD 4.0
@@ -250,6 +326,11 @@ public class MyTest {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/JUnitUseExpected" />
+```
+
 ## LongInstantiation
 
 **Since:** PMD 4.0
@@ -275,6 +356,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/LongInstantiation" />
+```
+
 ## ReplaceEnumerationWithIterator
 
 **Since:** PMD 3.4
@@ -301,6 +387,11 @@ public class Foo implements Enumeration {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/ReplaceEnumerationWithIterator" />
+```
+
 ## ReplaceHashtableWithMap
 
 **Since:** PMD 3.4
@@ -323,6 +414,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/ReplaceHashtableWithMap" />
+```
+
 ## ReplaceVectorWithList
 
 **Since:** PMD 3.4
@@ -345,6 +441,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/ReplaceVectorWithList" />
+```
+
 ## ShortInstantiation
 
 **Since:** PMD 4.0
@@ -370,3 +471,8 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/migrating.xml/ShortInstantiation" />
+```
+
diff --git a/docs/pages/pmd/rules/java/naming.md b/docs/pages/pmd/rules/java/naming.md
index 6f9dd88cf9..db258a25ae 100644
--- a/docs/pages/pmd/rules/java/naming.md
+++ b/docs/pages/pmd/rules/java/naming.md
@@ -39,6 +39,11 @@ public abstract class Foo { // should be AbstractFoo
 |----|-------------|-----------|
 |strict|true|Also flag classes, that are named Abstract, but are not abstract.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/AbstractNaming" />
+```
+
 ## AvoidDollarSigns
 
 **Since:** PMD 1.5
@@ -56,6 +61,11 @@ public class Fo$o {  // not a recommended name
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/AvoidDollarSigns" />
+```
+
 ## AvoidFieldNameMatchingMethodName
 
 **Since:** PMD 3.0
@@ -79,6 +89,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/AvoidFieldNameMatchingMethodName" />
+```
+
 ## AvoidFieldNameMatchingTypeName
 
 **Since:** PMD 3.0
@@ -98,6 +113,11 @@ public class Foo extends Bar {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/AvoidFieldNameMatchingTypeName" />
+```
+
 ## BooleanGetMethodName
 
 **Since:** PMD 4.0
@@ -132,6 +152,11 @@ public boolean getFoo(boolean bar); // ok, unless checkParameterizedMethods=true
 |----|-------------|-----------|
 |checkParameterizedMethods|false|Check parameterized methods|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/BooleanGetMethodName" />
+```
+
 ## ClassNamingConventions
 
 **Since:** PMD 1.2
@@ -148,6 +173,11 @@ Class names should always begin with an upper case character.
 public class Foo {}
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/ClassNamingConventions" />
+```
+
 ## GenericsNaming
 
 **Since:** PMD 4.2.6
@@ -184,6 +214,11 @@ public interface GenericDao<EF extends BaseModel, K extends Serializable> {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/GenericsNaming" />
+```
+
 ## LongVariable
 
 **Since:** PMD 0.3
@@ -216,6 +251,11 @@ public class Something {
 |----|-------------|-----------|
 |minimum|17|The variable length reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/LongVariable" />
+```
+
 ## MethodNamingConventions
 
 **Since:** PMD 1.2
@@ -241,6 +281,11 @@ public class Foo {
 |----|-------------|-----------|
 |checkNativeMethods|true|Check native methods|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/MethodNamingConventions" />
+```
+
 ## MethodWithSameNameAsEnclosingClass
 
 **Since:** PMD 1.5
@@ -262,6 +307,11 @@ public class MyClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/MethodWithSameNameAsEnclosingClass" />
+```
+
 ## MisleadingVariableName
 
 **Since:** PMD 3.4
@@ -287,6 +337,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/MisleadingVariableName" />
+```
+
 ## NoPackage
 
 **Since:** PMD 3.3
@@ -307,6 +362,11 @@ public class ClassInDefaultPackage {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/NoPackage" />
+```
+
 ## PackageCase
 
 **Since:** PMD 3.3
@@ -328,6 +388,11 @@ public class SomeClass {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/PackageCase" />
+```
+
 ## ShortClassName
 
 **Since:** PMD 5.0
@@ -353,6 +418,11 @@ public class Foo {
 |----|-------------|-----------|
 |minimum|5|Number of characters that are required as a minimum for a class name.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/ShortClassName" />
+```
+
 ## ShortMethodName
 
 **Since:** PMD 0.3
@@ -380,6 +450,11 @@ public class ShortMethod {
 |----|-------------|-----------|
 |minimum|3|Number of characters that are required as a minimum for a method name.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/ShortMethodName" />
+```
+
 ## ShortVariable
 
 **Since:** PMD 0.3
@@ -418,6 +493,11 @@ public class Something {
 |----|-------------|-----------|
 |minimum|3|Number of characters that are required as a minimum for a variable name.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/ShortVariable" />
+```
+
 ## SuspiciousConstantFieldName
 
 **Since:** PMD 2.0
@@ -445,6 +525,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/SuspiciousConstantFieldName" />
+```
+
 ## SuspiciousEqualsMethodName
 
 **Since:** PMD 2.0
@@ -492,6 +577,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/SuspiciousEqualsMethodName" />
+```
+
 ## SuspiciousHashcodeMethodName
 
 **Since:** PMD 1.5
@@ -512,6 +602,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/SuspiciousHashcodeMethodName" />
+```
+
 ## VariableNamingConventions
 
 **Since:** PMD 1.2
@@ -551,3 +646,8 @@ public class Foo {
 |checkLocals|true|Check local variables|
 |checkMembers|true|Check member variables|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/naming.xml/VariableNamingConventions" />
+```
+
diff --git a/docs/pages/pmd/rules/java/optimizations.md b/docs/pages/pmd/rules/java/optimizations.md
index 93ae39f7e0..a2670e8be4 100644
--- a/docs/pages/pmd/rules/java/optimizations.md
+++ b/docs/pages/pmd/rules/java/optimizations.md
@@ -27,6 +27,11 @@ String s = "" + 123;                // inefficient
 String t = Integer.toString(456);   // preferred approach
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/AddEmptyString" />
+```
+
 ## AvoidArrayLoops
 
 **Since:** PMD 3.5
@@ -74,6 +79,11 @@ public class Test {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/AvoidArrayLoops" />
+```
+
 ## AvoidInstantiatingObjectsInLoops
 
 **Since:** PMD 2.2
@@ -96,6 +106,11 @@ public class Something {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/AvoidInstantiatingObjectsInLoops" />
+```
+
 ## LocalVariableCouldBeFinal
 
 **Since:** PMD 2.2
@@ -117,6 +132,11 @@ public class Bar {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/LocalVariableCouldBeFinal" />
+```
+
 ## MethodArgumentCouldBeFinal
 
 **Since:** PMD 2.2
@@ -139,6 +159,11 @@ public void foo2 (final String param) { // better, do stuff with param never ass
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/MethodArgumentCouldBeFinal" />
+```
+
 ## PrematureDeclaration
 
 **Since:** PMD 5.0
@@ -166,6 +191,11 @@ public int getLength(String[] strings) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/PrematureDeclaration" />
+```
+
 ## RedundantFieldInitializer
 
 **Since:** PMD 5.0
@@ -201,6 +231,11 @@ public class C {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/RedundantFieldInitializer" />
+```
+
 ## SimplifyStartsWith
 
 **Since:** PMD 3.1
@@ -238,6 +273,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/SimplifyStartsWith" />
+```
+
 ## UnnecessaryWrapperObjectCreation
 
 **Since:** PMD 3.8
@@ -269,6 +309,11 @@ public int convert(String s) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/UnnecessaryWrapperObjectCreation" />
+```
+
 ## UseArrayListInsteadOfVector
 
 **Since:** PMD 3.0
@@ -294,6 +339,11 @@ public class SimpleTest extends TestCase {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/UseArrayListInsteadOfVector" />
+```
+
 ## UseArraysAsList
 
 **Since:** PMD 3.5
@@ -352,6 +402,11 @@ public class Test {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/UseArraysAsList" />
+```
+
 ## UseStringBufferForStringAppends
 
 **Since:** PMD 3.1
@@ -379,3 +434,8 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/optimizations.xml/UseStringBufferForStringAppends" />
+```
+
diff --git a/docs/pages/pmd/rules/java/strictexception.md b/docs/pages/pmd/rules/java/strictexception.md
index 764695a6f4..bb3ee1265e 100644
--- a/docs/pages/pmd/rules/java/strictexception.md
+++ b/docs/pages/pmd/rules/java/strictexception.md
@@ -43,6 +43,11 @@ public class PrimitiveType {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/AvoidCatchingGenericException" />
+```
+
 ## AvoidCatchingNPE
 
 **Since:** PMD 1.8
@@ -70,6 +75,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/AvoidCatchingNPE" />
+```
+
 ## AvoidCatchingThrowable
 
 **Since:** PMD 1.2
@@ -93,6 +103,11 @@ public void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/AvoidCatchingThrowable" />
+```
+
 ## AvoidLosingExceptionInformation
 
 **Since:** PMD 4.2.6
@@ -129,6 +144,11 @@ public void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/AvoidLosingExceptionInformation" />
+```
+
 ## AvoidRethrowingException
 
 **Since:** PMD 3.8
@@ -156,6 +176,11 @@ public void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/AvoidRethrowingException" />
+```
+
 ## AvoidThrowingNewInstanceOfSameException
 
 **Since:** PMD 4.2.5
@@ -190,6 +215,11 @@ public void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/AvoidThrowingNewInstanceOfSameException" />
+```
+
 ## AvoidThrowingNullPointerException
 
 **Since:** PMD 1.8
@@ -214,6 +244,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/AvoidThrowingNullPointerException" />
+```
+
 ## AvoidThrowingRawExceptionTypes
 
 **Since:** PMD 1.8
@@ -246,6 +281,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/AvoidThrowingRawExceptionTypes" />
+```
+
 ## DoNotExtendJavaLangError
 
 **Since:** PMD 4.0
@@ -265,6 +305,11 @@ Errors are system exceptions. Do not extend them.
 public class Foo extends Error { }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/DoNotExtendJavaLangError" />
+```
+
 ## DoNotThrowExceptionInFinally
 
 **Since:** PMD 4.2
@@ -296,6 +341,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/DoNotThrowExceptionInFinally" />
+```
+
 ## ExceptionAsFlowControl
 
 **Since:** PMD 1.8
@@ -323,6 +373,11 @@ public void bar() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/ExceptionAsFlowControl" />
+```
+
 ## SignatureDeclareThrowsException
 
 **Since:** PMD 1.2
@@ -341,3 +396,8 @@ public void foo() throws Exception {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strictexception.xml/SignatureDeclareThrowsException" />
+```
+
diff --git a/docs/pages/pmd/rules/java/strings.md b/docs/pages/pmd/rules/java/strings.md
index ae7f34c3be..085f2a2108 100644
--- a/docs/pages/pmd/rules/java/strings.md
+++ b/docs/pages/pmd/rules/java/strings.md
@@ -27,6 +27,11 @@ StringBuffer sb = new StringBuffer();
 sb.append('a');     // use this instead
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/AppendCharacterWithChar" />
+```
+
 ## AvoidDuplicateLiterals
 
 **Since:** PMD 1.0
@@ -60,6 +65,11 @@ private void buz(String x) {}
 |minimumLength|3|Minimum string length to check|
 |skipAnnotations|false|Skip literals within annotations|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/AvoidDuplicateLiterals" />
+```
+
 ## AvoidStringBufferField
 
 **Since:** PMD 4.2
@@ -81,6 +91,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/AvoidStringBufferField" />
+```
+
 ## ConsecutiveAppendsShouldReuse
 
 **Since:** PMD 5.1
@@ -106,6 +121,11 @@ StringBuffer buf = new StringBuffer();
 buf.append("Hello").append(foo).append("World"); // good
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/ConsecutiveAppendsShouldReuse" />
+```
+
 ## ConsecutiveLiteralAppends
 
 **Since:** PMD 3.5
@@ -130,6 +150,11 @@ buf.append("Hello World");                          // good
 |----|-------------|-----------|
 |threshold|1|Max consecutive appends|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/ConsecutiveLiteralAppends" />
+```
+
 ## InefficientEmptyStringCheck
 
 **Since:** PMD 3.6
@@ -155,6 +180,11 @@ public void bar(String string) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/InefficientEmptyStringCheck" />
+```
+
 ## InefficientStringBuffering
 
 **Since:** PMD 3.4
@@ -177,6 +207,11 @@ StringBuffer sb = new StringBuffer("tmp = ");
 sb.append(System.getProperty("java.io.tmpdir"));
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/InefficientStringBuffering" />
+```
+
 ## InsufficientStringBufferDeclaration
 
 **Since:** PMD 3.6
@@ -201,6 +236,11 @@ StringBuffer good = new StringBuffer(41);
 good.append("This is a long string, which is pre-sized");
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/InsufficientStringBufferDeclaration" />
+```
+
 ## StringBufferInstantiationWithChar
 
 **Since:** PMD 3.9
@@ -247,6 +287,11 @@ StringBuffer  sb3 = new StringBuffer("c");
 StringBuilder sb4 = new StringBuilder("c");
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/StringBufferInstantiationWithChar" />
+```
+
 ## StringInstantiation
 
 **Since:** PMD 1.0
@@ -263,6 +308,11 @@ Avoid instantiating String objects; this is usually unnecessary since they are i
 private String bar = new String("bar"); // just do a String bar = "bar";
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/StringInstantiation" />
+```
+
 ## StringToString
 
 **Since:** PMD 1.0
@@ -282,6 +332,11 @@ private String baz() {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/StringToString" />
+```
+
 ## UnnecessaryCaseChange
 
 **Since:** PMD 3.3
@@ -300,6 +355,11 @@ boolean answer1 = buz.toUpperCase().equals("baz");              // should be buz
 boolean answer2 = buz.toUpperCase().equalsIgnoreCase("baz");    // another unnecessary toUpperCase()
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/UnnecessaryCaseChange" />
+```
+
 ## UseEqualsToCompareStrings
 
 **Since:** PMD 4.1
@@ -327,6 +387,11 @@ public boolean test(String s) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/UseEqualsToCompareStrings" />
+```
+
 ## UseIndexOfChar
 
 **Since:** PMD 3.5
@@ -347,6 +412,11 @@ if (s.indexOf("d") {}
 if (s.indexOf('d') {}
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/UseIndexOfChar" />
+```
+
 ## UselessStringValueOf
 
 **Since:** PMD 3.8
@@ -368,6 +438,11 @@ public String convert(int i) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/UselessStringValueOf" />
+```
+
 ## UseStringBufferLength
 
 **Since:** PMD 3.4
@@ -389,3 +464,8 @@ if (sb.toString().equals("")) {}        // inefficient
 if (sb.length() == 0) {}                // preferred
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/strings.xml/UseStringBufferLength" />
+```
+
diff --git a/docs/pages/pmd/rules/java/sunsecure.md b/docs/pages/pmd/rules/java/sunsecure.md
index bf7d7f2bd7..f373281c62 100644
--- a/docs/pages/pmd/rules/java/sunsecure.md
+++ b/docs/pages/pmd/rules/java/sunsecure.md
@@ -30,6 +30,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sunsecure.xml/ArrayIsStoredDirectly" />
+```
+
 ## MethodReturnsInternalArray
 
 **Since:** PMD 2.2
@@ -53,3 +58,8 @@ public class SecureSystem {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sunsecure.xml/MethodReturnsInternalArray" />
+```
+
diff --git a/docs/pages/pmd/rules/java/unnecessary.md b/docs/pages/pmd/rules/java/unnecessary.md
index e41f7ba984..42f194a7ef 100644
--- a/docs/pages/pmd/rules/java/unnecessary.md
+++ b/docs/pages/pmd/rules/java/unnecessary.md
@@ -28,6 +28,11 @@ public String convert(int x) {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UnnecessaryConversionTemporary" />
+```
+
 ## UnnecessaryFinalModifier
 
 **Since:** PMD 3.0
@@ -59,6 +64,11 @@ public final class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UnnecessaryFinalModifier" />
+```
+
 ## UnnecessaryModifier
 
 **Since:** PMD 1.02
@@ -96,6 +106,11 @@ public class Bar {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UnnecessaryModifier" />
+```
+
 ## UnnecessaryReturn
 
 **Since:** PMD 1.3
@@ -117,6 +132,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UnnecessaryReturn" />
+```
+
 ## UnusedNullCheckInEquals
 
 **Since:** PMD 3.5
@@ -175,6 +195,11 @@ public class Test {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UnusedNullCheckInEquals" />
+```
+
 ## UselessOperationOnImmutable
 
 **Since:** PMD 3.5
@@ -203,6 +228,11 @@ class Test {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UselessOperationOnImmutable" />
+```
+
 ## UselessOverridingMethod
 
 **Since:** PMD 3.3
@@ -236,6 +266,11 @@ public Long getId() {
 |----|-------------|-----------|
 |ignoreAnnotations|false|Ignore annotations|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UselessOverridingMethod" />
+```
+
 ## UselessParentheses
 
 **Since:** PMD 5.0
@@ -315,6 +350,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UselessParentheses" />
+```
+
 ## UselessQualifiedThis
 
 **Since:** PMD 5.4.0
@@ -361,3 +401,8 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unnecessary.xml/UselessQualifiedThis" />
+```
+
diff --git a/docs/pages/pmd/rules/java/unusedcode.md b/docs/pages/pmd/rules/java/unusedcode.md
index 0d8305a890..bb87f2152b 100644
--- a/docs/pages/pmd/rules/java/unusedcode.md
+++ b/docs/pages/pmd/rules/java/unusedcode.md
@@ -33,6 +33,11 @@ public class Foo {
 |----|-------------|-----------|
 |checkAll|false|Check all methods, including non-private ones|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unusedcode.xml/UnusedFormalParameter" />
+```
+
 ## UnusedLocalVariable
 
 **Since:** PMD 0.1
@@ -53,6 +58,11 @@ public class Foo {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unusedcode.xml/UnusedLocalVariable" />
+```
+
 ## UnusedPrivateField
 
 **Since:** PMD 0.1
@@ -76,6 +86,11 @@ public class Something {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unusedcode.xml/UnusedPrivateField" />
+```
+
 ## UnusedPrivateMethod
 
 **Since:** PMD 0.7
@@ -94,3 +109,8 @@ public class Something {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/unusedcode.xml/UnusedPrivateMethod" />
+```
+
diff --git a/docs/pages/pmd/rules/jsp/basic-jsf.md b/docs/pages/pmd/rules/jsp/basic-jsf.md
index 4fee12d783..d8104dca9d 100644
--- a/docs/pages/pmd/rules/jsp/basic-jsf.md
+++ b/docs/pages/pmd/rules/jsp/basic-jsf.md
@@ -33,3 +33,8 @@ Do not nest JSF component custom actions inside a custom action that iterates ov
 </html>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic-jsf.xml/DontNestJsfInJstlIteration" />
+```
+
diff --git a/docs/pages/pmd/rules/jsp/basic.md b/docs/pages/pmd/rules/jsp/basic.md
index 93f30ef763..f1704787d9 100644
--- a/docs/pages/pmd/rules/jsp/basic.md
+++ b/docs/pages/pmd/rules/jsp/basic.md
@@ -23,6 +23,11 @@ Avoid duplicate import statements inside JSP's.
 <%@ page import=\"com.foo.MyClass,com.foo.MyClass\"%><html><body><b><img src=\"<%=Some.get()%>/foo\">xx</img>text</b></body></html>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/DuplicateJspImports" />
+```
+
 ## IframeMissingSrcAttribute
 
 **Since:** PMD 3.6
@@ -48,6 +53,11 @@ through SSL. See http://support.microsoft.com/default.aspx?scid=kb;EN-US;Q261188
 </BODY> </HTML>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/IframeMissingSrcAttribute" />
+```
+
 ## JspEncoding
 
 **Since:** PMD 4.0
@@ -76,6 +86,11 @@ Most browsers should be able to interpret the following headers:
 <meta http-equiv="Content-Type"  content="text/html; charset=UTF-8" />
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/JspEncoding" />
+```
+
 ## NoClassAttribute
 
 **Since:** PMD 3.6
@@ -96,6 +111,11 @@ Do not use an attribute called 'class'. Use "styleclass" for CSS styles.
 </BODY> </HTML>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/NoClassAttribute" />
+```
+
 ## NoHtmlComments
 
 **Since:** PMD 3.6
@@ -122,6 +142,11 @@ little other purpose. Consider switching to JSP comments.
 </BODY> </HTML>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/NoHtmlComments" />
+```
+
 ## NoInlineScript
 
 **Since:** PMD 4.0
@@ -145,6 +170,11 @@ Most browsers should be able to interpret the following headers:
 <meta http-equiv="Content-Type"  content="text/html; charset=UTF-8" />
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/NoInlineScript" />
+```
+
 ## NoInlineStyleInformation
 
 **Since:** PMD 3.6
@@ -162,6 +192,11 @@ tags, or attributes like "align='center'".
 <html><body><p align='center'><b>text</b></p></body></html>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/NoInlineStyleInformation" />
+```
+
 ## NoJspForward
 
 **Since:** PMD 3.6
@@ -180,6 +215,11 @@ Do not do a forward from within a JSP file.
 <jsp:forward page='UnderConstruction.jsp'/>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/NoJspForward" />
+```
+
 ## NoLongScripts
 
 **Since:** PMD 3.6
@@ -218,6 +258,11 @@ onload=calcDays;
 </HTML>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/NoLongScripts" />
+```
+
 ## NoScriptlets
 
 **Since:** PMD 3.6
@@ -247,6 +292,11 @@ response.setHeader("Pragma", "No-cache");
 </HTML>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/NoScriptlets" />
+```
+
 ## NoUnsanitizedJSPExpression
 
 **Since:** PMD 5.1.4
@@ -268,3 +318,8 @@ ${fn:escapeXml(expression)}      <!-- instead, escape it -->
 <c:out value="${expression}" />  <!-- or use c:out -->
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/jsp/basic.xml/NoUnsanitizedJSPExpression" />
+```
+
diff --git a/docs/pages/pmd/rules/plsql/TomKytesDespair.md b/docs/pages/pmd/rules/plsql/TomKytesDespair.md
index 1731f87847..d6f2bbdf6b 100644
--- a/docs/pages/pmd/rules/plsql/TomKytesDespair.md
+++ b/docs/pages/pmd/rules/plsql/TomKytesDespair.md
@@ -64,3 +64,8 @@ END update_planned_hrs;
 /
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/TomKytesDespair.xml/TomKytesDespair" />
+```
+
diff --git a/docs/pages/pmd/rules/plsql/codesize.md b/docs/pages/pmd/rules/plsql/codesize.md
index a31cea2cf3..60c525d2e5 100644
--- a/docs/pages/pmd/rules/plsql/codesize.md
+++ b/docs/pages/pmd/rules/plsql/codesize.md
@@ -147,6 +147,11 @@ END;
 |showClassesComplexity|true|Add class average violations to the report|
 |reportLevel|10|Cyclomatic Complexity reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/CyclomaticComplexity" />
+```
+
 ## ExcessiveMethodLength
 
 **Since:** PMD 5.1
@@ -179,6 +184,11 @@ END;
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/ExcessiveMethodLength" />
+```
+
 ## ExcessiveObjectLength
 
 **Since:** PMD 5.1
@@ -221,6 +231,11 @@ END;
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/ExcessiveObjectLength" />
+```
+
 ## ExcessivePackageBodyLength
 
 **Since:** PMD 5.1
@@ -263,6 +278,11 @@ END;
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/ExcessivePackageBodyLength" />
+```
+
 ## ExcessivePackageSpecificationLength
 
 **Since:** PMD 5.1
@@ -298,6 +318,11 @@ END;
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/ExcessivePackageSpecificationLength" />
+```
+
 ## ExcessiveParameterList
 
 **Since:** PMD 5.1
@@ -335,6 +360,11 @@ END;
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/ExcessiveParameterList" />
+```
+
 ## ExcessiveTypeLength
 
 **Since:** PMD 5.1
@@ -377,6 +407,11 @@ END;
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/ExcessiveTypeLength" />
+```
+
 ## NcssMethodCount
 
 **Since:** PMD 5.1
@@ -408,6 +443,11 @@ END;
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/NcssMethodCount" />
+```
+
 ## NcssObjectCount
 
 **Since:** PMD 5.1
@@ -441,6 +481,11 @@ CREATE OR REPLACE PACKAGE pkg_
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/NcssObjectCount" />
+```
+
 ## NPathComplexity
 
 **Since:** PMD 5.1
@@ -498,6 +543,11 @@ END;
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/NPathComplexity" />
+```
+
 ## TooManyFields
 
 **Since:** PMD 5.1
@@ -527,6 +577,11 @@ END pkg_too_many_fields;
 |----|-------------|-----------|
 |maxfields|15|Max allowable fields|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/TooManyFields" />
+```
+
 ## TooManyMethods
 
 **Since:** PMD 5.1
@@ -576,3 +631,8 @@ have more fine grained objects.
 |----|-------------|-----------|
 |maxmethods|1|The method count reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/codesize.xml/TooManyMethods" />
+```
+
diff --git a/docs/pages/pmd/rules/plsql/dates.md b/docs/pages/pmd/rules/plsql/dates.md
index 1936db49a1..63e581f4ae 100644
--- a/docs/pages/pmd/rules/plsql/dates.md
+++ b/docs/pages/pmd/rules/plsql/dates.md
@@ -43,6 +43,11 @@ END date_utilities;
 /
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/dates.xml/TO_DATE_TO_CHAR" />
+```
+
 ## TO_DATEWithoutDateFormat
 
 **Since:** PMD 5.1
@@ -86,6 +91,11 @@ END date_utilities;
 /
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/dates.xml/TO_DATEWithoutDateFormat" />
+```
+
 ## TO_TIMESTAMPWithoutDateFormat
 
 **Since:** PMD 5.1
@@ -129,3 +139,8 @@ END date_utilities;
 /
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/dates.xml/TO_TIMESTAMPWithoutDateFormat" />
+```
+
diff --git a/docs/pages/pmd/rules/plsql/strictsyntax.md b/docs/pages/pmd/rules/plsql/strictsyntax.md
index 180694ddf6..6e33ee8efa 100644
--- a/docs/pages/pmd/rules/plsql/strictsyntax.md
+++ b/docs/pages/pmd/rules/plsql/strictsyntax.md
@@ -42,3 +42,8 @@ end inline_pragma_error;
 /
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/plsql/strictsyntax.xml/MisplacedPragma" />
+```
+
diff --git a/docs/pages/pmd/rules/pom/basic.md b/docs/pages/pmd/rules/pom/basic.md
index 1ba49c5ab0..c00904d2de 100644
--- a/docs/pages/pmd/rules/pom/basic.md
+++ b/docs/pages/pmd/rules/pom/basic.md
@@ -39,6 +39,11 @@ dependency management section, it will not also uses the dependency.
 </project>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/pom/basic.xml/InvalidDependencyTypes" />
+```
+
 ## ProjectVersionAsDependencyVersion
 
 **Since:** PMD 5.4
@@ -64,3 +69,8 @@ By far the most common problem is the use of 6.0.0-SNAPSHOT in a BOM or parent P
 </project>
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/pom/basic.xml/ProjectVersionAsDependencyVersion" />
+```
+
diff --git a/docs/pages/pmd/rules/vf/security.md b/docs/pages/pmd/rules/vf/security.md
index 946a2501ef..1ed3b4febd 100644
--- a/docs/pages/pmd/rules/vf/security.md
+++ b/docs/pages/pmd/rules/vf/security.md
@@ -23,6 +23,11 @@ Avoid calling VF action upon page load as the action becomes vulnerable to CSRF.
 <apex:page controller="AcRestActionsController" action="{!csrfInitMethod}" >
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vf/security.xml/VfCsrf" />
+```
+
 ## VfUnescapeEl
 
 **Since:** PMD 5.6.0
@@ -39,3 +44,8 @@ Avoid unescaped user controlled content in EL as it results in XSS.
 <apex:outputText value="Potential XSS is {! here }" escape="false" />
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vf/security.xml/VfUnescapeEl" />
+```
+
diff --git a/docs/pages/pmd/rules/vm/basic.md b/docs/pages/pmd/rules/vm/basic.md
index a44ef90fd5..2cdf621585 100644
--- a/docs/pages/pmd/rules/vm/basic.md
+++ b/docs/pages/pmd/rules/vm/basic.md
@@ -23,6 +23,11 @@ Avoid creating deeply nested if-then statements since they are harder to read an
 |----|-------------|-----------|
 |problemDepth|3|The if statement depth reporting threshold|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/AvoidDeeplyNestedIfStmts" />
+```
+
 ## AvoidReassigningParameters
 
 **Since:** PMD 5.1
@@ -33,6 +38,11 @@ Reassigning values to incoming parameters is not recommended.  Use temporary loc
 
 **This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.vm.rule.basic.AvoidReassigningParametersRule](https://github.com/pmd/pmd/blob/master/pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/rule/basic/AvoidReassigningParametersRule.java)
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/AvoidReassigningParameters" />
+```
+
 ## CollapsibleIfStatements
 
 **Since:** PMD 5.1
@@ -43,6 +53,11 @@ Sometimes two consecutive 'if' statements can be consolidated by separating thei
 
 **This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.vm.rule.basic.CollapsibleIfStatementsRule](https://github.com/pmd/pmd/blob/master/pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/rule/basic/CollapsibleIfStatementsRule.java)
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/CollapsibleIfStatements" />
+```
+
 ## EmptyForeachStmt
 
 **Since:** PMD 5.1
@@ -53,6 +68,11 @@ Empty foreach statements should be deleted.
 
 **This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.vm.rule.basic.EmptyForeachStmtRule](https://github.com/pmd/pmd/blob/master/pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/rule/basic/EmptyForeachStmtRule.java)
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/EmptyForeachStmt" />
+```
+
 ## EmptyIfStmt
 
 **Since:** PMD 5.1
@@ -63,6 +83,11 @@ Empty if statements should be deleted.
 
 **This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.vm.rule.basic.EmptyIfStmtRule](https://github.com/pmd/pmd/blob/master/pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/rule/basic/EmptyIfStmtRule.java)
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/EmptyIfStmt" />
+```
+
 ## ExcessiveTemplateLength
 
 **Since:** PMD 5.1
@@ -81,6 +106,11 @@ The template is too long. It should be broken up into smaller pieces.
 |minimum||Minimum reporting threshold|
 |sigma||Sigma value|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/ExcessiveTemplateLength" />
+```
+
 ## NoInlineJavaScript
 
 **Since:** PMD 5.1
@@ -91,6 +121,11 @@ Avoid inline JavaScript. Import .js files instead.
 
 **This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.vm.rule.basic.NoInlineJavaScriptRule](https://github.com/pmd/pmd/blob/master/pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/rule/basic/NoInlineJavaScriptRule.java)
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/NoInlineJavaScript" />
+```
+
 ## NoInlineStyles
 
 **Since:** PMD 5.1
@@ -103,6 +138,11 @@ Avoid inline styles. Use css classes instead.
 //Text[matches(@literal, "<[^>]+\s[sS][tT][yY][lL][eE]\s*=")]
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/NoInlineStyles" />
+```
+
 ## UnusedMacroParameter
 
 **Since:** PMD 5.1
@@ -113,3 +153,8 @@ Avoid unused macro parameters. They should be deleted.
 
 **This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.vm.rule.basic.UnusedMacroParameterRule](https://github.com/pmd/pmd/blob/master/pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/rule/basic/UnusedMacroParameterRule.java)
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/vm/basic.xml/UnusedMacroParameter" />
+```
+
diff --git a/docs/pages/pmd/rules/xml/basic.md b/docs/pages/pmd/rules/xml/basic.md
index a385e12849..f153767559 100644
--- a/docs/pages/pmd/rules/xml/basic.md
+++ b/docs/pages/pmd/rules/xml/basic.md
@@ -25,3 +25,8 @@ An XML CDATA section begins with a <!CDATA[ marker, which has only one [, and en
 An extra [ looks like &lt;!CDATA[[]]&gt;, and an extra ] looks like &lt;!CDATA[]]]&gt;.
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/xml/basic.xml/MistypedCDATASection" />
+```
+
diff --git a/docs/pages/pmd/rules/xsl/xpath.md b/docs/pages/pmd/rules/xsl/xpath.md
index 8c6ab9544a..eda6752a0e 100644
--- a/docs/pages/pmd/rules/xsl/xpath.md
+++ b/docs/pages/pmd/rules/xsl/xpath.md
@@ -47,6 +47,11 @@ cutting through 100% of the document.
 |----|-------------|-----------|
 |checkSelfDescendantAbreviation|false|descendant::self abreviation, '//', will also trigger this rule.|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/xsl/xpath.xml/AvoidAxisNavigation" />
+```
+
 ## UseConcatOnce
 
 **Since:** PMD 5.0
@@ -67,3 +72,8 @@ The XPath concat() functions accepts as many arguments as required so you can ha
 <xsl:variable name="var" select="concat("Welcome","to you ",$name))">
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/xsl/xpath.xml/UseConcatOnce" />
+```
+
diff --git a/docs/pages/pmd/userdocs/best_practices.md b/docs/pages/pmd/userdocs/best_practices.md
index 91d572688a..6e59d9391a 100644
--- a/docs/pages/pmd/userdocs/best_practices.md
+++ b/docs/pages/pmd/userdocs/best_practices.md
@@ -1,8 +1,7 @@
 ---
 title: Best Practices
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_best_practices.html
-folder: pmd/userdocs
+author: Tom Copeland <tom@infoether.com>
 ---
 
 ## Choose the rules that are right for you
@@ -11,10 +10,10 @@ Running every ruleset will result in a huge number of rule violations, most of w
 Having to sort through a thousand line report to find the few you're really interested in takes
 all the fun out of things.
 
-Instead, start with some of the obvious rulesets - just run [unusedcode](/pmd_rules_java.html#Unused_Code) and fix any unused locals and fields.
-Then, run [empty](/pmd_rules_java.html#Empty_Code) and fix all the empty `if` statements and such-like. After that, take [unnecessary](/pmd_rules_java.html#Unnecessary)
-and fix these violations. Then, run [basic](/pmd_rules_java.html#Basic) and fix the remaining violations.
-Then peruse the [design](/pmd_rules_java.html#Design) and [controversial](/pmd_rules_java.html#Controversial) rulesets and use the ones
+Instead, start with some of the obvious rulesets - just run [unusedcode](/pmd_rules_java.html#unused-code) and fix any unused locals and fields.
+Then, run [empty](/pmd_rules_java.html#empty-code) and fix all the empty `if` statements and such-like. After that, take [unnecessary](/pmd_rules_java.html#unnecessary)
+and fix these violations. Then, run [basic](/pmd_rules_java.html#basic) and fix the remaining violations.
+Then peruse the [design](/pmd_rules_java.html#design) and [controversial](/pmd_rules_java.html#controversial) rulesets and use the ones
 you like [via a custom ruleset](/pmd_userdocs_understanding_rulesets.html).
 
 ## PMD rules are not set in stone
diff --git a/docs/pages/pmd/userdocs/ci.md b/docs/pages/pmd/userdocs/ci.md
index 900ee29edc..c84cff056a 100644
--- a/docs/pages/pmd/userdocs/ci.md
+++ b/docs/pages/pmd/userdocs/ci.md
@@ -1,8 +1,7 @@
 ---
 title: Continuous Integrations plugins
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_ci.html
-folder: pmd/userdocs
+author: Romain PELISSE <belaran@gmail.com>
 ---
 
 ## Introduction
diff --git a/docs/pages/pmd/userdocs/cpd.md b/docs/pages/pmd/userdocs/cpd.md
index 53668d394b..e75b3e4272 100644
--- a/docs/pages/pmd/userdocs/cpd.md
+++ b/docs/pages/pmd/userdocs/cpd.md
@@ -1,9 +1,8 @@
 ---
 title: Finding duplicated code
 summary: Or how to find copied and pasted code
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_cpd.html
-folder: pmd/userdocs
+author: Tom Copeland <tom@infoether.com>
 ---
 
 ## Overview
diff --git a/docs/pages/pmd/userdocs/credits.md b/docs/pages/pmd/userdocs/credits.md
index a3b79b056f..d53b833e7e 100644
--- a/docs/pages/pmd/userdocs/credits.md
+++ b/docs/pages/pmd/userdocs/credits.md
@@ -1,8 +1,7 @@
 ---
 title: Credits
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_credits.html
-folder: pmd/userdocs
+author: Tom Copeland <tom@infoether.org>
 ---
 
 ## Committers
diff --git a/docs/pages/pmd/userdocs/getting_started.md b/docs/pages/pmd/userdocs/getting_started.md
index a291ccc68f..21398decad 100644
--- a/docs/pages/pmd/userdocs/getting_started.md
+++ b/docs/pages/pmd/userdocs/getting_started.md
@@ -1,8 +1,7 @@
 ---
 title: Getting Started
 permalink: pmd_userdocs_getting_started.html
-sidebar: pmd_sidebar
-folder: pmd/userdocs
+author: Tom Copeland <tom@infoether.com>, Xavier Le Vourch <xlv@users.sourceforge.net>
 ---
 
 ## How to install PMD and CPD
diff --git a/docs/pages/pmd/userdocs/meaning.md b/docs/pages/pmd/userdocs/meaning.md
index ce73824c2e..b2bd1bc71f 100644
--- a/docs/pages/pmd/userdocs/meaning.md
+++ b/docs/pages/pmd/userdocs/meaning.md
@@ -1,8 +1,7 @@
 ---
 title: What does 'PMD' mean?
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_meaning.html
-folder: pmd/userdocs
+author: David Dixon-Peugh
 ---
 
 We've been trying to find the meaning of the letters PMD - because frankly, we don't
diff --git a/docs/pages/pmd/userdocs/news.md b/docs/pages/pmd/userdocs/news.md
index 6bebfe38bb..937c1bbcf4 100644
--- a/docs/pages/pmd/userdocs/news.md
+++ b/docs/pages/pmd/userdocs/news.md
@@ -1,8 +1,7 @@
 ---
 title: PMD in the press
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_news.html
-folder: pmd/userdocs
+author: Tom Copeland <tom@infoether.org>
 ---
 
 ## Sites/Articles about PMD
diff --git a/docs/pages/pmd/userdocs/products.md b/docs/pages/pmd/userdocs/products.md
index 702b10adc0..ffba09cb9f 100644
--- a/docs/pages/pmd/userdocs/products.md
+++ b/docs/pages/pmd/userdocs/products.md
@@ -1,8 +1,7 @@
 ---
 title: Products/books related to PMD
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_products.html
-folder: pmd/userdocs
+author: Tom Copeland <tom@infoether.org>
 ---
 
 ## Open source products
diff --git a/docs/pages/pmd/userdocs/similarprojects.md b/docs/pages/pmd/userdocs/similarprojects.md
index 6553bf2eb0..60f574aaf3 100644
--- a/docs/pages/pmd/userdocs/similarprojects.md
+++ b/docs/pages/pmd/userdocs/similarprojects.md
@@ -1,8 +1,7 @@
 ---
 title: Similar projects
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_similarprojects.html
-folder: pmd/userdocs
+author: Tom Copeland <tom@infoether.org>, David Dixon-Peugh <ddp@apache.org>
 ---
 
 ## Similar to PMD
diff --git a/docs/pages/pmd/userdocs/suppressing.md b/docs/pages/pmd/userdocs/suppressing.md
index b1c8f5c1be..d9de8589c7 100644
--- a/docs/pages/pmd/userdocs/suppressing.md
+++ b/docs/pages/pmd/userdocs/suppressing.md
@@ -1,8 +1,7 @@
 ---
 title: Suppressing warnings
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_suppressing.html
-folder: pmd/userdocs
+author: Tom Copeland <tom@infoether.com>
 ---
 
 PMD provides several methods by which Rule violations can be suppressed.
diff --git a/docs/pages/pmd/userdocs/tools.md b/docs/pages/pmd/userdocs/tools.md
index f4b0ff7381..c76c5be90b 100644
--- a/docs/pages/pmd/userdocs/tools.md
+++ b/docs/pages/pmd/userdocs/tools.md
@@ -1,13 +1,10 @@
 ---
 title: Tools / Integrations
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_tools.html
-folder: pmd/userdocs
+author: David Dixon-Peugh <dpeugh@users.sourceforge.net>
 ---
 
 * IDE plugins
-* build tool plugins
-    *   [Ant Task Usage](/pmd_userdocs_ant.html)
 * [Continuous Integrations plugins](/pmd_userdocs_ci.html)
 * GUIs
 
@@ -123,20 +120,6 @@ folder: pmd/userdocs
         <td>Jiger Patel, Dale Anson</td>
     </tr>
 
-    <tr>
-        <td><a href="#maven">Maven</a></td>
-        <td></td>
-        <td>N/A</td>
-        <td>N/A</td>
-    </tr>
-
-    <tr>
-        <td><a href="#maven-2-and-3">Maven 2 and 3</a></td>
-        <td></td>
-        <td>N/A</td>
-        <td><a href="http://maven.apache.org/plugins/maven-pmd-plugin/">apache.org / maven</a></td>
-    </tr>
-
     <tr>
         <td><a href="#netbeans">NetBeans</a></td>
         <td><a href="http://kenai.com/projects/sqe/">SQE</a></td>
@@ -385,145 +368,6 @@ Also, you can change the plugin to prompt you for a directory to check by going
 selecting the "Ask for Directory" checkbox.
 
 
-### Maven
-
-This section is about the maven 1 PMD plugin. The maven 2 PMD plugin page is available
-[below](#Maven_2_and_3).
-
-#### Running the pmd plugin
-
-##### report
-
-To include the Maven report in the project reports section add the following line under
-the reports element in your project.xml:
-
-    <report>maven-pmd-plugin</report>
-
-This will add an entry to the 'project reports' section with the PMD report.
-
-##### manual
-
-To run PMD on a Maven project without adding it as a report, simply run
-
-    maven pmd xdoc
-
-The PMD plugin writes the report in XML which will then be formatted into more readable HTML.
-
-#### Customization
-
-##### Changing rulesets
-
-To specify a set of official, built-in rulesets to be used set them in the property
-<em>maven.pmd.rulesets</em>.  You can include this setting in your project.properties file.
-
-A clean strategy for customizing which rules to use for a project is to write a ruleset file.
-In this file you can define which rules to use, add custom rules, and
-customizing which rules to include/exclude from official rulesets. More information on
-writing a ruleset can be found [here](/pmd_userdocs_understanding_rulesets.html).
-
-Add to the root of your Maven project a pmd.xml file which contains the ruleset mentioned in
-the previous paragraph. Add the following property to your project now:
-
-    maven.pmd.rulesetfiles = ${basedir}/pmd.xml
-
-#### Reference
-
-See the PMD plugin project page here:
-<http://maven.apache.org/maven-1.x/plugins/pmd/>
-
-
-### Maven 2 and 3
-
-#### Running the pmd plugin
-
-##### report
-
-To include the mvn report in the project reports section add the following lines under
-the reports element in your pom.xml:
-
-
-    <project>
-        ...
-        <reporting>
-            <plugins>
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-pmd-plugin</artifactId>
-                </plugin>
-            </plugins>
-        </reporting>
-        ...
-    </project>
-
-This will add an entry to the 'project reports' section with the PMD report.
-
-
-##### manual
-
-To run PMD on a Maven project without adding it as a report, simply run
-
-    mvn pmd:pmd
-
-The PMD plugin writes the report in XML which will then be formatted into more readable HTML.
-
-#### Customization
-
-##### Changing rulesets
-
-To specify a ruleset, simply edit the previous configuration:
-
-
-    <reporting>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-pmd-plugin</artifactId>
-                <configuration>
-                    <rulesets>
-                        <ruleset>/rulesets/java/braces.xml</ruleset>
-                        <ruleset>/rulesets/java/naming.xml</ruleset>
-                        <ruleset>d:\rulesets\strings.xml</ruleset>
-                        <ruleset>http://localhost/design.xml</ruleset>
-                    </rulesets>
-                </configuration>
-            </plugin>
-        </plugins>
-    </reporting>
-
-The value of the 'ruleset' value can either be a relative address, an absolute address or even an url.
-
-A clean strategy for customizing which rules to use for a project is to write a ruleset file.
-In this file you can define which rules to use, add custom rules, and
-customizing which rules to include/exclude from official rulesets. More information on
-writing a ruleset can be found [here](/pmd_userdocs_understanding_rulesets.html).
-Note that if you include other rulesets in your own rulesets, you have to be sure that the plugin
-will be able to resolve those other ruleset references.
-
-##### Other configurations
-
-The Maven 2 PMD plugin allows you to configure CPD, targetJDK, and the use of XRef to link
-the report to html source files, and the file encoding:
-
-    <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-pmd-plugin</artifactId>
-        <configuration>
-            <linkXRef>true</linkXRef>
-            <sourceEncoding>ISO-8859-1</sourceEncoding>
-            <minimumTokens>30</minimumTokens>
-            <targetJdk>1.4</targetJdk>
-        </configuration>
-    </plugin>
-
-#### Reference
-
-For more data, please see the well documented PMD plugin project page here:
-<http://maven.apache.org/plugins/maven-pmd-plugin/index.html>
-Also, the bug tracker for this plugin is [here](http://jira.codehaus.org/browse/MPMD).
-
-
-
-
 ### NetBeans
 
 The [SQE](http://kenai.com/projects/sqe/) project includes PMD integration for NetBeans.
diff --git a/docs/pages/pmd/userdocs/ant.md b/docs/pages/pmd/userdocs/tools/ant.md
similarity index 98%
rename from docs/pages/pmd/userdocs/ant.md
rename to docs/pages/pmd/userdocs/tools/ant.md
index 2997527ad2..eb2ff5f42e 100644
--- a/docs/pages/pmd/userdocs/ant.md
+++ b/docs/pages/pmd/userdocs/tools/ant.md
@@ -1,8 +1,10 @@
 ---
 title: Ant Task Usage
-sidebar: pmd_sidebar
-permalink: pmd_userdocs_ant.html
-folder: pmd/userdocs
+permalink: pmd_userdocs_tools_ant.html
+author: >
+    David Dixon-Peugh <dpeugh@users.sourceforge.net>,
+    Tom Copeland <tom@infoether.com>,
+    Xavier Le Vourch <xlv@users.sourceforge.net>
 ---
 
 ## PMD
diff --git a/docs/pages/pmd/userdocs/tools/maven.md b/docs/pages/pmd/userdocs/tools/maven.md
new file mode 100644
index 0000000000..06057b1b2d
--- /dev/null
+++ b/docs/pages/pmd/userdocs/tools/maven.md
@@ -0,0 +1,234 @@
+---
+title: Maven PMD Plugin
+permalink: /pmd_userdocs_tools_maven.html
+last_updated: August 2017
+author: >
+    Miguel Griffa <mikkey@users.sourceforge.net>,
+    Romain PELISSE <belaran@gmail.com>,
+    Andreas Dangel <andreas.dangel@adangel.org>
+---
+
+## Maven 2 and 3
+
+### Running the pmd plugin
+
+#### Generating a project report
+
+To include the PMD report in the project reports section add the following lines under
+the reports element in your pom.xml:
+
+``` xml
+<project>
+    ...
+    <reporting>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-pmd-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </reporting>
+    ...
+</project>
+```
+
+This will add an entry to the 'project reports' section with the PMD report when you build the maven site.
+
+
+#### Executing PMD manually
+
+To run PMD on a Maven project without adding it as a report, simply run
+
+    mvn pmd:pmd
+
+The PMD plugin writes the report in XML which will then be formatted into more readable HTML.
+
+
+#### Integrated into the build process
+
+You can also run PMD automatically when building your project. You even let the build fail, if
+PMD finds some violations. Therefore the `check` goal is used:
+
+``` xml
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-pmd-plugin</artifactId>
+        <configuration>
+            <failOnViolation>true</failOnViolation> <!-- this is actually true by default, but can be disabled -->
+            <printFailingErrors>true</printFailingErrors>
+        </configuration>
+        <executions>
+          <execution>
+            <goals>
+              <goal>check</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+  ...
+</project>
+```
+
+This will run PMD automatically during the `verify` phase of the build. You can additionally run CPD, if
+you add `cpd-check` as a goal.
+
+
+### Customization
+
+#### Changing rulesets
+
+To specify a ruleset, simply edit the previous configuration:
+
+
+    <reporting>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-pmd-plugin</artifactId>
+                <configuration>
+                    <rulesets>
+                        <ruleset>/rulesets/java/braces.xml</ruleset>
+                        <ruleset>/rulesets/java/naming.xml</ruleset>
+                        <ruleset>d:\rulesets\strings.xml</ruleset>
+                        <ruleset>http://localhost/design.xml</ruleset>
+                    </rulesets>
+                </configuration>
+            </plugin>
+        </plugins>
+    </reporting>
+
+The value of the 'ruleset' element can either be a relative address, an absolute address or even an url.
+
+A clean strategy for customizing which rules to use for a project is to write a ruleset file.
+In this file you can define which rules to use, add custom rules, and
+customizing which rules to include/exclude from official rulesets. More information on
+writing a ruleset can be found [here](pmd_userdocs_understanding_rulesets.html).
+Note that if you include other rulesets in your own rulesets, you have to be sure that the plugin
+will be able to resolve those other ruleset references.
+
+#### Other configurations
+
+The Maven PMD plugin allows you to configure CPD, targetJDK, and the use of XRef to link
+the report to html source files, and the file encoding:
+
+    <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-pmd-plugin</artifactId>
+        <configuration>
+            <linkXRef>true</linkXRef>
+            <sourceEncoding>ISO-8859-1</sourceEncoding>
+            <minimumTokens>30</minimumTokens>
+            <targetJdk>1.4</targetJdk>
+        </configuration>
+    </plugin>
+
+#### Upgrading the PMD version at runtime
+
+The Maven PMD plugin comes with a specific PMD version, which is documented on the
+[plugin project page](https://maven.apache.org/plugins/maven-pmd-plugin/index.html).
+
+Given that the newer PMD version is compatible, you can override the PMD version, that the
+Maven plugin will use and benefit from the latest bugfixes and enhancements:
+
+``` xml
+<project>
+    <properties>
+        <pmdVersion>...choose your version...</version>
+    </properties>
+...
+    <build>
+        <pluginManagement>
+            <plugins>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-pmd-plugin</artifactId>
+                    <version>3.8</version>
+                    <dependencies>
+                        <dependency>
+                            <groupId>net.sourceforge.pmd</groupId>
+                            <artifactId>pmd-core</artifactId>
+                            <version>${pmdVersion}</version>
+                        </dependency>
+                        <dependency>
+                            <groupId>net.sourceforge.pmd</groupId>
+                            <artifactId>pmd-java</artifactId>
+                            <version>${pmdVersion}</version>
+                        </dependency>
+                        <dependency>
+                            <groupId>net.sourceforge.pmd</groupId>
+                            <artifactId>pmd-javascript</artifactId>
+                            <version>${pmdVersion}</version>
+                        </dependency>
+                        <dependency>
+                            <groupId>net.sourceforge.pmd</groupId>
+                            <artifactId>pmd-jsp</artifactId>
+                            <version>${pmdVersion}</version>
+                        </dependency>
+                    </dependencies>
+                </plugin>
+            </plugins>
+        </pluginManagement>
+    </build>
+...
+</project>
+```
+
+### Reference
+
+For more information, please see the well documented PMD plugin project page here:
+<http://maven.apache.org/plugins/maven-pmd-plugin/index.html>.
+Also, the bug tracker for this plugin is [here](http://jira.codehaus.org/browse/MPMD).
+
+
+## Maven 1
+
+{% include warning.html content="Apache Maven 1.x has reached its end of life, and is no longer supported. For more information, see the [announcement](http://maven.apache.org/maven-1.x-eol.html). Users are encouraged to migrate to the current version of Apache Maven." %}
+
+This section is about the maven 1 PMD plugin.
+
+### Running the pmd plugin
+
+#### Generating a project report
+
+To include the PMD report in the project reports section add the following line under
+the reports element in your project.xml:
+
+    <report>maven-pmd-plugin</report>
+
+This will add an entry to the 'project reports' section with the PMD report.
+
+#### Executing PMD manually
+
+To run PMD on a Maven project without adding it as a report, simply run
+
+    maven pmd xdoc
+
+The PMD plugin writes the report in XML which will then be formatted into more readable HTML.
+
+### Customization
+
+#### Changing rulesets
+
+To specify a set of official, built-in rulesets to be used set them in the property
+<em>maven.pmd.rulesets</em>.  You can include this setting in your project.properties file.
+
+A clean strategy for customizing which rules to use for a project is to write a ruleset file.
+In this file you can define which rules to use, add custom rules, and
+customizing which rules to include/exclude from official rulesets. More information on
+writing a ruleset can be found [here](/pmd_userdocs_understanding_rulesets.html).
+
+Add to the root of your Maven project a pmd.xml file which contains the ruleset mentioned in
+the previous paragraph. Add the following property to your project now:
+
+    maven.pmd.rulesetfiles = ${basedir}/pmd.xml
+
+### Reference
+
+See the PMD plugin project page here:
+<http://maven.apache.org/maven-1.x/plugins/pmd/>
diff --git a/docs/pages/pmd/userdocs/understanding_rulesets.md b/docs/pages/pmd/userdocs/understanding_rulesets.md
index 98df3eddb8..cf9ea363c6 100644
--- a/docs/pages/pmd/userdocs/understanding_rulesets.md
+++ b/docs/pages/pmd/userdocs/understanding_rulesets.md
@@ -1,9 +1,69 @@
 ---
 title: Understanding Rulesets
-sidebar: pmd_sidebar
 permalink: pmd_userdocs_understanding_rulesets.html
-folder: pmd/userdocs
+summary: Rulesets are collections of rules
+last_updated: September 2017
 ---
 
-* Selecting the rules that should be executed
-* adjusting rule properties
+There are two major use cases:
+
+1.  When defining a new rule, the rule needs to be defined in a ruleset. PMD's built-in rules
+    are defined in specific rulesets from which the rule reference documentation is generated,
+    see [Java Rules](pmd_rules_java.html) for an example.
+
+    Similar rules are grouped together into the same ruleset, like the [Java Braces Ruleset](pmd_rules_java_braces.html)
+    which contains rules that all deal with missing braces.
+
+2.  When executing PMD you need to tell, which rules should be executed. You could directly point to the
+    built-in rulesets, but then you might be overwhelmed by the found violations. As described
+    in [Best Practices](pmd_userdocs_best_practices.html), it's better to define an own custom ruleset.
+
+    With an own custom ruleset, you can:
+
+    *   Select the rules, that should be executed
+    *   Adjust the rule properties to exactly meet your needs
+
+## Create a custom ruleset
+
+You start by creating a new XML file with the following contents:
+
+``` xml
+<?xml version="1.0"?>
+
+<ruleset name="Custom Rules"
+    xmlns="http://pmd.sourceforge.net/ruleset/3.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/3.0.0 http://pmd.sourceforge.net/ruleset_3_0_0.xsd">
+    <description>
+Custom rules
+    </description>
+
+</ruleset>
+```
+
+Now start to add rule by **referencing** them. Let's say, you want to start with finding
+[Empty Catch Blocks](pmd_rules_java_empty.html#emptycatchblock). Then you'd add the following
+rule reference inside the `ruleset` elements:
+
+```xml
+    <rule ref="rulesets/java/empty.xml/EmptyCatchBlock" />
+```
+
+## Adjusting rule properties
+
+If you want to be less strict with empty catch blocks, you could define that an exception variable name
+of `ignored` will not raise a violation. Therefore you would reference the rule **and** define
+the appropriate property value:
+
+```xml
+    <rule ref="rulesets/java/empty.xml/EmptyCatchBlock">
+        <properties>
+            <property name="allowExceptionNameRegex">
+                <value>^ignored$</value>
+            </property>
+        </properties>
+    </rule>
+```
+
+
+{% include note.html content="More information about rulesets can be found on [Making Rulesets](pmd_devdocs_making_rulesets.html)." %}
diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md
index 61c3918dec..3d9505e6a4 100644
--- a/docs/pages/release_notes.md
+++ b/docs/pages/release_notes.md
@@ -102,6 +102,9 @@ and include them to such reports.
     and "NcssTypeCount". The new rule uses the metrics framework to achieve the same. It has two properties, to
     define the report level for method and class sizes separately. Constructors and methods are considered the same.
 
+*   The new rule `ForLoopCanBeForeach` (ruleset `java-migration`) helps to identify those for-loops that can
+    be safely refactored into for-each-loops available since java 1.5.
+
 #### Modified Rules
 
 *   The rule `UnnecessaryFinalModifier` (ruleset `java-unnecessarycode`) has been revamped to detect more cases.
@@ -166,6 +169,7 @@ All existing rules have been updated to reflect these changes. If you have custo
 *   java-comments
     *   [#536](https://github.com/pmd/pmd/issues/536): \[java] CommentDefaultAccessModifierRule ignores constructors
 *   java-controversial
+    *   [#388](https://github.com/pmd/pmd/issues/388): \[java] controversial.AvoidLiteralsInIfCondition 0.0 false positive
     *   [#408](https://github.com/pmd/pmd/issues/408): \[java] DFA not analyzing asserts
     *   [#537](https://github.com/pmd/pmd/issues/537): \[java] UnnecessaryParentheses fails to detect obvious scenario
 *   java-design
@@ -273,6 +277,7 @@ All existing rules have been updated to reflect these changes. If you have custo
 *   [#556](https://github.com/pmd/pmd/pull/556): \[java] Fix #357: UncommentedEmptyConstructor consider annotations on Constructor - [Clément Fournier](https://github.com/oowekyala)
 *   [#557](https://github.com/pmd/pmd/pull/557): \[java] Fix NPath metric not counting ternaries correctly - [Clément Fournier](https://github.com/oowekyala)
 *   [#563](https://github.com/pmd/pmd/pull/563): \[java] Add support for basic method type inference for strict invocation - [Bendegúz Nagy](https://github.com/WinterGrascph)
+*   [#566](https://github.com/pmd/pmd/pull/566): \[java] New rule in migrating ruleset: ForLoopCanBeForeach - [Clément Fournier](https://github.com/oowekyala)
 *   [#567](https://github.com/pmd/pmd/pull/567): \[java] Last API change for metrics (metric options) - [Clément Fournier](https://github.com/oowekyala)
 *   [#570](https://github.com/pmd/pmd/pull/570): \[java] Model lower, upper and intersection types - [Bendegúz Nagy](https://github.com/WinterGrascph)
 *   [#573](https://github.com/pmd/pmd/pull/573): \[java] Data class rule - [Clément Fournier](https://github.com/oowekyala)
@@ -284,3 +289,4 @@ All existing rules have been updated to reflect these changes. If you have custo
 *   [#583](https://github.com/pmd/pmd/pull/583): \[java] Documentation about writing metrics - [Clément Fournier](https://github.com/oowekyala)
 *   [#585](https://github.com/pmd/pmd/pull/585): \[java] Moved NcssCountRule to codesize.xml - [Clément Fournier](https://github.com/oowekyala)
 *   [#588](https://github.com/pmd/pmd/pull/588): \[java] XPath function to compute metrics - [Clément Fournier](https://github.com/oowekyala)
+*   [#598](https://github.com/pmd/pmd/pull/598): \[java] Fix #388: controversial.AvoidLiteralsInIfCondition 0.0 false positive - [Clément Fournier](https://github.com/oowekyala)
diff --git a/pmd-core/src/main/resources/rulesets/releases/600.xml b/pmd-core/src/main/resources/rulesets/releases/600.xml
index 4c7bc8b288..cebdca8529 100644
--- a/pmd-core/src/main/resources/rulesets/releases/600.xml
+++ b/pmd-core/src/main/resources/rulesets/releases/600.xml
@@ -9,6 +9,7 @@ This ruleset contains links to rules that are new in PMD v6.0.0
   </description>
 
     <rule ref="rulesets/java/codesize.xml/NcssCount"/>
+    <rule ref="rulesets/java/migrating.xml/ForLoopCanBeForeach"/>
 
 </ruleset>
 
diff --git a/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java b/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java
index 9a2e66551b..bde314c9cc 100644
--- a/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java
+++ b/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java
@@ -239,15 +239,16 @@ public class RuleDocGenerator {
         for (Map.Entry<Language, List<RuleSet>> entry : rulesets.entrySet()) {
             String languageTersename = entry.getKey().getTerseName();
             for (RuleSet ruleset : entry.getValue()) {
+                String rulesetFilename = getRuleSetFilename(ruleset);
                 String filename = RULESET_INDEX_FILENAME_PATTERN
                     .replace("${language.tersename}", languageTersename)
-                    .replace("${ruleset.name}", getRuleSetFilename(ruleset));
+                    .replace("${ruleset.name}", rulesetFilename);
 
                 Path path = getAbsoluteOutputPath(filename);
 
                 String permalink = RULESET_INDEX_PERMALINK_PATTERN
                         .replace("${language.tersename}", languageTersename)
-                        .replace("${ruleset.name}", getRuleSetFilename(ruleset));
+                        .replace("${ruleset.name}", rulesetFilename);
 
                 List<String> lines = new LinkedList<>();
                 lines.add("---");
@@ -350,6 +351,12 @@ public class RuleDocGenerator {
                         }
                         lines.add("");
                     }
+
+                    lines.add("**Use this rule by referencing it:**");
+                    lines.add("``` xml");
+                    lines.add("<rule ref=\"rulesets/" + languageTersename + "/" + rulesetFilename + ".xml/" + rule.getName() + "\" />");
+                    lines.add("```");
+                    lines.add("");
                 }
 
                 writer.write(path, lines);
diff --git a/pmd-doc/src/test/resources/expected/sample.md b/pmd-doc/src/test/resources/expected/sample.md
index 66f2db4ada..c1119aab3e 100644
--- a/pmd-doc/src/test/resources/expected/sample.md
+++ b/pmd-doc/src/test/resources/expected/sample.md
@@ -21,6 +21,11 @@ Just some description of a deprecated rule.
 //ForStatement
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/DeprecatedSample" />
+```
+
 ## JumbledIncrementer
 
 **Since:** PMD 1.0
@@ -58,6 +63,11 @@ public class JumbledIncrementerRule1 {
 |----|-------------|-----------|
 |sampleAdditionalProperty|the value|This is a additional property for tests|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/JumbledIncrementer" />
+```
+
 ## MovedRule
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -93,6 +103,11 @@ public class JumbledIncrementerRule1 {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/MovedRule" />
+```
+
 ## OverrideBothEqualsAndHashcode
 
 **Since:** PMD 0.4
@@ -132,6 +147,11 @@ public class Foo {      // perfect, both methods provided
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/OverrideBothEqualsAndHashcode" />
+```
+
 ## RenamedRule
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -172,3 +192,8 @@ public class JumbledIncrementerRule1 {
 |Name|Default Value|Description|
 |----|-------------|-----------|
 |sampleAdditionalProperty|the value|This is a additional property for tests|
+
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/RenamedRule" />
+```
diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/migrating/ForLoopCanBeForeachRule.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/migrating/ForLoopCanBeForeachRule.java
new file mode 100644
index 0000000000..017ca45353
--- /dev/null
+++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/migrating/ForLoopCanBeForeachRule.java
@@ -0,0 +1,408 @@
+/**
+ * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
+ */
+
+package net.sourceforge.pmd.lang.java.rule.migrating;
+
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+
+import org.jaxen.JaxenException;
+
+import net.sourceforge.pmd.lang.ast.Node;
+import net.sourceforge.pmd.lang.java.ast.ASTExpression;
+import net.sourceforge.pmd.lang.java.ast.ASTForInit;
+import net.sourceforge.pmd.lang.java.ast.ASTForStatement;
+import net.sourceforge.pmd.lang.java.ast.ASTForUpdate;
+import net.sourceforge.pmd.lang.java.ast.ASTName;
+import net.sourceforge.pmd.lang.java.ast.ASTPrimaryPrefix;
+import net.sourceforge.pmd.lang.java.ast.ASTPrimarySuffix;
+import net.sourceforge.pmd.lang.java.ast.ASTRelationalExpression;
+import net.sourceforge.pmd.lang.java.ast.ASTVariableDeclarator;
+import net.sourceforge.pmd.lang.java.ast.ASTVariableDeclaratorId;
+import net.sourceforge.pmd.lang.java.ast.ASTVariableInitializer;
+import net.sourceforge.pmd.lang.java.rule.AbstractJavaRule;
+import net.sourceforge.pmd.lang.java.symboltable.VariableNameDeclaration;
+import net.sourceforge.pmd.lang.java.typeresolution.TypeHelper;
+import net.sourceforge.pmd.lang.symboltable.NameOccurrence;
+import net.sourceforge.pmd.lang.symboltable.Scope;
+
+/**
+ * @author Clément Fournier
+ * @since 6.0.0
+ */
+public class ForLoopCanBeForeachRule extends AbstractJavaRule {
+
+    @Override
+    public Object visit(ASTForStatement node, Object data) {
+
+        final ASTForInit init = node.getFirstChildOfType(ASTForInit.class);
+        final ASTForUpdate update = node.getFirstChildOfType(ASTForUpdate.class);
+        final ASTExpression guardCondition = node.getFirstChildOfType(ASTExpression.class);
+
+        if (init == null && update == null || guardCondition == null) {
+            return super.visit(node, data);
+        }
+
+        Entry<VariableNameDeclaration, List<NameOccurrence>> indexDecl = getIndexVarDeclaration(init, update);
+
+        if (indexDecl == null) {
+            return super.visit(node, data);
+        }
+
+
+        List<NameOccurrence> occurrences = indexDecl.getValue();
+        VariableNameDeclaration index = indexDecl.getKey();
+
+        if (TypeHelper.isA(index, Iterator.class)) {
+            Entry<VariableNameDeclaration, List<NameOccurrence>> iterableInfo = getIterableDeclOfIteratorLoop(index, node.getScope());
+
+            if (iterableInfo != null && isReplaceableIteratorLoop(indexDecl, guardCondition, iterableInfo, node)) {
+                addViolation(data, node);
+            }
+            return data;
+        }
+
+
+        if (occurrences == null || !"int".equals(index.getTypeImage()) || !indexStartsAtZero(index)) {
+            return super.visit(node, data);
+        }
+
+
+        String itName = index.getName();
+        String iterableName = getIterableNameOrNullToAbort(guardCondition, itName);
+
+
+        if (!isForUpdateSimpleEnough(update, itName) || iterableName == null) {
+            return super.visit(node, data);
+        }
+
+        Entry<VariableNameDeclaration, List<NameOccurrence>> iterableInfo = findDeclaration(iterableName, node.getScope());
+        VariableNameDeclaration iterableDeclaration = iterableInfo == null ? null : iterableInfo.getKey();
+
+        if (iterableDeclaration == null) {
+            return super.visit(node, data);
+        }
+
+        if (iterableDeclaration.isArray() && isReplaceableArrayLoop(node, occurrences, iterableDeclaration)) {
+            addViolation(data, node);
+        } else if (iterableDeclaration.getTypeImage() != null && iterableDeclaration.getTypeImage()
+                                                                                    .matches("List|ArrayList|LinkedList")
+            && isReplaceableListLoop(node, occurrences, iterableDeclaration)) {
+            addViolation(data, node);
+        }
+
+        return super.visit(node, data);
+    }
+
+
+    /* Finds the declaration of the index variable and its occurrences */
+    private Entry<VariableNameDeclaration, List<NameOccurrence>> getIndexVarDeclaration(ASTForInit init, ASTForUpdate update) {
+        if (init == null) {
+            return guessIndexVarFromUpdate(update);
+        }
+
+        Map<VariableNameDeclaration, List<NameOccurrence>> decls = init.getScope().getDeclarations(VariableNameDeclaration.class);
+        Entry<VariableNameDeclaration, List<NameOccurrence>> indexVarAndOccurrences = null;
+
+        for (Entry<VariableNameDeclaration, List<NameOccurrence>> e : decls.entrySet()) {
+
+            ASTForInit declInit = e.getKey().getNode().getFirstParentOfType(ASTForInit.class);
+            if (declInit == init) {
+                indexVarAndOccurrences = e;
+                break;
+            }
+        }
+
+        return indexVarAndOccurrences;
+
+    }
+
+
+    /** Does a best guess to find the index variable, gives up if the update has several statements */
+    private Entry<VariableNameDeclaration, List<NameOccurrence>> guessIndexVarFromUpdate(ASTForUpdate update) {
+
+        Node name = null;
+        try {
+            List<Node> match = update.findChildNodesWithXPath(getSimpleForUpdateXpath(null));
+            if (!match.isEmpty()) {
+                name = match.get(0);
+            }
+        } catch (JaxenException je) {
+            throw new RuntimeException(je);
+        }
+
+        if (name == null || name.getImage() == null) {
+            return null;
+        }
+
+        return findDeclaration(name.getImage(), update.getScope().getParent());
+    }
+
+
+    /**
+     * @return true if there's only one update statement of the form i++ or ++i.
+     */
+    private boolean isForUpdateSimpleEnough(ASTForUpdate update, String itName) {
+        return update != null && update.hasDescendantMatchingXPath(getSimpleForUpdateXpath(itName));
+    }
+
+
+    private String getSimpleForUpdateXpath(String itName) {
+        return "./StatementExpressionList[count(*)=1]"
+            + "/StatementExpression"
+            + "/*[self::PostfixExpression and @Image='++' or self::PreIncrementExpression]"
+            + "/PrimaryExpression"
+            + "/PrimaryPrefix"
+            + "/Name"
+            + (itName == null ? "" : ("[@Image='" + itName + "']"));
+    }
+
+
+    /* We only report loops with int initializers starting at zero. */
+    private boolean indexStartsAtZero(VariableNameDeclaration index) {
+        ASTVariableDeclaratorId name = (ASTVariableDeclaratorId) index.getNode();
+        ASTVariableDeclarator declarator = name.getFirstParentOfType(ASTVariableDeclarator.class);
+
+        if (declarator == null) {
+            return false;
+        }
+
+        try {
+            List<Node> zeroLiteral = declarator.findChildNodesWithXPath(
+                "./VariableInitializer/Expression/PrimaryExpression/PrimaryPrefix/Literal[@Image='0' and "
+                    + "@StringLiteral='false']");
+            if (!zeroLiteral.isEmpty()) {
+                return true;
+            }
+        } catch (JaxenException je) {
+            throw new RuntimeException(je);
+        }
+
+        return false;
+
+    }
+
+
+    /**
+     * Gets the name of the iterable array or list.
+     *
+     * @param itName The name of the iterator variable
+     *
+     * @return The name, or null if it couldn't be found or the guard condition is not safe to refactor (then abort)
+     */
+    private String getIterableNameOrNullToAbort(ASTExpression guardCondition, String itName) {
+
+
+        if (guardCondition.jjtGetNumChildren() > 0
+            && guardCondition.jjtGetChild(0) instanceof ASTRelationalExpression) {
+
+            ASTRelationalExpression relationalExpression = (ASTRelationalExpression) guardCondition.jjtGetChild(0);
+
+            if (relationalExpression.hasImageEqualTo("<") || relationalExpression.hasImageEqualTo("<=")) {
+
+                try {
+                    List<Node> left = guardCondition.findChildNodesWithXPath(
+                        "./RelationalExpression/PrimaryExpression/PrimaryPrefix/Name[@Image='" + itName + "']");
+
+                    List<Node> right = guardCondition.findChildNodesWithXPath(
+                        "./RelationalExpression[@Image='<']/PrimaryExpression/PrimaryPrefix"
+                            + "/Name[matches(@Image,'\\w+\\.(size|length)')]"
+                            + "|"
+                            + "./RelationalExpression[@Image='<=']/AdditiveExpression[count(*)=2 and "
+                            + "@Image='-' and PrimaryExpression/PrimaryPrefix/Literal[@Image='1']]"
+                            + "/PrimaryExpression/PrimaryPrefix/Name[matches(@Image,'\\w+\\.(size|length)')]");
+
+                    if (left.isEmpty()) {
+                        return null;
+                    } else if (!right.isEmpty()) {
+                        return right.get(0).getImage().split("\\.")[0];
+                    } else {
+                        return null;
+                    }
+
+                } catch (JaxenException je) {
+                    throw new RuntimeException(je);
+                }
+            }
+        }
+        return null;
+    }
+
+
+    private Entry<VariableNameDeclaration, List<NameOccurrence>> getIterableDeclOfIteratorLoop(VariableNameDeclaration indexDecl, Scope scope) {
+        Node initializer = indexDecl.getNode().getFirstParentOfType(ASTVariableDeclarator.class)
+                                    .getFirstChildOfType(ASTVariableInitializer.class);
+
+        if (initializer == null) {
+            return null;
+        }
+
+        String name = initializer.getFirstDescendantOfType(ASTName.class)
+                                 .getImage();
+        int dotIndex = name.indexOf('.');
+
+        if (dotIndex > 0) {
+            name = name.substring(0, dotIndex);
+        }
+
+        return findDeclaration(name, scope);
+    }
+
+
+    private boolean isReplaceableArrayLoop(ASTForStatement stmt, List<NameOccurrence> occurrences,
+                                           VariableNameDeclaration arrayDeclaration) {
+        String arrayName = arrayDeclaration.getName();
+
+
+        for (NameOccurrence occ : occurrences) {
+
+            if (occ.getLocation().getFirstParentOfType(ASTForUpdate.class) == null
+                && occ.getLocation().getFirstParentOfType(ASTExpression.class)
+                != stmt.getFirstChildOfType(ASTExpression.class)
+                && !occurenceIsArrayAccess(occ, arrayName)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+
+    private boolean occurenceIsArrayAccess(NameOccurrence occ, String arrayName) {
+        if (occ.getLocation() instanceof ASTName) {
+            ASTPrimarySuffix suffix = occ.getLocation().getFirstParentOfType(ASTPrimarySuffix.class);
+
+            if (suffix == null || !suffix.isArrayDereference()) {
+                return false;
+            }
+
+            return suffix.hasDescendantMatchingXPath("./Expression/PrimaryExpression[count(*)"
+                                                         + "=1]/PrimaryPrefix/Name[@Image='" + occ.getImage() + "']")
+                && suffix.hasDescendantMatchingXPath("../PrimaryPrefix/Name[@Image='" + arrayName + "']")
+                && !suffix.hasDescendantMatchingXPath("../../AssignmentOperator");
+        }
+        return false;
+    }
+
+
+    private boolean isReplaceableListLoop(ASTForStatement stmt, List<NameOccurrence> occurrences,
+                                          VariableNameDeclaration listDeclaration) {
+
+        String listName = listDeclaration.getName();
+
+
+        for (NameOccurrence occ : occurrences) {
+
+            if (occ.getLocation().getFirstParentOfType(ASTForUpdate.class) == null
+                && occ.getLocation().getFirstParentOfType(ASTExpression.class)
+                != stmt.getFirstChildOfType(ASTExpression.class)
+                && !occurenceIsListGet(occ, listName)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+
+    /** @return true if this occurence is as an argument to List.get on the correct list */
+    private boolean occurenceIsListGet(NameOccurrence occ, String listName) {
+        if (occ.getLocation() instanceof ASTName) {
+            ASTPrimarySuffix suffix = occ.getLocation().getFirstParentOfType(ASTPrimarySuffix.class);
+
+            if (suffix == null) {
+                return false;
+            }
+
+            Node prefix = suffix.jjtGetParent().jjtGetChild(0);
+
+            if (!(prefix instanceof ASTPrimaryPrefix) && prefix.jjtGetNumChildren() != 1
+                && !(prefix.jjtGetChild(0) instanceof ASTName)) {
+                return false;
+            }
+
+            String callImage = prefix.jjtGetChild(0).getImage();
+
+            return (listName + ".get").equals(callImage);
+
+        }
+        return false;
+    }
+
+
+    private Entry<VariableNameDeclaration, List<NameOccurrence>> findDeclaration(String varName, Scope innermost) {
+        Scope currentScope = innermost;
+
+        while (currentScope != null) {
+            for (Entry<VariableNameDeclaration, List<NameOccurrence>> e : currentScope.getDeclarations(VariableNameDeclaration.class).entrySet()) {
+                if (e.getKey().getName().equals(varName)) {
+                    return e;
+                }
+            }
+            currentScope = currentScope.getParent();
+        }
+
+        return null;
+    }
+
+
+    private boolean isReplaceableIteratorLoop(Entry<VariableNameDeclaration, List<NameOccurrence>> indexInfo,
+                                              ASTExpression guardCondition,
+                                              Entry<VariableNameDeclaration, List<NameOccurrence>> iterableInfo,
+                                              ASTForStatement stmt) {
+
+        if (isIterableModifiedInsideLoop(iterableInfo, stmt)) {
+            return false;
+        }
+
+
+        String indexName = indexInfo.getKey().getName();
+
+        if (indexName == null) {
+            return false;
+        }
+
+        if (!guardCondition.hasDescendantMatchingXPath(
+            "./PrimaryExpression/PrimaryPrefix/Name[@Image='" + indexName + ".hasNext']")) {
+            return false;
+        }
+
+        List<NameOccurrence> occurrences = indexInfo.getValue();
+
+        if (occurrences.size() > 2) {
+            return false;
+        }
+
+        for (NameOccurrence occ : indexInfo.getValue()) {
+            String image = occ.getLocation().getImage();
+
+            if (occ.getLocation() instanceof ASTName
+                && ((indexName + ".hasNext").equals(image) || (indexName + ".next").equals(image))) {
+                continue;
+            }
+            return false;
+        }
+        return true;
+    }
+
+    private boolean isIterableModifiedInsideLoop(Entry<VariableNameDeclaration, List<NameOccurrence>> iterableInfo,
+                                                 ASTForStatement stmt) {
+
+        String iterableName = iterableInfo.getKey().getName();
+        for (NameOccurrence occ : iterableInfo.getValue()) {
+            ASTForStatement forParent = occ.getLocation().getFirstParentOfType(ASTForStatement.class);
+            if (forParent == stmt) {
+                String image = occ.getLocation().getImage();
+                if (image.startsWith(iterableName + ".remove")) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+
+}
diff --git a/pmd-java/src/main/resources/rulesets/java/controversial.xml b/pmd-java/src/main/resources/rulesets/java/controversial.xml
index 779217c9f0..5c59d8f486 100644
--- a/pmd-java/src/main/resources/rulesets/java/controversial.xml
+++ b/pmd-java/src/main/resources/rulesets/java/controversial.xml
@@ -681,7 +681,7 @@ More exceptions can be defined with the property "ignoreMagicNumbers".
 //IfStatement/Expression/*/PrimaryExpression/PrimaryPrefix/Literal
 [not(NullLiteral)]
 [not(BooleanLiteral)]
-[empty(index-of(tokenize($ignoreMagicNumbers, ','), @Image))]
+[empty(index-of(tokenize($ignoreMagicNumbers, '\s*,\s*'), @Image))]
 ]]>
         </value>
       </property>
diff --git a/pmd-java/src/main/resources/rulesets/java/migrating.xml b/pmd-java/src/main/resources/rulesets/java/migrating.xml
index 48de8b7271..672b92fb21 100644
--- a/pmd-java/src/main/resources/rulesets/java/migrating.xml
+++ b/pmd-java/src/main/resources/rulesets/java/migrating.xml
@@ -477,4 +477,34 @@ public class MyTest {
     </example>
   </rule>
 
-</ruleset>
\ No newline at end of file
+    <rule name="ForLoopCanBeForeach"
+          language="java"
+          since="6.0"
+          message="This 'for' loop can be replaced by a 'foreach' loop"
+          typeResolution="true"
+          minimumLanguageVersion="1.5"
+          class="net.sourceforge.pmd.lang.java.rule.migrating.ForLoopCanBeForeachRule"
+          externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_migrating.html#forloopcanbeforeach">
+        <description><![CDATA[
+            Reports loops that can be safely replaced with the foreach syntax. The rule considers loops over
+            lists, arrays and iterators. A loop is safe to replace if it only uses the index variable to
+            access an element of the list or array, only has one update statement, and loops through *every*
+            element of the list or array left to right.
+        ]]></description>
+        <priority>3</priority>
+        <example><![CDATA[
+public class MyClass {
+  void loop(List<String> l) {
+    for (int i = 0; i < l.size(); i++) { // pre Java 1.5
+      System.out.println(l.get(i));
+    }
+
+    for (String s : l) {        // post Java 1.5
+      System.out.println(s);
+    }
+  }
+}
+        ]]></example>
+    </rule>
+
+</ruleset>
diff --git a/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/rule/migrating/MigratingRulesTest.java b/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/rule/migrating/MigratingRulesTest.java
index f20dbc1485..4354dca831 100644
--- a/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/rule/migrating/MigratingRulesTest.java
+++ b/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/rule/migrating/MigratingRulesTest.java
@@ -15,6 +15,7 @@ public class MigratingRulesTest extends SimpleAggregatorTst {
         addRule(RULESET, "AvoidAssertAsIdentifier");
         addRule(RULESET, "AvoidEnumAsIdentifier");
         addRule(RULESET, "ByteInstantiation");
+        addRule(RULESET, "ForLoopCanBeForeach");
         addRule(RULESET, "IntegerInstantiation");
         addRule(RULESET, "JUnit4SuitesShouldUseSuiteAnnotation");
         addRule(RULESET, "JUnit4TestShouldUseAfterAnnotation");
diff --git a/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/controversial/xml/AvoidLiteralsInIfCondition.xml b/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/controversial/xml/AvoidLiteralsInIfCondition.xml
index 7a561d35cf..e43cee3cb3 100644
--- a/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/controversial/xml/AvoidLiteralsInIfCondition.xml
+++ b/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/controversial/xml/AvoidLiteralsInIfCondition.xml
@@ -77,4 +77,19 @@ public class Foo {
 }
       ]]></code>
   </test-code>
+  <test-code>
+    <description>#388 False positive due to space in property list</description>
+    <expected-problems>0</expected-problems>
+    <rule-property name="ignoreMagicNumbers"><![CDATA[-1,0,1, 0.0]]></rule-property>
+    <code><![CDATA[
+    class Foo {
+      void bar() {
+        if (num == 0.0) {
+	        return MathExtItg.sgn0raw(num) == 1 ? IEEEclass.PositiveZero : IEEEclass.NegativeZero;
+	      }
+      }
+    }
+    ]]></code>
+  </test-code>
+
 </test-data>
diff --git a/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/migrating/xml/ForLoopCanBeForeach.xml b/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/migrating/xml/ForLoopCanBeForeach.xml
new file mode 100644
index 0000000000..d9db96aa48
--- /dev/null
+++ b/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/migrating/xml/ForLoopCanBeForeach.xml
@@ -0,0 +1,267 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<test-data>
+
+
+    <test-code>
+        <description>Positive with list</description>
+        <expected-problems>1</expected-problems>
+        <code><![CDATA[
+        public class MyClass {
+          void loop(List<String> l) {
+            for (int i = 0; i < l.size(); i++) {
+              System.out.println(l.get(i));
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Positive with lower or equal</description>
+        <expected-problems>1</expected-problems>
+        <code><![CDATA[
+        public class Foo {
+          void loop(List<String> lo) {
+            for (int i = 0; i <= lo.size() - 1; i++) {
+              System.out.println(lo.get(i));
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Usage of index var outside get</description>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+        public class MyClass {
+          void loop(List<String> l) {
+            for (int i = 0; i < l.size(); i++) {
+              System.out.println(i + ": " + l.get(i));
+
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Subclass of List</description>
+        <expected-problems>1</expected-problems>
+        <code><![CDATA[
+        public class MyClass {
+          void loop(ArrayList<String> l) {
+            for (int i = 0; i < l.size(); i++) {
+              System.out.println(l.get(i));
+
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Get called on another list</description>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+        public class MyClass {
+          void loop(List<String> l) {
+            List<String> l2 = new ArrayList<>(l);
+            for (int i = 0; i < l.size(); i++) {
+              System.out.println(l2.get(i));
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Backwards iteration</description>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+        public class MyClass {
+          void loop(List<String> l) {
+            for (int i = l.size() - 1; i > 0; i-= 1) {
+              System.out.println(i + ": " + l.get(i));
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+
+    <test-code>
+        <description>Index var initialized outside for init</description>
+        <expected-problems>1</expected-problems>
+        <code><![CDATA[
+        public class MyClass {
+          void loop(List<String> l) {
+            int i = 0;
+            for (; i < l.size(); i++) {
+              System.out.println(l.get(i));
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+
+    <test-code>
+        <description>Array positives</description>
+        <expected-problems>2</expected-problems>
+        <code><![CDATA[
+        class Foo {
+          protected static final char[] filter(char[] chars, char removeChar) {
+            int count = 0;
+            for (int i = 0; i < chars.length; i++) {
+              if (chars[i] == removeChar) {
+                count++;
+              }
+            }
+
+            char[] results = new char[chars.length - count];
+
+            int index = 0;
+            for (int i = 0; i < chars.length; i++) {
+              if (chars[i] != removeChar) {
+                results[index++] = chars[i];
+              }
+            }
+            return results;
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Consider iterators</description>
+        <expected-problems>1</expected-problems>
+        <code><![CDATA[
+        class Foo {
+          void loop() {
+            Iterable<DataFlowNode> path = null;
+            for (Iterator<DataFlowNode> i = path.iterator(); i.hasNext();) {
+              DataFlowNode inode = i.next();
+              if (inode.getVariableAccess() == null) {
+                continue;
+              }
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+
+    <test-code>
+        <description>Index var starts after zero</description>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+        public class MyClass {
+          void loop(List<String> l) {
+            for (int i = 1; i < filters.size(); i++) {
+              builder.append(' ').append(getOperator()).append(' ');
+              builder.append(filters.get(i));
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+
+    <test-code>
+        <description>Prefix increment should work</description>
+        <expected-problems>1</expected-problems>
+        <code><![CDATA[
+        class AbstractApexNode {
+         Node[] children;
+
+          public Object childrenAccept(ApexParserVisitor visitor, Object data) {
+            if (children != null) {
+              for (int i = 0; i < children.length; ++i) {
+                @SuppressWarnings("unchecked")
+                // we know that the children here are all ApexNodes
+                ApexNode<T> apexNode = (ApexNode<T>) children[i];
+                apexNode.jjtAccept(visitor, data);
+              }
+            }
+            return data;
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Index inside arithmetic expression should whitelist the loop</description>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+        class BenchMarker {
+          private static String findOptionalStringValue(String[] args, String name, String defaultValue) {
+            for (int i = 0; i < args.length; i++) {
+              if (args[i].equals(name)) {
+                return args[i + 1];
+              }
+            }
+            return defaultValue;
+          }
+        }
+        ]]></code>
+    </test-code>
+
+
+    <test-code>
+        <description>Array assignment whitelists the loop</description>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+        class StringPropertyTest {
+          private String newString() {
+            int strLength = randomInt(1, MAX_STRING_LENGTH);
+
+            char[] chars = new char[strLength];
+            for (int i = 0; i < chars.length; i++) {
+              chars[i] = randomCharIn(CHARSET);
+            }
+            return new String(chars);
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Consider iterators only if safe</description>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+        class Foo {
+          void loop() {
+            Iterable<DataFlowNode> path = null;
+
+            for (Iterator<DataFlowNode> i = path.iterator(); i.hasNext();) {
+              DataFlowNode inode = i.next();
+              path.remove(inode); // throws ConcurrentModificationException if it were a foreach
+              if (inode.getVariableAccess() == null) {
+                continue;
+              }
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Do not report iterator loop if we can't find iterator decl</description>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+        class Foo {
+          void loop() {
+            for (Iterator<DataFlowNode> i = path.iterator(); i.hasNext();) {
+              DataFlowNode inode = i.next();
+              if (inode.getVariableAccess() == null) {
+                continue;
+              }
+            }
+          }
+        }
+        ]]></code>
+    </test-code>
+
+
+</test-data>