code review 5575056: doc/go1: add net/url changes

doc/go1: add net/url changes

[niemeyer, 2012-01-25 03:17:05]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://go.googlecode.com/hg/

[bradfitz, 2012-01-25 03:22:23]

Need to edit the template file. Both that and generated HTML go in the CL.
 On Jan 24, 2012 7:17 PM, <n13m3y3r@gmail.com> wrote:

> Reviewers: golang-dev_googlegroups.com,
>
> Message:
> Hello golang-dev@googlegroups.com,
>
> I'd like you to review this change to
> https://go.googlecode.com/hg/
>
>
> Description:
> doc/go1: add net/url changes
>
> Please review this at
http://codereview.appspot.com/**5575056/<http://codereview.appspot.com/5575056/>
>
> Affected files:
>  M doc/go1.html
>
>
> Index: doc/go1.html
> ==============================**==============================**=======
> --- a/doc/go1.html
> +++ b/doc/go1.html
> @@ -1410,6 +1410,91 @@
>  or <code>panic</code> should be updated to use the new methods.
>  </p>
>
> +<h3 id="url">The url package</h3>
> +
> +<p>
> +In Go 1 the <a href="/net/url#URL"><code>url.**URL</code></a> type has
> +been simplified. The changes avoid duplication of information on
> +multiple fields and enable modifications made to an existing value
> +to have clear effects. More specific details follow.
> +</p>
> +
> +<p>
> +The <a href="/net/url#URL.String"><**code>String</code></a> method now
> +predictably rebuilds an encoded URL string using all of <code>URL</code>'s
> +fields as necessary. The resulting string will also no longer have
> +passwords escaped.
> +</p>
> +
> +<p>
> +The <code>Raw</code> field has been removed. In most cases the
> <code>String</code>
> +method may be used in its place.
> +</p>
> +
> +<p>
> +The <code>RawUserinfo</code> field was replaced by the <code>User</code>
> +field, of type <a href="/net/url#Userinfo"><**
> code>*net.Userinfo</code></a>.
> +Values of this type may be created using the new <a
> href="/net/url#User"><code>**net.User</code></a>
> +and <a href="/net/url#UserPassword"><**code>net.UserPassword</code></**a>
> +functions. Functions <code>EscapeUserinfo</code> and
> <code>UnescapeUserinfo</code>
> +that were used to manipulate the old field were removed too.
> +</p>
> +
> +<p>
> +The <code>RawAuthority</code> field has been removed. The same
> information is
> +available in the <code>Host</code> and <code>User</code> fields.
> +</p>
> +
> +<p>
> +The <code>RawPath</code> field and the <code>EncodedPath</code> method
> have
> +been removed. The path information in rooted URLs (with a slash following
> the
> +schema) is now available only in decoded form in the <code>Path</code>
> field.
> +In some less usual cases, the encoded data might be required to obtain
> +information that was lost in the decoding process. These cases must be
> handled
> +by accessing the data the URL was built from.
> +</p>
> +
> +<p>
> +URLs with non-rooted paths, such as <code>"mailto:dev@golang.org?**
> subject=Hi"</code>,
> +are also handled differently. The <code>OpaquePath</code> boolean field
> has been
> +removed and a new <code>Opaque</code> string field introduced to hold the
> encoded
> +path for such URLs. Also, the way in which these URLs are taken apart has
> changed.
> +Previously, the cited URL would parse as:
> +</p>
> +
> +<pre>
> +    URL{
> +        Raw: "mailto:dev@golang.org?**subject=Hi",
> +        Scheme: "mailto",
> +        OpaquePath: true,
> +        RawPath: "dev@golang.org?subject=Hi",
> +        Path:"dev@golang.org?subject=**Hi<http://dev@golang.org?subject=Hi>
> ",
> +    }
> +</pre>
> +
> +<p>
> +In Go 1, the same URL parses as:
> +</p>
> +
> +<pre>
> +    URL{
> +        Scheme: "mailto",
> +        Opaque: "dev@golang.org",
> +        RawQuery: "subject=Hi",
> +    }
> +</pre>
> +
> +<p>
> +A new <a href="/net/url#URL.RequestURI"**><code>RequestURI</code></a>
> method was
> +added to <code>URL</code>.
> +</p>
> +
> +<p>
> +<em>Updating</em>:
> +Code that uses the old fields will fail to compile and must be updated by
> hand.
> +The semantic changes make it difficult for gofix to update automatically.
> +</p>
> +
>  <h2 id="go_command">The go command</h2>
>
>  <h2 id="releases">Packaged releases</h2>
>
>
>

[niemeyer, 2012-01-25 03:31:22]

Hello golang-dev@googlegroups.com, bradfitz@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[r, 2012-01-25 18:11:46]

thanks. it's a bit long, but easy to make shorter.

the picture's a bit lost in all the prose. would it make sense to have a
executable example? that's a question, not a request.

http://codereview.appspot.com/5575056/diff/4002/doc/go1.tmpl
File doc/go1.tmpl (right):

http://codereview.appspot.com/5575056/diff/4002/doc/go1.tmpl#newcode1309
doc/go1.tmpl:1309: to have clear effects. More specific details follow.
delete most of this. this document does not need to justify, merely demonstrate

http://codereview.appspot.com/5575056/diff/4002/doc/go1.tmpl#newcode1325
doc/go1.tmpl:1325: The <code>RawUserinfo</code> field was replaced by the
<code>User</code>
s/The/The old/
s/was/is/

make sure it's all present tense. almost everyone reading this this will have Go
1 installed.

http://codereview.appspot.com/5575056/diff/4002/doc/go1.tmpl#newcode1330
doc/go1.tmpl:1330: that were used to manipulate the old field were removed too.
The EscapeUserInfo and UnescapeUserInfo functions are also gone.

http://codereview.appspot.com/5575056/diff/4002/doc/go1.tmpl#newcode1342
doc/go1.tmpl:1342: In some less usual cases, the encoded data might be required
to obtain
"In some less usual cases" isn't idiomatic.
maybe
Occasionally,
that also removes the duplication of 'cases'

http://codereview.appspot.com/5575056/diff/4002/doc/go1.tmpl#newcode1363
doc/go1.tmpl:1363: </pre>
delete how it used to work, or at least reduce it to a few words. we don't need
to document the old code

[niemeyer, 2012-01-25 22:37:39]

Hello golang-dev@googlegroups.com, bradfitz@golang.org, r@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[niemeyer, 2012-01-25 22:42:11]

> the picture's a bit lost in all the prose. would it make sense to have a
> executable example? that's a question, not a request.

I'm not entirely sure. A lot was removed, and it may be a bit hard to see what
is _not_ there in the example. I've fixed your requests, and will think about
that further.

[niemeyer, 2012-01-25 22:46:00]

Hello golang-dev@googlegroups.com, bradfitz@golang.org, r@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[r, 2012-01-26 00:37:55]

LGTM after fixing and testing links.
thanks

http://codereview.appspot.com/5575056/diff/8002/doc/go1.tmpl
File doc/go1.tmpl (right):

http://codereview.appspot.com/5575056/diff/8002/doc/go1.tmpl#newcode1306
doc/go1.tmpl:1306: In Go 1 several fields from the <a
href="/net/url#URL"><code>url.URL</code></a> type
hrefs are wrong.  i think you want /pkg/net/url/#URL in this case (note traliing
slash). compare with other examples.
i run a local godoc click all the links. painful but worthwhile

[niemeyer, 2012-01-26 01:11:34]

*** Submitted as http://code.google.com/p/go/source/detail?r=80e62792a44a ***

doc/go1: add net/url changes

R=golang-dev, bradfitz, r
CC=golang-dev
http://codereview.appspot.com/5575056