Commits

Michael[tm] Smith committed f8e32ab

Updated the README.

  • Participants
  • Parent commits cf9317d

Comments (0)

Files changed (1)

-## How to download, build, and run the validator
+## Using
+
+There are two ways you can use the code here to do validate documents:
+
+  A. Use the pre-built vnu.jar and vnu-fast-client.jar files
+
+  or
+
+  B. Download, build, and run the validator from the sources
+
+This section explains how to use the pre-built jar files. For information
+on how to download, build, and run the validator from the sources, see the
+next section.
+
+You can validate a single document by doing this:
+
+  `java -jar vnu.jar FILE.html`
+
+You can batch-validate multiple files at once by doing this:
+
+  `java -jar vnu.jar FILE.html FILE2.html FILE3.HTML FILE4.html...`
+
+Or by doing something like this:
+
+  `java -jar vnu.jar $(find . -name "*.html")`
+
+### Faster validation
+
+For faster validation -- especially for single files -- you should run the
+validator as a service and use `vnu-fast-client.jar`.
+
+To do that, you first need to start the validator by doing this:
+
+  `java -cp vnu.jar nu.validator.servlet.Main 8888`
+
+(To have the validator listen on a different port, replace `8888` with the
+port number.)
+
+The validator will run in the console window in which you start it, writing
+any service messages to that window.
+
+In a separate console window, you can validate a single document by doing
+this:
+
+  `java -jar vnu-fast-client.jar FILE.html`
+
+You can batch-validate multiple files at once by doing this:
+
+  `java -jar vnu-fast-client.jar FILE.html FILE2.html FILE3.HTML...`
+
+Or by doing something like this:
+
+  `java -jar vnu-fast-client.jar $(find . -name "*.html")`
+
+### Configuration
+
+You can configure the validator behavior using Java system properties.
+These properties map to the Validator.nu common input parameters documented
+at http://wiki.whatwg.org/wiki/Validator.nu_Common_Input_Parameters
+
+nu.validator.client.host
+
+    Specifies the hostname of the validator for the client to connect to.
+
+    default: `127.0.0.1`
+
+nu.validator.client.port
+
+    Specifies the hostname of the validator for the client to connect to.
+
+    default: `8888`
+
+    example: `java -Dnu.validator.client.port=8080 -jar vnu.jar FILE.html`
+
+nu.validator.client.level
+
+    Specifies the severity level of validation messages to report; to
+    suppress warning-level messages, set this to `error`.
+
+    default: [unset]
+
+    possible values: `error`
+
+    example: `java -Dnu.validator.client.level=error -jar vnu.jar FILE.html`
+
+nu.validator.client.parser
+
+    Specifies which parser to use.
+
+    default: `html` or (for `*.xhtml` files) `xml`
+
+    possible values: see
+    http://wiki.whatwg.org/wiki/Validator.nu_Common_Input_Parameters#parser
+
+    example: `java -Dnu.validator.client.level=error -jar vnu.jar FILE.html`
+
+nu.validator.client.charset
+
+    Specifies the encoding of the input document.
+
+    default: [unset]
+
+nu.validator.client.content-type
+
+    Specifies the content-type of the input document.
+
+    default: `text/html` or (for `*.xhtml` files) `application/xhtml+xml`
+
+nu.validator.client.out
+
+    Specifies the output format for validation messages.
+
+    default: `gnu`
+
+    possible values: see
+    http://wiki.whatwg.org/wiki/Validator.nu_Common_Input_Parameters#out
+
+nu.validator.client.asciiquotes
+
+    Specifies whether ASCII quotation marks are substituted for Unicode
+    smart quoation marks in validation messages.
+
+    default: `yes`
+
+    possible values: `yes` or `no`
+
+## How to download, build, and run the validator from the sources
 
   1. First, set the JAVA_HOME environment variable properly.
+
      On Ubuntu:
 
       `export JAVA_HOME=/usr/lib/jvm/java-6-openjdk`
 
   2. Create a validator workspace.
 
-      mkdir checker
+      `mkdir checker`
 
-      cd checker
+      `cd checker`
 
-      hg clone https://bitbucket.org/validator/build build
+      `hg clone https://bitbucket.org/validator/build build`
 
       The above steps create a `checker` directory in which the build
       script will create other subdirectories, and downloads the `build.py`
 
   3. Run the build script.
 
-      python build/build.py all
+      `python build/build.py all`
 
-      python build/build.py all
+      `python build/build.py all`
 
 Yes, the last line is there twice intentionally. Running the script twice tends
 to fix a `ClassCastException` on the first run.
 searched for additional jars for the classpath. For example, if you configure
 log4j to send email, you should put the Java Mail API and JavaBeans Activation
 Framework jars in extras/.
-
-## jars
-
-[more info later]