FAQ
Hi everyone,

So having used Go for a few HTTP API and command line tool apps I really
enjoyed the quality of the language, the standard library, and the
documentation of both.

On the back of the successes with my earlier projects, I decided to use Go
as the backing language for a single page app our design agency had been
commissioned to build.

This project gave me my first real exposure to html/template and I don't
feel like the experience was up to the same quality as working with
net/http or encoding/json, which makes for a pretty wonky stool of
"building web applications"

With that said, I'd like to dive in and make a few changes to the library,
but want to discuss it here before I start writing any code as I don't want
to rustle any feathers or violate any of the standard library's design
guidelines.

## Improve documentation

First thing I want to do is overhaul the godoc comments through the package
to be more friendly to first time readers (and newer gophers), including a
wide range of example code blocks especially around nested templates and
FuncMaps

I'm not sure how general my experience was, but I found myself relying on
heavy googling, tutorial blog posts, and past discussions on golang-nuts to
get productive with the library ahead of the godocs.

## Stop Stripping HTML comments

I think html/template should stop stripping out html comments as they're
widely used in everyday web development, and until they're supported (or if
they never get supported) the documentation should make it abundantly clear
that they are removed.

The rationale for them being stripped out was mostly discussed in
https://groups.google.com/forum/#!msg/golang-nuts/8y6by6SERyU/XQRnbw3aBhwJ
html/template strips comments because analysis of one codebase showed
that comments often contained code that the template authors had
disabled or contained comments that template authors intended for
reviewers and maintainers and did not intend to expose to larger
audiences, and because properly handling HTML <!--[...]-->, JS /
*@cc_on ... */, and CSS's occasionally nesting comments properly
requires introducing output-language-specific conditional constructs
which is just a headache. Instead I decided just to handle the core
languages.

I think the use cases for html comments are wider and more common than Mike
suggests. The three major ones that spring to mind are:

* IE conditional comments (examples of them sanely used below)
   - Html5 Boilerplate
http://knockoutjs.com/documentation/foreach-binding.html
   - Bootstrap for html5 shims
   - fallbacks for responsive image loading techniques (to get full browser
support you can end up using an unholy combination of noscript tags
containing img tags, conditional comments, and a bunch of gnarly javascript)
* Javascript library hooks. eg the cointainerless iteration example at
http://knockoutjs.com/documentation/foreach-binding.html
* Outputting debug information from the application server. I don't have
external documentation supporting this, but I often run HTTP health checks
against content in html comments as it remains constant regardless of
design changes

I can see why dealing with HTML/JS/CSS comments would be a real pain in
implementation, but I think it's worth the effort and am happy to make that
effort myself.

The workaround as it stands now (as the noescape solution usually suggested
no longer works) is to create your own version of noescape returning a
template.HTML value and add it to your own FuncMap which you set on your
template. That seems to be an unnecessary amount of boilerplate/overhead
for very common use cases, not to mention that it makes for uglier
templates.

## Add a default FuncMap for templates

I think the noescape method that used to be an undocumented part of
html/template was quite handy, but looking at the commit that pulled it out
I can see why the implementation didn't have any supporters.

I'd like to propose a default FuncMap for the package including a
newer/better implementation of noescape and maybe one or two other helper
functions, that is used in a similar way to the default muxer in net/http
where it is on by default, but clearly separate and easy to swap out for
your preferred implementation.

---

Are any/all of these proposals sensible? Please let me know your thoughts
and I'll get cracking on whichever of these people think are worth working
on.

Cheers,
John

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

Search Discussions

  • John Barton at Feb 9, 2014 at 1:04 am
    Hi Josh/Mike/Rob/Nigel/Francesc,

    I'm just cc'ing you in on the proposal below as I've fished your emails out of the mercurial log for the html/template package and would appreciate any feedback, and if the reaction's positive I'll try and spend as much of the second half of my holiday working on it.

    Cheers,
    John
    From: John Barton John Barton
    Reply: John Barton jrbarton@gmail.com
    Date: 6 February 2014 at 3:25:41 pm
    To: golang-nuts@googlegroups.com golang-nuts@googlegroups.com
    Subject:  [go-nuts] Proposed changes to html/template package around documentation, html comments and noescape
    Hi everyone,

    So having used Go for a few HTTP API and command line tool apps I really enjoyed the quality of the language, the standard library, and the documentation of both.

    On the back of the successes with my earlier projects, I decided to use Go as the backing language for a single page app our design agency had been commissioned to build.

    This project gave me my first real exposure to html/template and I don't feel like the experience was up to the same quality as working with net/http or encoding/json, which makes for a pretty wonky stool of "building web applications"

    With that said, I'd like to dive in and make a few changes to the library, but want to discuss it here before I start writing any code as I don't want to rustle any feathers or violate any of the standard library's design guidelines.

    ## Improve documentation

    First thing I want to do is overhaul the godoc comments through the package to be more friendly to first time readers (and newer gophers), including a wide range of example code blocks especially around nested templates and FuncMaps

    I'm not sure how general my experience was, but I found myself relying on heavy googling, tutorial blog posts, and past discussions on golang-nuts to get productive with the library ahead of the godocs.

    ## Stop Stripping HTML comments

    I think html/template should stop stripping out html comments as they're widely used in everyday web development, and until they're supported (or if they never get supported) the documentation should make it abundantly clear that they are removed.

    The rationale for them being stripped out was mostly discussed in https://groups.google.com/forum/#!msg/golang-nuts/8y6by6SERyU/XQRnbw3aBhwJ
    html/template strips comments because analysis of one codebase showed
    that comments often contained code that the template authors had
    disabled or contained comments that template authors intended for
    reviewers and maintainers and did not intend to expose to larger
    audiences, and because properly handling HTML <!--[...]-->, JS /
    *@cc_on ... */, and CSS's occasionally nesting comments properly
    requires introducing output-language-specific conditional constructs
    which is just a headache.  Instead I decided just to handle the core languages.
    I think the use cases for html comments are wider and more common than Mike suggests. The three major ones that spring to mind are:

    * IE conditional comments (examples of them sanely used below)
      - Html5 Boilerplate http://knockoutjs.com/documentation/foreach-binding.html
      - Bootstrap for html5 shims
      - fallbacks for responsive image loading techniques (to get full browser support you can end up using an unholy combination of noscript tags containing img tags, conditional comments, and a bunch of gnarly javascript)
    * Javascript library hooks. eg the cointainerless iteration example at http://knockoutjs.com/documentation/foreach-binding.html
    * Outputting debug information from the application server. I don't have external documentation supporting this, but I often run HTTP health checks against content in html comments as it remains constant regardless of design changes

    I can see why dealing with HTML/JS/CSS comments would be a real pain in implementation, but I think it's worth the effort and am happy to make that effort myself.

    The workaround as it stands now (as the noescape solution usually suggested no longer works) is to create your own version of noescape returning a template.HTML value and add it to your own FuncMap which you set on your template. That seems to be an unnecessary amount of boilerplate/overhead for very common use cases, not to mention that it makes for uglier templates.

    ## Add a default FuncMap for templates

    I think the noescape method that used to be an undocumented part of html/template was quite handy, but looking at the commit that pulled it out I can see why the implementation didn't have any supporters.

    I'd like to propose a default FuncMap for the package including a newer/better implementation of noescape and maybe one or two other helper functions, that is used in a similar way to the default muxer in net/http where it is on by default, but clearly separate and easy to swap out for your preferred implementation.

    ---

    Are any/all of these proposals sensible? Please let me know your thoughts and I'll get cracking on whichever of these people think are worth working on.

    Cheers,
    John
    --
    You received this message because you are subscribed to a topic in the Google Groups "golang-nuts" group.
    To unsubscribe from this topic, visit https://groups.google.com/d/topic/golang-nuts/BXiIwHtkW1A/unsubscribe.
    To unsubscribe from this group and all its topics, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Josh Bleecher Snyder at Feb 9, 2014 at 5:29 pm
    Hi John,

    I am at best a bystander for html/template, but I will offer some
    general advice, and hope that I don't lead you astray.

    ## Improve documentation
    Improved docs are always welcome. However, if you're thinking about an
    overhaul rather than small tweaks, I'd suggest first opening an issue
    (golang.org/issue/new) and describing at a high level what problem
    you're solving (where/why do people get lost?) and the proposed new
    approach. Post a link to the issue here once you've created it.

    If there's resistance to a documentation overhaul, you could also
    write your own blog post, containing the New Definitive Guide to
    html/text, and share it here. The Gopher Academy might also be
    interested in publishing such a guide. No matter how perfect the docs,
    a broad, flourishing ecosystem of extra materials in blogs, mailing
    lists, SO, etc. is incredibly valuable. (As an example, I find myself
    directing almost all new gophers to read
    http://dave.cheney.net/2013/01/19/what-is-the-zero-value-and-why-is-it-useful
    at some point.)

    ## Stop Stripping HTML comments
    File an issue; post the link here. Be sure to lay out why the previous
    decision was wrong and how to address all the concerns that led to the
    previous decision in your proposed new design.

    I'll point out in passing that it appears to me that you've so far
    addressed only one and a half of the three concerns from the quoted
    passage.

    * Concern one (addressed): No legit use cases; you've provided some.
    * Concern two (half-addressed): Difficulty of implementation. You've
    offered to implement. However, difficult implementations also reduce
    readability and create a maintenance burden.
    * Concern three (not addressed): Exposing comments will frequently
    leak information that should not be leaked. From the quote: "comments
    often contained code ... template authors intended for reviewers and
    maintainers and did not intend to expose to larger audiences".
    Additionally, note that changing default behavior will now leak
    information that was previously safely private.

    ## Add a default FuncMap for templates
    Interesting. File an issue; post the link back here. :)


    Hope that helps; sorry I could not provide concrete answers. And
    thanks in advance for any contributions to the community, wherever they are.

    -josh


    On Sat, Feb 8, 2014 at 5:04 PM, John Barton wrote:
    Hi Josh/Mike/Rob/Nigel/Francesc,

    I'm just cc'ing you in on the proposal below as I've fished your emails out
    of the mercurial log for the html/template package and would appreciate any
    feedback, and if the reaction's positive I'll try and spend as much of the
    second half of my holiday working on it.

    Cheers,
    John
    ________________________________
    From: John Barton John Barton
    Reply: John Barton jrbarton@gmail.com
    Date: 6 February 2014 at 3:25:41 pm
    To: golang-nuts@googlegroups.com golang-nuts@googlegroups.com
    Subject: [go-nuts] Proposed changes to html/template package around
    documentation, html comments and noescape

    Hi everyone,

    So having used Go for a few HTTP API and command line tool apps I really
    enjoyed the quality of the language, the standard library, and the
    documentation of both.

    On the back of the successes with my earlier projects, I decided to use Go
    as the backing language for a single page app our design agency had been
    commissioned to build.

    This project gave me my first real exposure to html/template and I don't
    feel like the experience was up to the same quality as working with net/http
    or encoding/json, which makes for a pretty wonky stool of "building web
    applications"

    With that said, I'd like to dive in and make a few changes to the library,
    but want to discuss it here before I start writing any code as I don't want
    to rustle any feathers or violate any of the standard library's design
    guidelines.

    ## Improve documentation

    First thing I want to do is overhaul the godoc comments through the package
    to be more friendly to first time readers (and newer gophers), including a
    wide range of example code blocks especially around nested templates and
    FuncMaps

    I'm not sure how general my experience was, but I found myself relying on
    heavy googling, tutorial blog posts, and past discussions on golang-nuts to
    get productive with the library ahead of the godocs.

    ## Stop Stripping HTML comments

    I think html/template should stop stripping out html comments as they're
    widely used in everyday web development, and until they're supported (or if
    they never get supported) the documentation should make it abundantly clear
    that they are removed.

    The rationale for them being stripped out was mostly discussed in
    https://groups.google.com/forum/#!msg/golang-nuts/8y6by6SERyU/XQRnbw3aBhwJ
    html/template strips comments because analysis of one codebase showed
    that comments often contained code that the template authors had
    disabled or contained comments that template authors intended for
    reviewers and maintainers and did not intend to expose to larger
    audiences, and because properly handling HTML <!--[...]-->, JS /
    *@cc_on ... */, and CSS's occasionally nesting comments properly
    requires introducing output-language-specific conditional constructs
    which is just a headache. Instead I decided just to handle the core
    languages.
    I think the use cases for html comments are wider and more common than Mike
    suggests. The three major ones that spring to mind are:

    * IE conditional comments (examples of them sanely used below)
    - Html5 Boilerplate
    http://knockoutjs.com/documentation/foreach-binding.html
    - Bootstrap for html5 shims
    - fallbacks for responsive image loading techniques (to get full browser
    support you can end up using an unholy combination of noscript tags
    containing img tags, conditional comments, and a bunch of gnarly javascript)
    * Javascript library hooks. eg the cointainerless iteration example at
    http://knockoutjs.com/documentation/foreach-binding.html
    * Outputting debug information from the application server. I don't have
    external documentation supporting this, but I often run HTTP health checks
    against content in html comments as it remains constant regardless of design
    changes

    I can see why dealing with HTML/JS/CSS comments would be a real pain in
    implementation, but I think it's worth the effort and am happy to make that
    effort myself.

    The workaround as it stands now (as the noescape solution usually suggested
    no longer works) is to create your own version of noescape returning a
    template.HTML value and add it to your own FuncMap which you set on your
    template. That seems to be an unnecessary amount of boilerplate/overhead for
    very common use cases, not to mention that it makes for uglier templates.

    ## Add a default FuncMap for templates

    I think the noescape method that used to be an undocumented part of
    html/template was quite handy, but looking at the commit that pulled it out
    I can see why the implementation didn't have any supporters.

    I'd like to propose a default FuncMap for the package including a
    newer/better implementation of noescape and maybe one or two other helper
    functions, that is used in a similar way to the default muxer in net/http
    where it is on by default, but clearly separate and easy to swap out for
    your preferred implementation.

    ---

    Are any/all of these proposals sensible? Please let me know your thoughts
    and I'll get cracking on whichever of these people think are worth working
    on.

    Cheers,
    John
    --
    You received this message because you are subscribed to a topic in the
    Google Groups "golang-nuts" group.
    To unsubscribe from this topic, visit
    https://groups.google.com/d/topic/golang-nuts/BXiIwHtkW1A/unsubscribe.
    To unsubscribe from this group and all its topics, send an email to
    golang-nuts+unsubscribe@googlegroups.com.

    For more options, visit https://groups.google.com/groups/opt_out.
    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Mike Samuel at Feb 10, 2014 at 7:55 pm

    2014-02-08 20:04 GMT-05:00 John Barton <jrbarton@gmail.com>:
    So having used Go for a few HTTP API and command line tool apps I really
    enjoyed the quality of the language, the standard library, and the
    documentation of both.

    On the back of the successes with my earlier projects, I decided to use Go
    as the backing language for a single page app our design agency had been
    commissioned to build.

    This project gave me my first real exposure to html/template and I don't
    feel like the experience was up to the same quality as working with net/http
    or encoding/json, which makes for a pretty wonky stool of "building web
    applications"
    With that said, I'd like to dive in and make a few changes to the library,
    but want to discuss it here before I start writing any code as I don't want
    to rustle any feathers or violate any of the standard library's design
    guidelines.

    ## Improve documentation

    First thing I want to do is overhaul the godoc comments through the package
    to be more friendly to first time readers (and newer gophers), including a
    wide range of example code blocks especially around nested templates and
    FuncMaps

    I'm not sure how general my experience was, but I found myself relying on
    heavy googling, tutorial blog posts, and past discussions on golang-nuts to
    get productive with the library ahead of the godocs.
    Improving the godocs sounds like a great idea.

    Was the relationship between html/template and text/template clear
    when you were diving in?

    Do the examples in text/template answer questions that don't relate
    specifically to HTML?



    ## Stop Stripping HTML comments

    I think html/template should stop stripping out html comments as they're
    widely used in everyday web development, and until they're supported (or if
    they never get supported) the documentation should make it abundantly clear
    that they are removed.

    The rationale for them being stripped out was mostly discussed in
    https://groups.google.com/forum/#!msg/golang-nuts/8y6by6SERyU/XQRnbw3aBhwJ
    html/template strips comments because analysis of one codebase showed
    that comments often contained code that the template authors had
    disabled or contained comments that template authors intended for
    reviewers and maintainers and did not intend to expose to larger
    audiences, and because properly handling HTML <!--[...]-->, JS /
    *@cc_on ... */, and CSS's occasionally nesting comments properly
    requires introducing output-language-specific conditional constructs
    which is just a headache. Instead I decided just to handle the core
    languages.
    I think the use cases for html comments are wider and more common than Mike
    suggests. The three major ones that spring to mind are:

    * IE conditional comments (examples of them sanely used below)
    - Html5 Boilerplate
    http://knockoutjs.com/documentation/foreach-binding.html
    - Bootstrap for html5 shims
    - fallbacks for responsive image loading techniques (to get full browser
    support you can end up using an unholy combination of noscript tags
    containing img tags, conditional comments, and a bunch of gnarly javascript)
    * Javascript library hooks. eg the cointainerless iteration example at
    http://knockoutjs.com/documentation/foreach-binding.html
    * Outputting debug information from the application server. I don't have
    external documentation supporting this, but I often run HTTP health checks
    against content in html comments as it remains constant regardless of design
    changes

    I can see why dealing with HTML/JS/CSS comments would be a real pain in
    implementation, but I think it's worth the effort and am happy to make that
    effort myself.

    The workaround as it stands now (as the noescape solution usually suggested
    no longer works) is to create your own version of noescape returning a
    template.HTML value and add it to your own FuncMap which you set on your
    template. That seems to be an unnecessary amount of boilerplate/overhead for
    very common use cases, not to mention that it makes for uglier templates.
    Which of these use cases are not satisfied by typed strings?
    https://godoc.org/html/template#hdr-Typed_Strings

    ## Add a default FuncMap for templates

    I think the noescape method that used to be an undocumented part of
    html/template was quite handy, but looking at the commit that pulled it out
    I can see why the implementation didn't have any supporters.

    I'd like to propose a default FuncMap for the package including a
    newer/better implementation of noescape and maybe one or two other helper
    functions, that is used in a similar way to the default muxer in net/http
    where it is on by default, but clearly separate and easy to swap out for
    your preferred implementation.
    If you have a taxonomy of reasons to use noescape in mind, maybe we
    could see whether library fixes would allow a better solution than
    making it easier to sprinkle noescape around templates.

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Jimmy frasche at Feb 10, 2014 at 8:30 pm

    On Mon, Feb 10, 2014 at 11:55 AM, Mike Samuel wrote:
    Which of these use cases are not satisfied by typed strings?
    https://godoc.org/html/template#hdr-Typed_Strings
    The only thing typed strings don't really work well for is types that
    know how to render themselves but are not strings. I think adding
    something analogous to Stringer, say,

    type HTMLer interface {
         HTML() string
    }

    would be a good addition. Currently you need to put a method like
    HTML() template.HTML on the object and invoke that like:

    {{.LoginForm.HTML}}

    instead of just:

    {{.LoginForm}}

    Since it's just an interface, it could be supported by many
    render-to-html template packages without having to import
    html/template to get the HTML type for compatibility with
    html/template.

    I suppose you could make the argument for similar interfaces for
    HTMLAttr and the like, but this covers the most common use case of "I
    know how to render myself".

    It's a minor nit, but I think it would be an improvement.

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Mike Samuel at Feb 10, 2014 at 9:45 pm

    2014-02-10 15:30 GMT-05:00 jimmy frasche <soapboxcicero@gmail.com>:
    On Mon, Feb 10, 2014 at 11:55 AM, Mike Samuel wrote:
    Which of these use cases are not satisfied by typed strings?
    https://godoc.org/html/template#hdr-Typed_Strings
    The only thing typed strings don't really work well for is types that
    know how to render themselves but are not strings. I think adding
    something analogous to Stringer, say,

    type HTMLer interface {
    HTML() string
    }

    would be a good addition. Currently you need to put a method like
    HTML() template.HTML on the object and invoke that like:

    {{.LoginForm.HTML}}

    instead of just:

    {{.LoginForm}}

    Since it's just an interface, it could be supported by many
    render-to-html template packages without having to import
    html/template to get the HTML type for compatibility with
    html/template.

    I suppose you could make the argument for similar interfaces for
    HTMLAttr and the like, but this covers the most common use case of "I
    know how to render myself".

    It's a minor nit, but I think it would be an improvement.
    I like the idea.

    John, would that address some of your concerns?

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • John Barton at Feb 11, 2014 at 7:51 pm
    So I've fallen a bit behind on responding to the emails individually so I'll just try and address all the major points.

    Jimmy/Mike: On the HTMLer interface - I like that quite a bit, and I think reduces the reasoning for bringing noescape/adding a default func map quite a bit.

    Daniel/Mike: Re documentation.

    My main issue with the documentation isn't that there isn't enough of it, or that it's not accurate, but that I think it'd be better to target it to the audience a little better (especially the preamble section). This bit is all opinion :)

    The "average" web developer picking up a new language (I think) will typically follow this workflow

    * play with a tiny app that will spit out "Hello World" and 200 OK
    * try and figure out how to render a template instead of munge strings themselves
    * try and figure out how to move data from their backend into the template (ie something they've pulled out of a db/off an API), then how to iterate over collections of the same things, and maybe some basic conditionals
    * decide that now they need N different pages, and try and work out how to do layouts/nested templates/whatever their last language calls that

    So the biggest change I'd like to make to the docs is (before sending the user off to read a different document) to address those basic use cases straight up, then explain that go's template rending is more powerful/richer than that by quite a margin and that to learn more refer to text/template

    Mike/Josh: about the deletion of HTML comments

    Josh you're right I didn't explicitly answer all of Mike's original points, I'll do so here.

    * no legit use cases

    OK I did address that one

    * implementation complexity (ie difficult implementation creates maintenance burden)

    I've got two things to say about that. The first is that I'm happy to iterate with review until the implementation becomes sane, and abandon ship if it's completely unachievable, but knowing that it would be a lot of work I didn't want to start unless it has a chance of being accepted (if it meets the quality bar) The second is that some implementation complexity may be unavoidable, but that in terms of total software complexity in the eco system - it's better to have one tough bit of a very commonly used library than hundreds/thousands of different ways to work around a library shortcoming out in everyone else's apps.

    * Leaking information that shouldn't be leaked

    I didn't address that argument because I believe it to be specious. Of every templating system I've worked with (at least, but not limited to ERB & HAML in ruby, asp.net, php, perl) I've never had my content placed in a template surprisingly removed on me.

    Within my experience, almost every web site/app I've built has a legitimate need for html comments, and when I've put them there, they stay. Mike mentions a survey of one web app, I'm suggesting a survey of the lets say 50ish I've worked on over the past 10 years - between product company work, agency work, and hobby products.

    At the very least, html/template removing them (without the package docs saying so) violates the principle of least surprise, which the docs suggest the package follows. Mike rightly points out that it can be worked around, but I think that users shouldn't need to.

    I've got to run into a conference session right now, will add a bit more this afternoon.

    Cheers,
    John



    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Rob Pike at Feb 11, 2014 at 9:15 pm
    I have been planning to write a tour for the template package. I've
    actually started on one, but it's hard. I want to finish it for 1.3.
    If that exists, much of what you're asking for is addressed. I would
    prefer not to turn the package comment for either template package
    into book-length material.

    See also issue 4338.
    On Tue, Feb 11, 2014 at 11:50 AM, John Barton wrote:
    So I've fallen a bit behind on responding to the emails individually so I'll
    just try and address all the major points.

    Jimmy/Mike: On the HTMLer interface - I like that quite a bit, and I think
    reduces the reasoning for bringing noescape/adding a default func map quite
    a bit.

    Daniel/Mike: Re documentation.

    My main issue with the documentation isn't that there isn't enough of it, or
    that it's not accurate, but that I think it'd be better to target it to the
    audience a little better (especially the preamble section). This bit is all
    opinion :)

    The "average" web developer picking up a new language (I think) will
    typically follow this workflow

    * play with a tiny app that will spit out "Hello World" and 200 OK
    * try and figure out how to render a template instead of munge strings
    themselves
    * try and figure out how to move data from their backend into the template
    (ie something they've pulled out of a db/off an API), then how to iterate
    over collections of the same things, and maybe some basic conditionals
    * decide that now they need N different pages, and try and work out how to
    do layouts/nested templates/whatever their last language calls that

    So the biggest change I'd like to make to the docs is (before sending the
    user off to read a different document) to address those basic use cases
    straight up, then explain that go's template rending is more powerful/richer
    than that by quite a margin and that to learn more refer to text/template

    Mike/Josh: about the deletion of HTML comments

    Josh you're right I didn't explicitly answer all of Mike's original points,
    I'll do so here.

    * no legit use cases

    OK I did address that one

    * implementation complexity (ie difficult implementation creates maintenance
    burden)

    I've got two things to say about that. The first is that I'm happy to
    iterate with review until the implementation becomes sane, and abandon ship
    if it's completely unachievable, but knowing that it would be a lot of work
    I didn't want to start unless it has a chance of being accepted (if it meets
    the quality bar) The second is that some implementation complexity may be
    unavoidable, but that in terms of total software complexity in the eco
    system - it's better to have one tough bit of a very commonly used library
    than hundreds/thousands of different ways to work around a library
    shortcoming out in everyone else's apps.

    * Leaking information that shouldn't be leaked

    I didn't address that argument because I believe it to be specious. Of every
    templating system I've worked with (at least, but not limited to ERB & HAML
    in ruby, asp.net, php, perl) I've never had my content placed in a template
    surprisingly removed on me.

    Within my experience, almost every web site/app I've built has a legitimate
    need for html comments, and when I've put them there, they stay. Mike
    mentions a survey of one web app, I'm suggesting a survey of the lets say
    50ish I've worked on over the past 10 years - between product company work,
    agency work, and hobby products.

    At the very least, html/template removing them (without the package docs
    saying so) violates the principle of least surprise, which the docs suggest
    the package follows. Mike rightly points out that it can be worked around,
    but I think that users shouldn't need to.

    I've got to run into a conference session right now, will add a bit more
    this afternoon.

    Cheers,
    John



    --
    You received this message because you are subscribed to the Google Groups
    "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an
    email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Benjamin Measures at Feb 13, 2014 at 12:43 am

    On Tuesday, 11 February 2014 19:50:49 UTC, John Barton wrote:
    * Leaking information that shouldn't be leaked

    I didn't address that argument because I believe it to be specious. Of
    every templating system I've worked with (at least, but not limited to ERB
    & HAML in ruby, asp.net, php, perl) I've never had my content placed in a
    template surprisingly removed on me.

    Within my experience, almost every web site/app I've built has a
    legitimate need for html comments, and when I've put them there, they stay.
    Mike mentions a survey of one web app, I'm suggesting a survey of the lets
    say 50ish I've worked on over the past 10 years - between product company
    work, agency work, and hobby products.
    The rational for stripping comments wasn't that there wasn't "a legitimate
    need" but that "comments will frequently leak information that should not
    be leaked."

    Take, for example, the one and only comment on your site http://goodfil.ms/:
    <!--
    debug info
    goodfilms-app-three

    /repos/b
    926b52f839b140714dad9af88cbc43767949e2ce

    2014-02-13 00:21:42 +0000
    -->

    This is the sort of information that shouldn't go into production, and
    something a "security by default" stance would try to avoid.

    At the very least, html/template removing them (without the package docs
    saying so) violates the principle of least surprise
    With security in mind, taking steps to avoid information disclosure isn't
    particularly surprising.

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • John Barton at Feb 14, 2014 at 12:32 am
    I still argue that comments don't frequently leak information that should not be leaked, and even if it does up to a point, that the balance is still in favour of the legitimate use cases.

    Goodfilms is an interesting example, as instead of having a responsive site we do user agent sniffing and redirect to a separate mobile app. The comment you reference is production only information that I willingly exposed for its usefulness in debugging production issues (especially around caching + code reloading issues), and I don't believe it presents any meaningful security risk.

    If you check out out portfolio site http://codename.io/, which is just flat HTML (ie nothing to debug) and designed to be responsive, you'll see 100% the opposite - we use comments for IE and don't expose any debugging information.

    The docs explicitly mention that the template authors are trusted and that Execute's data parameter is not. Given that, it's not surprising that anything injected into a template is altered for security reasons, but very surprising that something in the actual template is removed/modified.

    From: Benjamin Measures Benjamin Measures
    Reply: Benjamin Measures saint.abroad@gmail.com
    Date: 13 February 2014 at 1:43:45 pm
    To: golang-nuts@googlegroups.com golang-nuts@googlegroups.com
    Subject:  Re: [go-nuts] Proposed changes to html/template package around documentation, html comments and noescape
    On Tuesday, 11 February 2014 19:50:49 UTC, John Barton wrote:
    * Leaking information that shouldn't be leaked

    I didn't address that argument because I believe it to be specious. Of every templating system I've worked with (at least, but not limited to ERB & HAML in ruby, asp.net, php, perl) I've never had my content placed in a template surprisingly removed on me.

    Within my experience, almost every web site/app I've built has a legitimate need for html comments, and when I've put them there, they stay. Mike mentions a survey of one web app, I'm suggesting a survey of the lets say 50ish I've worked on over the past 10 years - between product company work, agency work, and hobby products.

    The rational for stripping comments wasn't that there wasn't "a legitimate need" but that "comments will frequently leak information that should not be leaked."

    Take, for example, the one and only comment on your site http://goodfil.ms/:
    <!--
    debug info
    goodfilms-app-three

    /repos/b
    926b52f839b140714dad9af88cbc43767949e2ce

    2014-02-13 00:21:42 +0000
    -->

    This is the sort of information that shouldn't go into production, and something a "security by default" stance would try to avoid.

    At the very least, html/template removing them (without the package docs saying so) violates the principle of least surprise

    With security in mind, taking steps to avoid information disclosure isn't particularly surprising.
    --
    You received this message because you are subscribed to a topic in the Google Groups "golang-nuts" group.
    To unsubscribe from this topic, visit https://groups.google.com/d/topic/golang-nuts/BXiIwHtkW1A/unsubscribe.
    To unsubscribe from this group and all its topics, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Mike Samuel at Feb 14, 2014 at 1:26 am

    2014-02-13 19:32 GMT-05:00 John Barton <jrbarton@gmail.com>:
    I still argue that comments don't frequently leak information that should
    not be leaked, and even if it does up to a point, that the balance is still
    in favour of the legitimate use cases.
    My survey of application code seemed to indicate otherwise, but
    different code-bases differ, and I think well-documented workarounds
    can satisfy both concerns.

    Goodfilms is an interesting example, as instead of having a responsive site
    we do user agent sniffing and redirect to a separate mobile app. The comment
    you reference is production only information that I willingly exposed for
    its usefulness in debugging production issues (especially around caching +
    code reloading issues), and I don't believe it presents any meaningful
    security risk.
    There is a problem in that there is no escaping convention for comment
    content, and comments are often co-opted for language extensions like
    conditional compilation.

    This lack of a transformation from string -> safe, and the knowledge
    that there are obscure unknowns makes it hard to derive a
    white-listing definition of a safe comment.

    If you check out out portfolio site http://codename.io/, which is just flat
    HTML (ie nothing to debug) and designed to be responsive, you'll see 100%
    the opposite - we use comments for IE and don't expose any debugging
    information.

    The docs explicitly mention that the template authors are trusted and that
    Execute's data parameter is not. Given that, it's not surprising that
    anything injected into a template is altered for security reasons, but very
    surprising that something in the actual template is removed/modified.
    The security posture is that template authors are trusted but naive.

    By naive, I mean we assume that template authors know a subset (the
    good parts) of the languages they work in, but are not as familiar
    with obscure/bad parts which only language lawyers and attackers know
    well.

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Josh Bleecher Snyder at Feb 14, 2014 at 2:06 am

    I still argue that comments don't frequently leak information that should
    not be leaked, and even if it does up to a point, that the balance is still
    in favour of the legitimate use cases.
    My survey of application code seemed to indicate otherwise, but
    different code-bases differ, and I think well-documented workarounds
    can satisfy both concerns.
    However one feels about right thing to do in general, there remains
    the fact that existing templates may have been written relying on the
    fact that comments get stripped. If the default behavior changed,
    information that is currently private might leak. That strikes me as a
    non-starter.

    Given that backdrop, to my mind, the more interesting question is
    about how best to expose non-default non-comment-stripping behavior.
    (A template level option? Better helper functions? Status quo? Etc.)

    -josh

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • Matt Silverlock at Feb 10, 2014 at 12:28 am
    Figured I'd jump in here (I meant to last week) as I've been using
    html/template for a little while and can probably voice some of my pain
    points:


        - A lot of the html/template docs are improved by the content in
        text/template (http://golang.org/pkg/text/template/). Although it
        potentially increases the risk of the two sets of docs getting out of sync,
        I'd like to see more content pulled across (or at least referenced).
        FuncMaps are a big one: examples would be good.
        - HTML comment stripping: I completely understand where you're coming
        from here, but to change this is effectively breaking expectations. I'd
        prefer to see a way to turn them on (per base template), with the default
        remaining as off. The docs should be clear on how to turn them on for the
        many users who wish to do so.
        - If not some default FuncMaps, I think a few strong examples would help
        to bridge the gap here. `func NoEscape(string) template.HTML` is pretty
        simple to implement, but it pays to be explicit.
        - Bring the comparison operators from 1.2
        (http://golang.org/doc/go1.2#text_template) into the html/template docs.
        There's still a disconnect here, and the lack of a "single reference" (as
        touched on above) is also likely to push users to other templating packages
        in cases where html/template can likely do what they want.
        - How to use {{ with }} and {{ range }} as per this great
        tutorial: http://jan.newmarch.name/golang/template/chapter-template.html
        - Nesting templates, pipelining, etc. Good example is passing a
        per-template title into the base templates <title> block by using a {{
        $title := "This Page" }}.

    As someone coming from (primarily) Django templates, html/template wasn't
    *hard* to figure out (in hindsight) but it often wasn't clear how to
    achieve things. When I was made aware that text/template's docs had a lot
    of the "missing" content and after finding a couple of good resources
    things became much easier.

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.
  • David Symonds at Feb 10, 2014 at 12:53 am
    I am confused why people are asking for more docs in html/template.
    Its package docs start with these two lines:
       Package template (html/template) implements data-driven templates
    for generating HTML output safe against code injection. 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.

    That seems pretty clear that you should go read the text/template docs
    to learn how to use the templating features except for the
    HTML-specific stuff. I'd certainly welcome suggestions on how to make
    that clearer, because it's obvious that people are skipping over those
    two lines or not understanding them.

    --
    You received this message because you are subscribed to the Google Groups "golang-nuts" group.
    To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
    For more options, visit https://groups.google.com/groups/opt_out.

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupgolang-nuts @
categoriesgo
postedFeb 6, '14 at 2:25a
activeFeb 14, '14 at 2:06a
posts14
users8
websitegolang.org

People

Translate

site design / logo © 2022 Grokbase