Update documentation

README.md

@@ -1,16 +1,13 @@
-PHP Domain Parser
-=================
+# PHP Domain Parser
 
 **PHP Domain Parser** is a [Public Suffix List](http://publicsuffix.org/) based
 domain parser implemented in PHP.
 
 [![Build Status](https://travis-ci.org/jeremykendall/php-domain-parser.png?branch=master)](https://travis-ci.org/jeremykendall/php-domain-parser)
-[![SensioLabsInsight](https://insight.sensiolabs.com/projects/13310245-48b5-43a2-ac30-269e059305e1/mini.png)](https://insight.sensiolabs.com/projects/13310245-48b5-43a2-ac30-269e059305e1)
 [![Total Downloads](https://poser.pugx.org/jeremykendall/php-domain-parser/downloads.png)](https://packagist.org/packages/jeremykendall/php-domain-parser)
 [![Latest Stable Version](https://poser.pugx.org/jeremykendall/php-domain-parser/v/stable.png)](https://packagist.org/packages/jeremykendall/php-domain-parser)
 
-Motivation
-----------
+## Motivation
 
 While there are plenty of excellent URL parsers and builders available, there
 are very few projects that can accurately parse a url into its component
@@ -20,13 +17,12 @@ Consider the domain www.pref.okinawa.jp.  In this domain, the
 *public suffix* portion is **okinawa.jp**, the *registerable domain* is
 **pref.okinawa.jp**, and the *subdomain* is **www**. You can't regex that.
 
-Other similar libraries focus primarily on URL building, parsing, and manipulation and
-additionally include public suffix domain parsing.  PHP Domain Parser was built around
-accurate Public Suffix List based parsing from the very beginning, adding a URL
-object simply for the sake of completeness.
+Other similar libraries focus primarily on URL building, parsing, and
+manipulation and additionally include public suffix domain parsing.  PHP Domain
+Parser was built around accurate Public Suffix List based parsing from the very
+beginning, adding a URL object simply for the sake of completeness.
 
-Installation
-------------
+## Installation
 
 The only (currently) supported method of installation is via
 [Composer](http://getcomposer.org).
@@ -53,10 +49,9 @@ require_once 'vendor/autoload.php'
 
 You're now ready to begin using the PHP Domain Parser.
 
-Usage
------
+## Usage
 
-### Parsing URLs ###
+### Parsing URLs
 
 Parsing URLs into their component parts is as simple as the example you see below.
 
@@ -104,8 +99,9 @@ class Pdp\Uri\Url#6 (8) {
 
 ### Convenience Methods
 
-A magic __get() method is provided to access the above object properties.  Obtaining the
-public suffix for a parsed domain is as simple as:
+A magic [`__get()`](http://php.net/manual/en/language.oop5.overloading.php#object.get) 
+method is provided to access the above object properties.  Obtaining the public
+suffix for a parsed domain is as simple as:
 
 ``` php
 <?php
@@ -120,8 +116,8 @@ $publicSuffix = $url->host->publicSuffix;
 ### IDNA Support
 
 [IDN (Internationalized Domain Name)](http://en.wikipedia.org/wiki/Internationalized_domain_name)
-support was added in version `1.4.0`. Both unicode domains and their ASCII equivalents
-are supported.
+support was added in version `1.4.0`. Both unicode domains and their ASCII
+equivalents are supported.
 
 **IMPORTANT**:
 
@@ -132,13 +128,13 @@ required for [mb_strtolower](http://php.net/manual/en/function.mb-strtolower.php
 
 #### Unicode
 
-Parsing IDNA hosts is no different that parsing standard hosts. Setting `$host = 'Яндекс.РФ';` (Russian-Cyrillic)
-in the *Parsing URLs* example would return:
+Parsing IDNA hosts is no different that parsing standard hosts. Setting `$host
+= 'Яндекс.РФ';` (Russian-Cyrillic) in the *Parsing URLs* example would return:
 
 ```
 class Pdp\Uri\Url#6 (8) {
   private $scheme =>
-  string(4) "http"
+  string(0) ""
   private $host =>
   class Pdp\Uri\Url\Host#5 (4) {
     private $subdomain =>
@@ -203,7 +199,8 @@ class Pdp\Uri\Url#6 (8) {
 
 ### IPv6 Support
 
-Parsing IPv6 hosts is no different that parsing standard hosts. Setting `$host = 'http://[2001:db8:85a3:8d3:1319:8a2e:370:7348]:8080/';`
+Parsing IPv6 hosts is no different that parsing standard hosts. Setting `$host
+= 'http://[2001:db8:85a3:8d3:1319:8a2e:370:7348]:8080/';`
 in the *Parsing URLs* example would return:
 
 ```
@@ -242,7 +239,7 @@ will not be parsed properly otherwise.
 > Hat tip to [@geekwright](https://github.com/geekwright) for adding IPv6 support in a
 > [bugfix pull request](https://github.com/jeremykendall/php-domain-parser/pull/35).
 
-### Parsing Domains ###
+### Parsing Domains
 
 If you'd like to parse the domain (or host) portion only, you can use
 `Parser::parseHost()`.
@@ -279,7 +276,8 @@ var_dump($parser->isSuffixValid('www.example.com.au');
 // true
 ```
 
-A suffix is considered invalid if it is not contained in the [Public Suffix List](http://publicsuffix.org/).
+A suffix is considered invalid if it is not contained in the 
+[Public Suffix List](http://publicsuffix.org/).
 
 > Huge thanks to [@SmellyFish](https://github.com/SmellyFish) for submitting
 > [Add a way to validate TLDs](https://github.com/jeremykendall/php-domain-parser/pull/36)
@@ -306,7 +304,7 @@ string(16) "scottwills.co.uk"
 string(5) "co.uk"
 ```
 
-### Sanity Check ###
+### Sanity Check
 
 You can quickly parse a url from the command line with the provided `parse`
 vendor binary.  From the root of your project, simply call:
@@ -318,7 +316,8 @@ $ ./vendor/bin/parse <url>
 If you pass a url to `parse`, that url will be parsed and the output printed
 to screen.
 
-If you do not pass a url, `http://user:pass@www.pref.okinawa.jp:8080/path/to/page.html?query=string#fragment` will be parsed and the output printed to screen.
+If you do not pass a url, `http://user:pass@www.pref.okinawa.jp:8080/path/to/page.html?query=string#fragment`
+will be parsed and the output printed to screen.
 
 Example:
 
@@ -342,12 +341,12 @@ Array
 Host: http://www.waxaudio.com.au/
 ```
 
-### Example Script ###
+### Example Script
 
 For more information on using the PHP Domain Parser, please see the provided
 [example script](https://github.com/jeremykendall/php-domain-parser/blob/master/example.php).
 
-### Refreshing the Public Suffix List ###
+### Refreshing the Public Suffix List
 
 While a cached PHP copy of the Public Suffix List is provided for you in the
 `data` directory, that copy may or may not be up to date (Mozilla provides an
@@ -367,13 +366,23 @@ You may verify the update by checking the timestamp on the files located in the
 **Important**: The vendor binary `update-psl` depends on an internet connection to
 update the cached Public Suffix List.
 
-Contributing
-------------
+## Possible Unexpected Behavior
+
+PHP Domain Parser is built around PHP's
+[`parse_url()`](http://php.net/parse_url) function and, as such, exhibits most
+of the same behaviors of that function. Just like `parse_url()`, this library
+is not meant to validate URLs, but rather to break a URL into its component
+parts.
+
+One specific, counterintuitive behavior is that PHP Domain Parser will happily 
+parse a URL with [spaces in the host part](https://github.com/jeremykendall/php-domain-parser/issues/45).
+
+## Contributing
 
 Pull requests are *always* welcome! Please review the CONTRIBUTING.md document before
 submitting pull requests.
 
-#### Heads up: BC Break In All 1.4 Versions
+## Heads up: BC Break In All 1.4 Versions
 
 The 1.4 series introduced a backwards incompatible change by adding PHP's `ext-mbstring`
 and `ext-intl` as dependencies.  This should have resulted in a major version
@@ -383,11 +392,10 @@ I highly recommend reverting to 1.3.1 if you're running into extension issues an
 do not want to or cannot install `ext-mbstring` and `ext-intl`. You will lose
 IDNA and IPv6 support, however.  Those are only available in versions >= 1.4.
 
-Version 2 is currently in the works.  Please keep an eye out.  I apologize for any
-issues you may have encountered due my [semver](http://semver.org/) error.
+I apologize for any issues you may have encountered due my 
+[semver](http://semver.org/) error.
 
-Attribution
------------
+## Attribution
 
 The HTTP adapter interface and the cURL HTTP adapter were inspired by (er,
 lifted from) Will Durand's excellent