Fix URI, Request target terminology.

[damooo]

As this crate stands for correctness, it is imperative to fix misleading terminology that is used through out the request-target handling documentation.

1. Use HttpRequestTarget instead of Uri, as it really handles only request target forms, not identity scheme in any way. This may be difficult, noting it is a breaking change. Can alias and deprecate though.
2. In documentation of current Uri struct, There is extensive use of absolute-uri/relative-uri dichotomy to show that, for absolute-uri it has port, scheme, etc, and for relative-uri it won't. This is grossly misleading. As this crate is not handling identifiers in the first place, there is no such thing as absolute-uri/relative-uri dichotomy. It is instead dichotomy of absolute-form/origin-form of request target. i.e, request-target in absolute-form encodes port, scheme etc, and that in origin-form doesn't, as they have to be runtime-resolved. That's also the reason the mis-termed relative-uris starts with a /, as they are not really identifiers, relative/absolute, but origin-form resource targets.

The second point of fixing documentation may not be breaking change, and possible i hope.

We can see many misunderstandings due to this misleading. for example

1. Get fragment of Uri #127, As These are not identifiers, but representation of request-target values, there is no uri, and thus no fragments in first place.
2. Parsing "http://localhost" as URI results in path_and_query: Some("/") #465 Same mis-issue of using request-target representation to represent identifiers
3. Cannot parse URI without authority component #469 They even mention other uri-schemes in issue discription, and also quotes uri-standard. Same mis-issue.
4. Interoperability with servo URL? #396 , url crate is for identifiers, where as this one only deals with request-targets.
5. URI parser cannot parse URNs #379 same issue. This crate doesn't handles uris in first place. only request targets.
6. The hyperium URI parser is stricter than the url crate #342
7. Uri parses "example.com" but fails to parse "example.com/foo" #311
8. parse::<Uri> fails to parse uris with triple slash after scheme #323
9. Correctly parse file URIs #421
10. Spec non-compliance inconsistency in URI parsing #306
11. Uri::path() and and Uri::path_and_query() have confusing semantics #176
12. Request "always" has a Uri #110

so on, so forth.
For amount of confusion, ad misleading it creates, It may be helpful to fix at least terminology in docs, and fix Uri name for struct before 1.0

see solid/specification#368

[KiloJuliett]

I agree that the current situation is untenable. The current name of Uri suggests that the struct can be all sorts of things that URIs and URLs can be, when in reality it's simply "the thing you use to specify an HTTP request target" nothing more. I personally think a lot of confusion can be saved by renaming Uri as stated above, despite the fact that this is a breaking change. Certainly would have saved me quite a bit.

[LukasKalbertodt]

Unfortunately, 1.0 was released without addressing this. So renaming Uri is out of the question for the foreseeable future, I assume. I still think that some of this confusion can be avoided by improving the docs.

I just stumbled over this issue, as I was confused by the whole situation again. It doesn't help that the docs mention the fragment in the syntax breakdown diagram, but nowhere else. Neither does the fact that parsing an URI with fragment succeeds but silently discards the fragment part.