code review 5654062: html/template: Added more explicit wording about exampl...

html/template: Added more explicit wording about examples and documentation.

[bjorn.tipling, 2012-02-11 19:25:35]

Hello golang-dev@googlegroups.com, I'd like you to review this change to https://go.googlecode.com/hg/

[bjorn.tipling, 2012-02-11 19:34:44]

On 2012/02/11 19:25:35, bjorn.tipling wrote: > Hello mailto:golang-dev@googlegroups.com, > > I'd like you to review this change to > https://go.googlecode.com/hg/ I thought some of the language in this part of the documentation was not explicit enough about when it was referring to text/template vs html/template. While you could simply assume that people reading the documentation for the html/template would know to also check text/template, I just thought it would be helpful and wouldn't hurt to add a line encouraging it.

[r, 2012-02-11 20:39:42]

http://codereview.appspot.com/5654062/diff/3002/src/pkg/html/template/doc.go File src/pkg/html/template/doc.go (right): http://codereview.appspot.com/5654062/diff/3002/src/pkg/html/template/doc.go#... src/pkg/html/template/doc.go:10: text/template documentation. good intention but we can be clearer and say, "use this". how about: Package template (html/template) implements data-driven templates for generating HTML output safe against code injection. It It provides the same interface as package text/template and should be used instead of text/template whenever the output is HTML. The documentation here focuses on the security features of the package. For information about how to program the templates themselves, see the documentation for text/template.

[bjorn.tipling, 2012-02-11 22:33:34]

Agreed that's even better. Adding this now. On 2012/02/11 20:39:42, r wrote: > http://codereview.appspot.com/5654062/diff/3002/src/pkg/html/template/doc.go > File src/pkg/html/template/doc.go (right): > > http://codereview.appspot.com/5654062/diff/3002/src/pkg/html/template/doc.go#... > src/pkg/html/template/doc.go:10: text/template documentation. > good intention but we can be clearer and say, "use this". > > how about: > > Package template (html/template) implements data-driven templates for generating > HTML output safe against code injection. It It provides the same interface as > package text/template and should be used instead of text/template whenever the > output is HTML. > > The documentation here focuses on the security features of the package. For > information about how to program the templates themselves, see the documentation > for text/template.

[bjorn.tipling, 2012-02-11 22:39:47]

Hello golang-dev@googlegroups.com, r@golang.org (cc: golang-dev@googlegroups.com), Please take another look.

[r, 2012-02-12 00:41:25]

one last tweak. http://codereview.appspot.com/5654062/diff/4003/src/pkg/html/template/doc.go File src/pkg/html/template/doc.go (right): http://codereview.appspot.com/5654062/diff/4003/src/pkg/html/template/doc.go#... src/pkg/html/template/doc.go:18: to safely parse and execute html templates. to parse and execute HTML templates safely.

[bjorn.tipling, 2012-02-12 01:03:14]

Hello golang-dev@googlegroups.com, r@golang.org (cc: golang-dev@googlegroups.com), Please take another look.

[bjorn.tipling, 2012-02-12 01:05:23]

Oh that is a split infinitive isn't it. Oops. On 2012/02/12 00:41:25, r wrote: > one last tweak. > > http://codereview.appspot.com/5654062/diff/4003/src/pkg/html/template/doc.go > File src/pkg/html/template/doc.go (right): > > http://codereview.appspot.com/5654062/diff/4003/src/pkg/html/template/doc.go#... > src/pkg/html/template/doc.go:18: to safely parse and execute html templates. > to parse and execute HTML templates safely.

[bjorn.tipling, 2012-02-12 01:05:46]

http://codereview.appspot.com/5654062/diff/3002/src/pkg/html/template/doc.go File src/pkg/html/template/doc.go (right): http://codereview.appspot.com/5654062/diff/3002/src/pkg/html/template/doc.go#... src/pkg/html/template/doc.go:10: text/template documentation. On 2012/02/11 20:39:42, r wrote: > good intention but we can be clearer and say, "use this". > > how about: > > Package template (html/template) implements data-driven templates for generating > HTML output safe against code injection. It It provides the same interface as > package text/template and should be used instead of text/template whenever the > output is HTML. > > The documentation here focuses on the security features of the package. For > information about how to program the templates themselves, see the documentation > for text/template. Done. http://codereview.appspot.com/5654062/diff/4003/src/pkg/html/template/doc.go File src/pkg/html/template/doc.go (right): http://codereview.appspot.com/5654062/diff/4003/src/pkg/html/template/doc.go#... src/pkg/html/template/doc.go:18: to safely parse and execute html templates. On 2012/02/12 00:41:26, r wrote: > to parse and execute HTML templates safely. Done.

[r2, 2012-02-12 01:17:10]

 On 12/02/2012, at 12:05 PM, bjorn.tipling@gmail.com wrote: > Oh that is a split infinitive isn't it. Oops. that's OK, it's the lower-case html and binding of 'safely' that wanted fixing. 

[r, 2012-02-12 01:17:27]

LGTM thanks

[r, 2012-02-12 01:18:07]

*** Submitted as http://code.google.com/p/go/source/detail?r=637fa427fef5 *** html/template: Added more explicit wording about examples and documentation. R=golang-dev, r, r CC=golang-dev http://codereview.appspot.com/5654062 Committer: Rob Pike <r@golang.org>