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>