code review 5569067: doc/go1: add encoding/xml changes

doc/go1: add encoding/xml changes

[niemeyer, 2012-01-26 01:20:19]

Hello golang-dev@googlegroups.com,

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

[r, 2012-01-26 01:52:34]

apologies for all the comments.

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl
File doc/go1.tmpl (right):

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1417
doc/go1.tmpl:1417: is similar to other marshaling packages, and its behavior has
been significantly
s/,//

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1418
doc/go1.tmpl:1418: improved.
"significantly improved" is editorial. simplified? made more regular?

i'd be happy with

In Go 1, the <a href="/pkg/encoding/xml/"><code>xml</code></a> package has been
brought closer in design to the other marshaling packages such as <a
href="/pkg/encoding/gob/"><code>encoding/gob</code></a>.

also don't forget the trailing slahses in the path. they avoid a redirection,
i'm told, and they're missing everywhere in this section

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1422
doc/go1.tmpl:1422: The <code>Parser</code> type is renamed to
The old <code>Parser</code> type is renamed 
(say "old", no "to").

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1439
doc/go1.tmpl:1439: tags have all been changed to follow the comma convention
s/all //
maybe say where else this is a convention, or better just say what it's like.
(json, right?) and don't say convention

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1442
doc/go1.tmpl:1442: simple. The XMLName field tag, if present, must also
necessarily match
what does 'simple' mean? drop it or explain, and i vote for drop.

<code> for XMLName

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1447
doc/go1.tmpl:1447: A number of other small improvements were done to the
marshaling and
s/done/made/
but i don't think this paragraph needs to be here

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1455
doc/go1.tmpl:1455: Gofix will update the API use in most cases, except for some
calls to
Gofix will update most uses of the package except for some calls to

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1456
doc/go1.tmpl:1456: <code>Unmarshal</code> that may have to be fixed by hand.
Special care
s/have/need/, except that 'most' already means 'some will need to be fixed, so
you can stop this sentence at the comma.

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1458
doc/go1.tmpl:1458: not fixed by hand they will misbehave silently in some cases.
E.g.
E.g. is not a word and certainly not a good sentence starter.  write it out:
For example,

http://codereview.appspot.com/5569067/diff/2002/doc/go1.tmpl#newcode1460
doc/go1.tmpl:1460: previous version is still valid and with a different meaning.
be clearer:
the old "attr" is now written ",attr", while plain "attr" remains valid but with
a different meaning.

[niemeyer, 2012-01-26 02:22:25]

On 2012/01/26 01:52:34, r wrote:
> apologies for all the comments.

No worries. The comments are welcome, even more when they come
with reasoning, as I may eventually catch up. Using
"A was renamed B" surprised me, for instance, but I guess it
makes sense given that "named B" is sound.

PTAL

[r, 2012-01-26 02:35:06]

LGTM
thanks

http://codereview.appspot.com/5569067/diff/6002/doc/go1.tmpl
File doc/go1.tmpl (right):

http://codereview.appspot.com/5569067/diff/6002/doc/go1.tmpl#newcode1442
doc/go1.tmpl:1442: names, and the XML attribute and element names is now case
sensitive.
s/case sensitive/case-sensitive/

http://codereview.appspot.com/5569067/diff/6002/doc/go1.tmpl#newcode1444
doc/go1.tmpl:1444: necessarily match the name of the XML element being
marshaled.
s/necessarily //
(must means that)

[niemeyer, 2012-01-26 02:59:57]

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

doc/go1: add encoding/xml changes

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