Merge pull request #249 from paazmaya/247-documentation-update

Documentation update to reflect recent changes

Author: ironikart

README.markdown

@@ -1,86 +1,73 @@
-# HTML_CodeSniffer README
+# HTML_CodeSniffer
 
 ## What is HTML_CodeSniffer?
 
 HTML_CodeSniffer is a JavaScript application that checks a HTML document
 or source code, and detects violations of a defined presentation or accessibility
-standard.
+standard, such as Section508 or WCAG2.0.
 
-### Standards included
+## Standards included
 
-By default, HTML\_CodeSniffer comes with standards that cover the three conformance
+By default, HTML_CodeSniffer comes with standards that cover the three conformance
 levels of the <abbr title="World Wide Web Consortium">W3C</abbr> [Web Content Accessibility Guidelines (WCAG) 2.0](http://www.w3.org/TR/WCAG20),
 and the <abbr title="United States of America">U.S.</abbr> [Section 508](http://section508.gov/index.cfm?fuseAction=stdsdoc) legislation.
 It also provides tools to write your own standards, which can be useful in situations
 where you wish to enforce consistency across a web site.
 
-### Using HTML_CodeSniffer
+## Using HTML_CodeSniffer
 
-HTML\_CodeSniffer can be called in multiple ways:
+HTML_CodeSniffer can be called in multiple ways:
 * Called directly in JavaScript source, HTML_CodeSniffer will provide a list of known
   and potential violations to the calling script.
 * It also comes with a pop-up auditor interface, accessible via a bookmarklet,
   letting you browse through messages emitted from one of the defined standards.
   Where possible, the auditor also points you to the HTML element causing the problem.
 * It can also be run on the command line with the assistance of a headless browser app.
-* Using npm:
-```
-$ npm i -g npm
-$ npm i --save html_codesniffer
-```
-
-### Licence
+* Using as a Node.js module, installed with npm: `npm i --save html_codesniffer`
 
-HTML_CodeSniffer is released under a BSD-style licence. For more information,
-please see the file "licence.txt".
 
 ## Using the source code
 
 ### Building the auditor
 
-The HTML\_CodeSniffer auditor can be built using [node.js](https://nodejs.org/) and the Grunt
-tasker (http://gruntjs.com/). It has been tested with the latest version of node.js
-(at time of writing: version 6.0) and Grunt, but should also work with recent
-earlier versions.
-
-* Install node.js with your package manager of choice.
-* You may need to update the Node.js package manager (npm) itself:
-  <code>npm update -g npm</code>
-* Install the Grunt CLI helper if you haven't already done so:  
-  <code>npm install -g grunt-cli</code>
-* Get node.js to install the dependencies Grunt needs:  
-  <code>npm install</code>
-* Run Grunt to build the auditor:
-  <code>grunt build</code>
-
-You should see two new directories: <code>node_modules</code> (containing the node.js
-dependencies), and <code>build</code> (containing your auditor). You can then move
-(or symlink as appropriate) your <code>build</code> directory to a web-accessible
+The HTML_CodeSniffer auditor can be built using [Node.js](https://nodejs.org/) and [Grunt
+task runner](http://gruntjs.com/). It has been tested with the recent version of Node.js
+(starting from version 6.0) and Grunt.
+
+* Install Node.js with your package manager of choice, for example `sudo apt-get install nodejs`
+* You may need to update the Node.js package manager (npm) itself: `npm install -g npm`
+* Install the Grunt CLI helper if you haven't already done so: `npm install -g grunt-cli`
+* Get Node.js to install the dependencies Grunt needs: `npm install`
+* Run Grunt to build the auditor: `grunt build`
+
+You should see two new directories: `node_modules` (containing the Node.js
+dependencies), and `build` (containing your auditor). You can then move
+(or symlink as appropriate) your `build` directory to a web-accessible
 location.
 
 Then grab or copy the JavaScript from the auditor bookmarklet from the [HTML_CodeSniffer site](https://squizlabs.github.io/HTML_CodeSniffer),
 replace the directory at the start (//squizlabs.github.io/HTML_CodeSniffer/build) with your local URL, and save as a new bookmarklet.
 
-#### Debug build
+### Debug build
 
-If you are developing using HTML\_CodeSniffer and require the code not minified for
-debugging purposes, follow the above steps, but run <code>grunt build-debug</code>
+If you are developing using HTML_CodeSniffer and require the code not minified for
+debugging purposes, follow the above steps, but run `grunt build-debug`
 (instead of just build). This will combine the files as normal, but not minify them.
 
-### Command-Line processing
+## Command-Line processing
 
 **Note:** These examples assume a built version of HTMLCS exported to `./build/HTMLCS.js`
 
-#### PhantomJS
+### PhantomJS
 
 You will need [PhantomJS](http://www.phantomjs.org/) installed if you wish to
 use the contributed command-line script. PhantomJS provides a headless Webkit-based
 browser to run the scripts in, so it should provide results that are similar to
 recent (or slightly less than recent) versions of Safari.
 
-See the <code>Contrib/PhantomJS/HTMLCS_Run.js</code> file for more information.
+See the `Contrib/PhantomJS/HTMLCS_Run.js` file for more information.
 
-#### Headless Google Chrome via Puppeteer
+### Headless Google Chrome via Puppeteer
 
 [Puppeteer](https://developers.google.com/web/tools/puppeteer/get-started) offers an
 easy way to interact with the page via Google Chrome.
@@ -113,7 +100,7 @@ const url = 'https://www.squiz.net';
   page.on('console', msg => {
     console.log(msg.text())
   });
-  
+
   await page.goto(url);
 
   await page.addScriptTag({
@@ -128,13 +115,14 @@ const url = 'https://www.squiz.net';
 })();
 ```
 
-#### Node & JSDom
+### Node.js & JSDom
 
-HTML_CodeSniffer requires a dom to run, however, it is possible to run it entirely
-server side without a headless browser using Node on arbitrary fragments of HTML using
+HTML_CodeSniffer requires a DOM to run, however, it is possible to run it entirely
+server side without a headless browser using Node.js on arbitrary fragments of HTML using
 an environment wrapper like [JSDom](https://github.com/jsdom/jsdom).
 
-An example node script:
+An example Node.js script:
+
 ```javascript
 var jsdom = require('jsdom');
 var { JSDOM } = jsdom;
@@ -157,7 +145,7 @@ dom.window.eval(HTMLCS);
 dom.window.HTMLCS_RUNNER.run('WCAG2AA');
 ```
 
-### Translations
+## Translations
 
 HTML_CodeSniffer supports _very_ basic string translations. The auditor will use the current language of the document it is being run in (e.g. `<html lang="en">`). A language code can be supplied if you need to tell HTML_CodeSniffer which language you want to use.
 
@@ -168,11 +156,11 @@ HTMLCSAuditor.run('WCAG2AA', null, {
 });
 ```
 
-**Note:** HTML_CodeSniffer only has english (default) and polish language.
+**Note:** HTML_CodeSniffer only has English (default), French, and Polish languages.
 
-If other language support is required a custom version can be built by adding more translations in `Translations/<code>.js` and using the grunt build process described above.
+If other language support is required a custom version can be built by adding more translations in `Translations/*.js` and using the grunt build process described above.
 
-### Contributing and reporting issues
+## Contributing and reporting issues
 
 To report any issues with using HTML_CodeSniffer, please use the
 [HTML_CodeSniffer Issue Tracker](http://github.com/squizlabs/HTML_CodeSniffer/issues).
@@ -188,10 +176,9 @@ contribute, you do not need to do both.
 More information on HTML_CodeSniffer can be found on its GitHub site,
 [http://squizlabs.github.io/HTML_CodeSniffer/](http://squizlabs.github.io/HTML_CodeSniffer/). This site provides:
 
-- Information on the tests performed (and messages emitted) by HTML_CodeSniffer's standards, organised by conformance level and Success Criterion;
-- A source test area that allows you to try out HTML_CodeSniffer with your own HTML source code; and
-- A link to the HTML_CodeSniffer bookmarklet, letting you check other pages using the pop-up auditor interface.
-
+* Information on the tests performed (and messages emitted) by HTML_CodeSniffer's standards, organised by conformance level and Success Criterion;
+* A source test area that allows you to try out HTML_CodeSniffer with your own HTML source code; and
+* A link to the HTML_CodeSniffer bookmarklet, letting you check other pages using the pop-up auditor interface.
 
 ## Translation Contributors
 
@@ -203,3 +190,5 @@ Special thanks to:
 ## License
 
 Licensed under [the BSD 3-Clause "New" or "Revised" License](https://opensource.org/licenses/BSD-3-Clause).
+
+License text also available in [the `license.txt` file](./license.txt).

index.js

@@ -4,5 +4,5 @@ var scriptPath = __dirname+'/build/HTMLCS.js';
 if (fs.existsSync(scriptPath) === true) {
     module.exports = require(scriptPath);
 } else {
-    throw new Error('HTMLCS must be built using `grunt build` before it can be required in Nodejs.');
-}
+    throw new Error('HTMLCS must be built using `grunt build` before it can be required in Node.js.');
+}

package.json

@@ -9,8 +9,12 @@
   ],
   "scripts": {
     "prepack": "grunt build",
+    "build": "grunt build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "engines": {
+    "node": ">=6"
+  },
   "files": [
     "Auditor",
     "build",