Convert the FAQ from FML to Markdown

src/site/markdown/faq.md

@@ -0,0 +1,106 @@
+---
+title: Frequently Asked Questions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<a id="top"></a>
+
+# Frequently Asked Questions
+
+1. [The PMD report takes a long time to generate. Is there any way to skip the PMD or CPD reports temporarily?](#Is_there_any_way_to_skip_the_PMD_or_CPD_reports_temporarily)
+2. [How can I generate links to the JXR cross-referenced source?](#xref_links)
+3. [I have add the PMD/CPD reports, but they do not show up in the generated site. Has the plugin been executed?](#no_report_in_site)
+4. [What's the difference between violations, failures and warnings and when is a build failing?](#violations_failures_warnings)
+5. [Why do I get sometimes false positive and/or false negative violations?](#typeresolution_aggregate)
+
+<a id="Is_there_any_way_to_skip_the_PMD_or_CPD_reports_temporarily"></a>
+
+### The PMD report takes a long time to generate. Is there any way to skip the PMD or CPD reports temporarily?
+
+Yes, each report supports a skip parameter which you can pass on the command line, `-Dpmd.skip=true` and
+`-Dcpd.skip=true` respectively.
+
+<a id="xref_links"></a>
+
+### How can I generate links to the JXR cross-referenced source?
+
+First make sure that the [linkXRef](pmd-mojo.html#linkXRef) parameter is configured correctly (it is switched
+on by default).
+
+Then, the jxr plugin has to run first so that the links can be picked up by the pmd report. If you run from
+the command line, use `mvn jxr:jxr pmd:pmd`, or if you want the reports generated by the site plugin,
+configure the jxr plugin in your reporting section, see
+[JXR usage](http://maven.apache.org/plugins/maven-jxr-plugin/usage.html).
+
+<a id="no_report_in_site"></a>
+
+### I have add the PMD/CPD reports, but they do not show up in the generated site. Has the plugin been executed?
+
+If there are no violations, then by default no reports are created and the entire PMD or CPD section is not
+rendered in the site. To change this behaviour, set the
+[skipEmptyReport for PMD](pmd-mojo#skipEmptyReport) or
+[skipEmptyReport for CPD](cpd-mojo#skipEmptyReport) to `false`
+
+<a id="violations_failures_warnings"></a>
+
+### What's the difference between violations, failures and warnings and when is a build failing?
+
+PMD reports violations. These violations originate from rules - the rules, that are enabled in the configured
+ruleset (see property [rulesets](pmd-mojo.html#rulesets)). Each rule has a assigned priority (1 - high,
+2 - medium-high, 3 - medium, 4 - medium-low, 5 - low). This priority is also used for the violation.
+
+Violations with a high enough priority can fail the build when using the [check](check-mojo.html) goal. These
+violations are called "failures". The exact priority, when to fail the build, is configured via the property
+[failurePriority](check-mojo.html#failurePriority).
+
+Violations, that have a priority too low to fail the build, are called "warnings". These warnings appear in
+the report and are displayed in the build output, if the property [verbose](check-mojo.html#verbose) is
+enabled.
+
+With the property [failOnViolation](check-mojo.html#failOnViolation) the build failure can be entirely
+disabled. This is most useful at command line with `-Dpmd.failOnViolation=false`.
+
+With the property [maxAllowedViolations](check-mojo.html#maxAllowedViolations) one can configure how many
+failures are allowed, before the build is failed.
+
+<a id="typeresolution_aggregate"></a>
+
+### Why do I get sometimes false positive and/or false negative violations?
+
+In order to improve PMD's results, type resolution should be used. It is enabled by default (property
+[typeResolution](pmd-mojo.html#typeResolution)) and helps to avoid false positive or false negative findings
+by matching the exact types of method parameters or variables.
+
+However, this requires that the project is built first so that not only the project's dependencies can be used
+for type resolution, but also the project's classes as well.
+
+When using the property [aggregate](pmd-mojo.html#aggregate), this is problematic: With aggregate=true, PMD is
+executed at the root of a multi-module project *before the individual modules are built*. Then the types of
+the individual projects are not available, which might lead to false positive findings e.g. for the rule
+"UnusedPrivateMethod". That's why this property has been deprecated.
+
+In order to use type resolution and aggregate together, maven needs to be execute in two passes: First pass
+will compile the projects (e.g. `mvn clean package`) and the second pass will execute PMD without clean via
+the verify phase (e.g. `mvn verify`).
+
+Since version 3.15.0 the new goal [aggregate-pmd](aggregate-pmd-mojo.html) can be used which allows to run
+everything with only one maven call. However, this goal invokes the lifecycle *test-compile* before executing
+itself, which might lead to duplicated execution of some plugins.