update readme

README.md

@@ -1,2 +1,79 @@
 # quick-xml
-Quick xml parser
+
+High performance xml pull reader for simple enough xmls.
+
+Inspired by [xml-rs](https://github.com/netvl/xml-rs).
+
+## Usage
+
+Carto.toml
+```toml
+[dependencies]
+quick-xml="0.1"
+```
+
+``` rust
+extern crate quick_xml;
+```
+
+## Example
+
+```rust
+use quick_xml::{XmlReader, Event};
+
+let xml = r#"<tag1 att1 = \"test\">
+                <tag2><!--Test comment-->Test</b>
+                <tag2>
+                    Test 2
+                </tag2>
+            </tag1>"#;
+let reader = XmlReader::from_str(xml).trim_text(true);
+let mut count = 0;
+let mut txt = Vec::new();
+for r in reader {
+    match r {
+        Ok(Event::Start(ref e)) => {
+            match e.as_bytes() {
+                b"tag1" => println!("attributes values: {:?}", 
+                                 e.attributes().map(|a| a.unwrap().1).collect::<Vec<_>>()),
+                b"tag2" => count += 1,
+                _ => (),
+            }
+        },
+        Ok(Event::Text(e)) => txt.push(e.into_string()),
+        Err(e) => println!("{:?}", e),
+        _ => (),
+    }
+}
+```
+
+## Current state
+
+**quick-xml** has been written to be fast.
+
+On my first tests (200mb+ xmls) it performs much better (minimum 10x)
+ than [xml-rs](https://github.com/netvl/xml-rs).
+
+While this is a still WIP and only basic xml specifications are implemented, 
+you can already use it for simple enough xmls (no namespaces, no exotic 
+characters etc ...).
+
+This is particularly true when the xml is generated by a known source (e.g. OpenStreetMap).
+
+## Todo
+
+There are many xml specifications not implemented yet:
+- [ ] namespaces
+- [ ] non-utf8
+- [ ] parse xml prologue
+- [ ] XQuries ?
+- [ ] more checks
+- [ ] ... and many other things I don't even know!
+
+## Contribute
+
+Any PR is welcomed!
+
+I am not an expert in xml specifications, I simply have to work with big xmls. As a result, 
+I may not implement some basic functionalities, simply because I don't know/need them.
+

src/lib.rs

@@ -1,4 +1,35 @@
 //! Quick XmlReader reader which performs **very** well.
+//!
+//! # Example
+//!
+//! ```
+//! use quick_xml::{XmlReader, Event};
+//! 
+//! let xml = r#"<tag1 att1 = \"test\">
+//!                 <tag2><!--Test comment-->Test</b>
+//!                 <tag2>
+//!                     Test 2
+//!                 </tag2>
+//!             </tag1>"#;
+//! let reader = XmlReader::from_str(xml).trim_text(true);
+//! let mut count = 0;
+//! let mut txt = Vec::new();
+//! for r in reader {
+//!     match r {
+//!         Ok(Event::Start(ref e)) => {
+//!             match e.as_bytes() {
+//!                 b"a" => println!("attributes values: {:?}", 
+//!                                  e.attributes().map(|a| a.unwrap().1).collect::<Vec<_>>()),
+//!                 b"b" => count += 1,
+//!                 _ => (),
+//!             }
+//!         },
+//!         Ok(Event::Text(e)) => txt.push(e.into_string()),
+//!         Err(e) => println!("{:?}", e),
+//!         _ => (),
+//!     }
+//! }
+//! ```
 
 #[macro_use]
 extern crate log;

src/test.rs

@@ -125,13 +125,3 @@ fn test_nested() {
             );
 }
 
-#[test]
-fn test_html() {
-    let r = XmlReader::from_file("/home/johann/Downloads/Rust (programming language) - Wikipedia, the free encyclopedia.html")
-        .unwrap().trim_text(true);
-    let mut c = 0;
-    for e in r {
-        c += 1;
-        assert!(e.is_ok(), "{:?} at {}", e, c);
-    }
-}