New message-filtering options for the HTML checker

This weekend I worked on adding new options to the HTML checker to allow
filtering out (dropping/ignoring/suppressing) errors/warnings you don’t
care about/don’t want to see/don’t consider to be a problem.

https://github.com/validator/validator/wiki/Message-filtering (and pasted in
below) has documentation on the options available in various contexts.

* Filtering messages with the command-line checker
  * Using the `--filterfile` option
  * Using the `--filterpattern` option

* Filtering messages in the network API and Web checker
  * Using the `filterurl` query param
  * Using the `filterpattern` query param

* Filtering messages globally for your own checker service
  * Using the `resources/message-filters.txt` file
  * Using the `--filter-file` option to the build script
  * Using the `nu.validator.servlet.filterfile` Java system property

## Filtering messages with the command-line checker

Use the `--filterfile` and `--filterpattern` options to filter out messages
emitted by the vnu.jar command-line checker.

### Using the `--filterfile` option

Use the `--filterfile` command-line option to specify a filename. Each line of
the specified file contains either a regular expression or starts with `#` to
indicate the line is a comment. Any error message or warning message that
matches a regular expression in the file is filtered out (dropped/suppressed).

    java -jar ~/vnu.jar --filterfile ~/my-message-filters.txt FILE.html

### Using the `--filterpattern` option

Use the `--filterpattern` command-line option to specify a regular-expression
pattern. Any error message or warning message that matches the pattern is
filtered out (dropped/suppressed).

    java -jar ~/vnu.jar --filterpattern=".*Unicode Normalization.*" FILE.html

## Filtering messages in the network API and Web checker

Use the `filterurl` and `filterpattern` query parameters to filter out messages
per-request when using the checker network API or the Web-base checker UI.

### Using the `filterurl` query param

Use the `filterurl` query parameter to specify a URL for a filter file. Each
line of the specified file contains either a regular expression or starts with
`#` to indicate the line is a comment. Any error message or warning message that
matches a regular expression in the file is filtered out (dropped/suppressed).

    curl -s -H 'Content-Type: text/html; charset=utf-8' \
      --data-binary @FILE.html \
      "https://checker.html5.org/?out=json&filterurl=https://example.com/filters.txt

### Using the `filterpattern` query param

Use the `filterpattern` query parameter to specify a **percent-encoded**
regular-expression pattern. Any error message or warning message that matches
the pattern is filtered out (dropped/suppressed).

    curl -s -H 'Content-Type: text/html; charset=utf-8' \
      --data-binary @FILE.html \
      "https://checker.html5.org/?out=json&filterpattern=.*Unicode%20Normalization.*

## Filtering messages globally for your own checker service

When running your own instance of the checker, use the
`resources/message-filters.txt` file or the `--filter-file` option to the build
script or the `nu.validator.servlet.filterfile` Java system property to globally
filter out messages.

### Using the `resources/message-filters.txt` file

To filter out (drop/ignore/suppress) errors/warnings you don’t care about/don’t
want to see/don’t consider a problem, use the `resources/message-filters.txt`
file. Each line of the file contains either a regular expression or starts with
`#` to indicate the line is a comment. Any error message or warning message that
matches a regular expression in the file is filtered out (dropped/suppressed)
globally for all requests made by all users of the service.

### Using the `--filter-file` option to the build script

Use the `--filter-file` build option to specify a different pathname to override
the default `resources/message-filter.txt` location.

    ./build/build.sh --filter-file=/usr/local/validator/message-filters.txt run

### Using the `nu.validator.servlet.filterfile` Java system property

Use the `nu.validator.servlet.filterfile` Java system property to specify a
different pathname to override the default `resources/message-filter.txt`
location.

    java -Dnu.validator.servlet.filterfile=/usr/local/validator/message-filters.txt \
      -cp ~/vnu.jar nu.validator.servlet.Main 8888

-- 
Michael[tm] Smith https://people.w3.org/mike