UPGRADING.md: add some line breaks.

About break placement:
http://rhodesmill.org/brandon/2012/one-sentence-per-line/

UPGRADING.md

@@ -1,10 +1,19 @@
 # Guide to upgrading from url 0.x to 1.x
 
-* The fields of `Url` are now private because the `Url` constructor, parser, and setters maintain invariants that could be violated if you were to set the fields directly. Instead of accessing, for example, `url.scheme`, use the getter method, such as `url.scheme()`. Instead of assigning directly to a field, for example `url.scheme = "https".to_string()`, use the setter method, such as `url.set_scheme("https").unwrap()` (the setters return a `Result` that must be used).
+* The fields of `Url` are now private because the `Url` constructor, parser,
+  and setters maintain invariants that could be violated if you were to set the fields directly.
+  Instead of accessing, for example, `url.scheme`, use the getter method, such as `url.scheme()`.
+  Instead of assigning directly to a field, for example `url.scheme = "https".to_string()`,
+  use the setter method, such as `url.set_scheme("https").unwrap()`
+  (the setters return a `Result` that must be used).
 
-* The methods of `Url` now return `&str` instead of `String`, thus reducing allocations and making serialization cheap.
+* The methods of `Url` now return `&str` instead of `String`,
+  thus reducing allocations and making serialization cheap.
 
-* The `path()` method on `url::Url` instances used to return `Option<&[String]>`; now it returns `&str`. If you would like functionality more similar to the old behavior of `path()`, use `path_segments()` that returns `Option<str::Split<char>>`.
+* The `path()` method on `url::Url` instances used to return `Option<&[String]>`;
+  now it returns `&str`.
+  If you would like functionality more similar to the old behavior of `path()`,
+  use `path_segments()` that returns `Option<str::Split<char>>`.
 
     Before upgrading:
 
@@ -24,7 +33,8 @@
         assert_eq!(issue_list_url.path_segments().map(|c| c.collect::<Vec<_>>()),
                    Some(vec!["rust-lang", "rust", "issues"]));
 
-* The `path_mut()` method on `url::Url` instances that allowed modification of a URL's path has been replaced by `path_segments_mut()`.
+* The `path_mut()` method on `url::Url` instances that allowed modification of a URL's path
+  has been replaced by `path_segments_mut()`.
 
     Before upgrading:
 
@@ -36,11 +46,16 @@
         let mut url = Url::parse("https://github.com/rust-lang/rust").unwrap();
         url.path_segments_mut().unwrap().push("issues");
 
-* The `domain_mut()` method on `url::Url` instances that allowed modification of a URL's domain has been replaced by `set_host()` and `set_ip_host()`.
+* The `domain_mut()` method on `url::Url` instances that allowed modification of a URL's domain
+  has been replaced by `set_host()` and `set_ip_host()`.
 
-* The `host()` method on `url::Url` instances used to return `Option<&Host>`; now it returns `Option<Host<&str>>`. The `serialize_host()` method that returned `Option<String>` has been replaced by the `host_str()` method that returns `Option<&str>`.
+* The `host()` method on `url::Url` instances used to return `Option<&Host>`;
+  now it returns `Option<Host<&str>>`.
+  The `serialize_host()` method that returned `Option<String>`
+  has been replaced by the `host_str()` method that returns `Option<&str>`.
 
-* The `serialize()` method on `url::Url` instances that returned `String` has been replaced by an `as_str()` method that returns `&str`.
+* The `serialize()` method on `url::Url` instances that returned `String`
+  has been replaced by an `as_str()` method that returns `&str`.
 
     Before upgrading:
 
@@ -66,7 +81,8 @@
         let css_url = this_document.join("../main.css").unwrap();
         assert_eq!(css_url.as_str(), "http://servo.github.io/rust-url/main.css");
 
-* `url::parse_path()` and `url::UrlParser::parse_path()` have been removed without replacement. As a workaround, you can give a base URL that you then ignore too `url::Url::parse()`.
+* `url::parse_path()` and `url::UrlParser::parse_path()` have been removed without replacement.
+  As a workaround, you can give a base URL that you then ignore too `url::Url::parse()`.
 
     Before upgrading:
 
@@ -83,7 +99,12 @@
         assert_eq!(with_path.query(), Some("q=42"));
         assert_eq!(with_path.fragment(), None);
 
-* The `url::form_urlencoded::serialize()` method has been replaced with the `url::form_urlencoded::Serializer` struct. Instead of calling `serialize()` with key/value pairs, create a new `Serializer` with a new string, call the `extend_pairs()` method on the `Serializer` instance with the key/value pairs as the argument, then call `finish()`.
+* The `url::form_urlencoded::serialize()` method
+  has been replaced with the `url::form_urlencoded::Serializer` struct.
+  Instead of calling `serialize()` with key/value pairs,
+  create a new `Serializer` with a new string,
+  call the `extend_pairs()` method on the `Serializer` instance with the key/value pairs as the argument,
+  then call `finish()`.
 
     Before upgrading:
 
@@ -97,7 +118,8 @@
             form.iter().map(|(k, v)| { (&k[..], &v[..]) })
         ).finish();
 
-* The `set_query_from_pairs()` method on `url::Url` instances that took key/value pairs has been replaced with `query_pairs_mut()`, which allows you to modify the `url::Url`'s query pairs.
+* The `set_query_from_pairs()` method on `url::Url` instances that took key/value pairs
+  has been replaced with `query_pairs_mut()`, which allows you to modify the `url::Url`'s query pairs.
 
     Before upgrading:
 
@@ -121,7 +143,12 @@
           pairs.iter().map(|&(k, v)| { (&k[..], &v[..]) })
         );
 
-* `url::SchemeData`, its variants `Relative` and `NonRelative`, and the struct `url::RelativeSchemeData` have been removed. Instead of matching on these variants to determine if you have a URL in a relative scheme such as HTTP versus a URL in a non-relative scheme as data, use the `cannot_be_a_base()` method to determine which kind you have.
+* `url::SchemeData`, its variants `Relative` and `NonRelative`,
+  and the struct `url::RelativeSchemeData` have been removed.
+  Instead of matching on these variants
+  to determine if you have a URL in a relative scheme such as HTTP
+  versus a URL in a non-relative scheme as data,
+  use the `cannot_be_a_base()` method to determine which kind you have.
 
     Before upgrading:
 
@@ -140,7 +167,12 @@
                                       data: {}", field, url)))
         }
 
-* The functions `url::whatwg_scheme_type_mapper()`, the `SchemeType` enum, and the `scheme_type_mapper()` method on `url::UrlParser` instances have been removed. `SchemeType` had a method for getting the `default_port()`; to replicate this functionality, use the method `port_or_known_default()` on `url::Url` instances. The `port_or_default()` method on `url::Url` instances has been removed; use `port_or_known_default()` instead.
+* The functions `url::whatwg_scheme_type_mapper()`, the `SchemeType` enum,
+  and the `scheme_type_mapper()` method on `url::UrlParser` instances have been removed.
+  `SchemeType` had a method for getting the `default_port()`;
+  to replicate this functionality, use the method `port_or_known_default()` on `url::Url` instances.
+  The `port_or_default()` method on `url::Url` instances has been removed;
+  use `port_or_known_default()` instead.
 
     Before upgrading:
 
@@ -158,20 +190,35 @@
                                     url.scheme())),
         };
 
-* The following formatting utilities have been removed without replacement; look at their linked previous implementations if you would like to replicate the functionality in your code:
+* The following formatting utilities have been removed without replacement;
+  look at their linked previous implementations
+  if you would like to replicate the functionality in your code:
   * [`url::format::PathFormatter`](https://github.com/servo/rust-url/pull/176/commits/9e759f18726c8e1343162922b87163d4dd08fe3c#diff-0bb16ac13b75e9b568fa4aff61b0e71dL24)
   * [`url::format::UserInfoFormatter`](https://github.com/servo/rust-url/pull/176/commits/9e759f18726c8e1343162922b87163d4dd08fe3c#diff-0bb16ac13b75e9b568fa4aff61b0e71dL50)
   * [`url::format::UrlNoFragmentFormatter`](https://github.com/servo/rust-url/pull/176/commits/9e759f18726c8e1343162922b87163d4dd08fe3c#diff-0bb16ac13b75e9b568fa4aff61b0e71dL70)
 
-* `url::percent_encoding::percent_decode()` used to have a return type of `Vec<u8>`; now it returns an iterator of decoded `u8` bytes that also implements `Into<Cow<u8>>`.
-
-* The `url::percent_encoding::EncodeSet` struct and constant instances used with `url::percent_encoding::percent_encode()` have been changed to structs that implement the trait `url::percent_encoding::EncodeSet`.
-  * `SIMPLE_ENCODE_SET`, `QUERY_ENCODE_SET`, `DEFAULT_ENCODE_SET`, and `USERINFO_ENCODE_SET` have the same behavior.
-  * `USERNAME_ENCODE_SET` and `PASSWORD_ENCODE_SET` have been removed; use `USERINFO_ENCODE_SET` instead.
-  * `HTTP_VALUE_ENCODE_SET` has been removed; an implementation of it in the new types can be found [in hyper's source](https://github.com/hyperium/hyper/blob/67436c5bf615cf5a55a71e32b788afef5985570e/src/header/parsing.rs#L131-L138) if you need to replicate this functionality in your code.
-  * `FORM_URLENCODED_ENCODE_SET` has been removed; instead, use the functionality in `url::form_urlencoded`.
+* `url::percent_encoding::percent_decode()` used to have a return type of `Vec<u8>`;
+  now it returns an iterator of decoded `u8` bytes that also implements `Into<Cow<u8>>`.
+
+* The `url::percent_encoding::EncodeSet` struct and constant instances
+  used with `url::percent_encoding::percent_encode()`
+  have been changed to structs that implement the trait `url::percent_encoding::EncodeSet`.
+  * `SIMPLE_ENCODE_SET`, `QUERY_ENCODE_SET`, `DEFAULT_ENCODE_SET`,
+    and `USERINFO_ENCODE_SET` have the same behavior.
+  * `USERNAME_ENCODE_SET` and `PASSWORD_ENCODE_SET` have been removed;
+    use `USERINFO_ENCODE_SET` instead.
+  * `HTTP_VALUE_ENCODE_SET` has been removed;
+    an implementation of it in the new types can be found [in hyper's source](
+    https://github.com/hyperium/hyper/blob/67436c5bf615cf5a55a71e32b788afef5985570e/src/header/parsing.rs#L131-L138)
+    if you need to replicate this functionality in your code.
+  * `FORM_URLENCODED_ENCODE_SET` has been removed;
+    instead, use the functionality in `url::form_urlencoded`.
   * `PATH_SEGMENT_ENCODE_SET` has been added for use on '/'-separated path segments.
 
-* `url::percent_encoding::percent_decode_to()` has been removed. Use `url::percent_encoding::percent_decode()` and manage pushing the results into a data structure yourself.
-* A number of `ParseError` variants have changed. [See the documentation for the current set](http://servo.github.io/rust-url/url/enum.ParseError.html).
-* `url::OpaqueOrigin::new()` and `url::Origin::UID(OpaqueOrigin)` have been replaced by `url::Origin::new_opaque()` and `url::Origin::Opaque(OpaqueOrigin)`, respectively.
+* `url::percent_encoding::percent_decode_to()` has been removed.
+  Use `url::percent_encoding::percent_decode()`
+  and manage pushing the results into a data structure yourself.
+* A number of `ParseError` variants have changed.
+  [See the documentation for the current set](http://servo.github.io/rust-url/url/enum.ParseError.html).
+* `url::OpaqueOrigin::new()` and `url::Origin::UID(OpaqueOrigin)`
+  have been replaced by `url::Origin::new_opaque()` and `url::Origin::Opaque(OpaqueOrigin)`, respectively.