[doc] Add remaining pages from old "usage" section

docs/_data/sidebars/pmd_sidebar.yml

@@ -36,6 +36,12 @@ entries:
     - title: Best Pratices
       url: /pmd_best_practices.html
       output: web, pdf
+    - title: Copy-Paste Detection
+      url: /pmd_userdocs_cpd.html
+      output: web, pdf
+    - title: Suppressing
+      url: /pmd_userdocs_suppressing.html
+      output: web, pdf
     - title: Tools / Integrations
       url: /pmd_tools.html
       output: web, pdf
@@ -69,6 +75,12 @@ entries:
     - title: Java Rules
       url: /pmd_rules_java.html
       output: web, pdf
+  - title: Language Specific Documentation
+    output: web, pdf
+    folderitems:
+    - title: JSP Support
+      url: /pmd_languages_jsp.html
+      output: web, pdf
   - title: Developer Documentation
     output: web, pdf
     folderitems:

docs/pages/pmd/languages/pmd_languages_jsp.md

@@ -0,0 +1,52 @@
+---
+title: JSP Support
+sidebar: pmd_sidebar
+permalink: pmd_languages_jsp.html
+folder: pmd/languages
+---
+
+## What is currently supported and what is not
+
+In short, JSP files that are XHTML-compliant, are supported.
+Except for files that contain inline DTDs; only references to external
+DTD files are supported (having inline DTD will result in a parsing
+error).
+
+The XHTML support means that:
+
+*   opening tags must be accompanied by corresponding *closing tags*
+    (or they must be empty tags). This means that currently a "<HR>"
+    tag without corresponding closing tag will result in a parsing error.
+
+*   *attribute values* must be *surrounded by* single or double *quotes*. This means that the following syntax
+    will result in a parsing error:
+
+    <MyTag myAttr1=true myAttr2=1024/>
+
+*   < and > characters must be *escaped*, or put inside a CDATA section.
+
+    PMD creates a "Abstract Syntax Tree" representation of source code; the rules use such a tree as input.
+    For JSP files, the following constructs are parsed into nodes of the tree:
+
+    *   XML-elements, XML-attributes, XML-comments, doctype-declarations, CDATA
+    *   JSP-directives, JSP-declarations, JSP-comments, JSP-scriptlets, JSP-expressions,
+        Expression Language expressions, JSF value bindings
+    *   everything else is seen as flat text nodes.
+
+*   Java code (e.g. in JSP-scriptlets) and EL expressions are not parsed or
+    further broken down. If you want to create rules that check the code
+    inside EL expressions or JSP scriptlets (a.o.), you currently would
+    have to do "manual" string manipulation (e.g. using regular expressions).
+
+## How to use it
+
+Using the command-line interface, two new options can be used in the arguments string:
+
+*   "-jsp" : this triggers checking JSP files (they are not checked by default)
+*   "-nojava" : this tells PMD not to check java source files (they are checked by default)
+
+Using the Ant task, you decide if PMD must check JSP files by choosing
+what files are given to the PMD task. If you use a fileset that
+contains only ".java" files, JSP files obviously will not be checked.
+
+If you want to call the PMD API for checking JSP files, you should investigate the javadoc of PMD.

docs/pages/pmd/userdocs/pmd_userdocs_suppressing.md

@@ -0,0 +1,166 @@
+---
+title: Suppressing warnings
+sidebar: pmd_sidebar
+permalink: pmd_userdocs_suppressing.html
+folder: pmd/userdocs
+---
+
+PMD provides several methods by which Rule violations can be suppressed.
+Follow these steps to help you determine which expression method works best
+for you:
+
+1.  Is the thing you need to suppress universally appealing to other
+    users of PMD, or is it a false positive? Can you modify the Rule to
+    support this specific suppression via a configuration property, or to
+    fix the false positive?  If you can do this, then please do so, and
+    submit a patch back to the PMD project.  Since PMD is built by users
+    for users, your help would be greatly appreciated by everyone.  If you
+    cannot...
+
+2.  Can you use Annotations or the NOPMD marker to work around your
+    particular issue on a case by case basis?  If not...
+
+3.  Can a regular expression matching the violation message work
+    around your particular issue?  If not...
+
+4.  Can a XPath query on the violation node work around your particular
+    issue? If not...
+
+5.  Your last and final option is to see the first point about
+    changing the Rule, but you do not need to submit a patch back to the
+    PMD project.
+
+If you need to modify the Rule, see [How to write a rule](../customizing/howtowritearule.html).
+Otherwise, the other suppression methods are explain in the following sections.
+
+## Annotations
+
+You can use a JDK 1.5 annotation to suppress PMD warnings, like this:
+
+    // This will suppress all the PMD warnings in this class
+    @SuppressWarnings("PMD")
+    public class Bar {
+        void bar() {
+            int foo;
+        }
+    }
+
+Or you can suppress one rule with an annotation like this:
+
+    // This will suppress UnusedLocalVariable warnings in this class
+    @SuppressWarnings("PMD.UnusedLocalVariable")
+    public class Bar {
+        void bar() {
+            int foo;
+        }
+    }
+
+PMD also obeys the JDK annotation @SuppressWarnings("unused"), which will apply to all rules in the unused ruleset.
+
+    // This will suppress UnusedLocalVariable and UnusedPrivateMethod warnings in this class
+    @SuppressWarnings("unused")
+    public class Bar {
+        void bar() {
+            int foo;
+        }
+        private void foobar(){}
+    }
+
+
+## NOPMD
+
+Alternatively, you can tell PMD to ignore a specific line by using the "NOPMD" marker, like this:
+
+    public class Bar {
+        // 'bar' is accessed by a native method, so we want to suppress warnings for it
+        private int bar; //NOPMD
+    }
+
+You can use whatever text string you want to suppress warnings, for example, here's
+how to use TURN\_OFF\_WARNINGS as the suppressor:
+
+    $ cat Foo.java
+    public class Foo {
+        void bar() {
+            int x = 2; // TURN_OFF_WARNINGS
+        }
+    }
+
+    $ ./run.sh pmd -d Foo.java -f text -R java-unusedcode -suppressmarker TURN_OFF_WARNINGS
+    No problems found!
+    UnusedLocalVariable rule violation suppressed by //NOPMD in /home/tom/pmd/pmd/bin/Foo.java
+
+Note that PMD expects the //NOPMD marker to be on the same line as the violation. So, for
+example, if you want to suppress an "empty if statement" warning, you'll need to place it on
+the line containing the "if" keyword, e.g.:
+
+    $ cat ~/tmp/Foo.java
+    public class Foo {
+        void bar() {
+            int x = 42;
+            if (x > 5) { // NOPMD
+            }
+        }
+    }
+    $ java net.sourceforge.pmd.PMD -d ~/tmp/Foo.java -f text -R java-basic
+    No problems found!
+    $
+
+A message placed after the NOPMD marker will get placed in the report, e.g.:
+
+    public class Foo {
+        void bar() {
+            try {
+                bar();
+            } catch (FileNotFoundException e) {} // NOPMD - this surely will never happen
+        }
+    }
+
+## Violation Suppress Regex
+
+If a particular Rule does not provide a property to customize behavior
+sufficiently, you can fall back to using the global 'violationSuppressRegex'
+property.  This property defines a regular expression to match against the
+message of the violation.  If the regular expression matches,
+then the violation will be suppressed.
+
+When using a Rule reference in a RuleSet XML, you can customize the
+Rule by adding the 'violationSuppressRegex' property.  For example, to
+suppress reporting specifically named parameters which are unused:
+
+
+    <rule ref="rulesets/java/unusedcode.xml/UnusedFormalParameter">
+      <properties>
+        <property name="violationSuppressRegex" value=".*'mySpecialParameterName'.*"/>
+      </properties>
+    </rule>
+
+Note for message based suppression to work, you must know who to write
+a regular expression that matches the message of violations you wish to
+suppress. Regular expressions are explained in the JavaDoc for standard
+Java class java.util.regex.Pattern.
+
+## Violation Suppress XPath
+
+If a particular Rule does not provide a property to customize behavior
+sufficiently, you can fall back to using the global 'violationSuppressXPath'
+property.  This property defines an XPath query to be executed using the
+violation node as the starting point.  If the XPath query matches anything,
+then the violation will be suppressed.
+
+When using a Rule reference in a RuleSet XML, you can customize the
+Rule by adding the 'violationSuppressXPath' property.  For example, to
+suppress reporting specifically typed parameters which are unused:
+
+    <rule ref="rulesets/java/unusedcode.xml/UnusedFormalParameter">
+      <properties>
+        <property name="violationSuppressXPath" value=".[typeof('java.lang.String')]"/>
+      </properties>
+    </rule>
+
+Note for XPath based suppression to work, you must know how to write
+an XPath query that matches the AST structure of the nodes of the
+violations you wish to suppress.  XPath queries are explained in
+[XPath Rule tutorial](../customizing/xpathruletutorial.html).
+
+Suggestions?  Comments? Post them [here](https://github.com/pmd/pmd/issues). Thanks!