Updated documentation.

README.md

@@ -1,47 +1,159 @@
 # htmldiff.js
-## HTML Diffing in JavaScript
 
-[![Build Status](https://travis-ci.org/inkling/htmldiff.js.svg?branch=master)](https://travis-ci.org/inkling/htmldiff.js)
+Diff and markup HTML with `<ins>` and `<del>` tags.
 
-`htmldiff.js` is a JavaScript port of [https://github.com/myobie/htmldiff](https://github.com/myobie/htmldiff) by
-[Keanu Lee](http://keanulee.com) at [Inkling](https://www.inkling.com/).
 
-This is diffing that understands HTML. Best suited for cases when you
-want to show a diff of user-generated HTML (like from a wysiwyg editor).
+## Origin
 
-## Usage (JavaScript)
-You use it like this:
+Quote from the original source of this fork:
+
+*`htmldiff.js` is a JavaScript port of [https://github.com/myobie/htmldiff](https://github.com/myobie/htmldiff) by
+[Keanu Lee](http://keanulee.com) at [Inkling](https://www.inkling.com/).*
+
+**htmldiff.js** is based on [this fork](https://github.com/inkling/htmldiff.js) and adds a few things:
+
+- Diffing of video, math, widget, iframe, img and svg tags.
+- Ability to set atomic tags via the API.
+- A command line interface.
+- TypeScript support.
+- Better documentation.
+
+See also *Credits* below.
+
+## Description
+
+htmldiff takes two HTML snippets or files and marks the differences between them with
+`<ins>` and `<del>` tags. The diffing understands HTML so it doesn't do a pure text diff,
+instead it will insert the appropriate tags for changed/added/deleted text nodes, single 
+tags or tag hierarchies.
+
+The module can be used as module in Node.js, with RequireJS, or even just as a script tag.
+
+## API
+
+The module exports a single default function:
+
+JavaScript:
+
+````javascript
+diff(before, after, className, dataPrefix, atomicTags);
+````
+
+TypeScript:
+
+````javascript
+function diff(before: string, after: string, className?: string | null, dataPrefix?: string | null, atomicTags?: string | null): string;
+````
+
+### Parameters
+
+- `before` (string) is the original HTML text.
+- `after` (string) is the HTML text after the changes have been applied.
+
+The return value is a string with the diff result, marked by `<ins>` and `del` tags. The 
+function has three optional parameters. If an empty string or `null` is used for any
+of these three parameters it will be ignored:
+
+- `className` (string) className will be added as a class attribute on every inserted 
+  `<ins>` and `<del>` tag.
+- `dataPrefix` (string) The data prefix to use for data attributes. The so called *operation 
+  index data attribute* will be named `data-${dataPrefix-}operation-index`. If not used, 
+  the default attribute name `data-operation-index` will be added on every inserted 
+  `<ins>` and `<del>` tag. The value of this attribute is an auto incremented counter.
+- `atomicTags` (string) A list of tag names. The list has to be in the form `tag1|tag2|...`
+  e. g. `head|script|style`. An atomic tag is one whose child nodes should not be 
+  compared - the entire tag should be treated as one token. This is useful for tags where 
+  it does not make sense to insert `<ins>`  and `<del>` tags. If not used, this default 
+  list will be used: `iframe|object|math|svg|script|video|head|style`.
+
+
+### Example
+
+JavaScript:
 
 ```javascript
-  diff = require('htmldiff.js');
-  console.log(diff('<p>this is some text</p>', '<p>this is some more text</p>'));
+  diff = require('node-htmldiff');
+
+  console.log(diff('<p>This is some text</p>', '<p>That is some more text</p>', 'myClass'));
 ```
 
-And you get:
+TypeScript:
 
-```html
-<p>this is some <ins>more </ins>text</p>
+```javascript
+  import diff = require("node-htmldiff");
+
+  console.log(diff("<p>This is some text</p>", "<p>That is some more text</p>", "myClass"));
 ```
 
-## Usage (TypeScript)
+Please note that `diff` is only an arbitrary name; since the module exports only one default 
+function you can use whatever name you like, e. g., `diffHTML`.
+
+Result:
 
-```typescript
-  import diff = require("htmldiff");
-  console.log(diff("<p>this is some text</p>", "<p>this is some more text</p>"));
+```html
+<p><del data-operation-index="1" class="myClass">This</del><ins data-operation-index="1" class="myClass">That</ins> is some<ins data-operation-index="3" class="myClass"> more</ins> text.</p>
 ```
 
-`diff` is just an arbitry name for the exported default module function, you can use
-any other name you like, e. g.:
 
-```typescript
-  import diffHTML = require("htmldiff");
-  console.log(diffHTML("<p>this is some text</p>", "<p>this is some more text</p>"));
+## Command line interface
+
+```bash
+htmldiff beforeFile afterFile diffedFile [Options]
 ```
 
-## Module
+Parameters: 
+
+- `beforeFile` An HTML input file in its original form.
+
+- `afterFile` An HTML input file, based on `beforeFile` but with changes.
+
+- `diffedFile` Name of the diffed HTML output file. All differences between
+  `beforeFile` and `afterFile` will be surrounded with `<ins>` and `<del>`
+  tags. If diffedFile is `-` (minus) the result will be written with 
+  `console.log()` to stdout.
+
+Options:
+
+- `-c` `className` (optional): className will be added as a class attribute 
+  on every `<ins>` and `<del>` tag.
+
+- `-p` `dataPrefix` (optional): The data prefix to use for data attributes. 
+  The operation index data attribute will be named 
+  `data-${dataPrefix-}operation-index`. If not used, the default attribute 
+  name `data-operation-index` will be added on every `<ins>` and `<del>` tag. 
+  The value of this attribute is an auto incremented counter.
+
+- `-t` `atomicTags` (optional): List of tag names. The list has to be in the 
+  form `tag1|tag2|...` e. g. `head|script|style`. An atomic tag is one whose 
+  child nodes should not be compared - the entire tag should be treated as 
+  one token. This is useful for tags where it does not make sense to insert 
+  `<ins>` and `<del>` tags. If not used, this default list will be used:
+  `iframe|object|math|svg|script|video|head|style`.
+
+
+## Development
+
+After cloning the repository run `npm i` or `npm install` to install the necessary 
+dependencies. A run of `npm run make` creates the JavaScript output file. 
+`npm run lint` checks the TypeScript sources with TSLint. `npm test` runs all the
+tests from the `test` directory. `npm run testsample` diffs the HTML sample files 
+from the directory `sample` and logs the result to the console.
+
+The command line interface of htmldiff is developed in TypeScript so you have to run
+`npm run make` once to create the JavaScript output file.
+
+
+## Credits
+
+This module wouldn't have been possible without code from the following projects/persons:
+
+- Original project: [The Network Inc.](http://www.tninetwork.com), [Github](https://github.com/tnwinc/htmldiff.js)
+- Massive improvements of the original code: [Inkling](https://www.inkling.com), [Github](https://github.com/inkling/htmldiff.js)
+- Support of more tags: Ian White, [Github](https://github.com/ian97531)
+
 
-It should be multi-module aware. ie. it should work as a node.js module
-or an AMD (RequireJS) module, or even just as a script tag.
+## License
 
+MIT © [idesis GmbH](http://www.idesis.de), Rellinghauser Straße 334F, D-45136 Essen
 
-Licensed under the MIT License. See the `LICENSE` file for details.
+See the `LICENSE` file for details.