Improved documentation.

README.md

@@ -10,3 +10,48 @@ xml-stream-filter - a Java and command line utility to:
   - based on:
     -  the `javax.xml.*` API and 
     - `com.fasterxml.woodstox:woodstox-core` [known](https://github.com/eishay/jvm-serializers/wiki) to be a very fast implementation.
+
+
+Usage
+-----
+
+The "*thin*" jar is available in Maven Central:
+
+    <dependency>
+        <groupId>com.carmatechnologies.utilities</groupId>
+        <artifactId>xml-stream-filter</artifactId>
+        <version>1.0</version>
+    </dependency>
+
+You can also download the "*fat*" jar [here](https://github.com/marccarre/xml-stream-filter/archive/v1.0.zip).
+
+
+Command Line Interface
+----------------------
+
+    java -jar com.carmatechnologies.utilities.xml.XmlStreamFilter [-e <arg>] [-f <arg>] [-h] [-i] [-s <arg>] [-t <arg>] [-v] < input.xml|.xml.gz > output.xml|.txt
+
+     -e,--element <arg>     Local name of the XML element to detect in the input XML stream and, potentially, select.
+                            Example: "book".
+
+     -f,--file <arg>        [Optional] Define white-list of patterns from file, one per line.
+                            XML elements will be selected if the value returned by the provided XPath query is in the white-list.
+                            Example:
+                            if file contains "magician\nxquery\n" and filter is: "//book/tags/tag/text()",
+                            then "book" elements with either a "magician" or "xquery" tag will be returned.
+
+     -h,--help              Print this, i.e. a usage message briefly
+                            summarizing the command-line options, then exit.
+
+     -i,--indent            [Optional] Indent returned XML elements, for potentially better readability.
+                            Default: keep the same formatting and indentation as in the input XML stream.
+
+     -s,--select <arg>      XPath query used to select XML elements among the ones detected.
+                            Example: "//book/tags/tag[text() = 'magician']" will select all "book" elements with "magician" as a "tag".
+
+     -t,--transform <arg>   [Optional] XPath expression used to transform the selected XML elements.
+                            Example: "//book/title/text()".
+                            Default: the entire XML element will be returned.
+
+     -v,--version           Print "1.0", i.e. the version number of com.carmatechnologies.utilities.xml.XmlStreamFilter
+                            to the standard output stream. This version number should be included in all bug reports.