text/template: Better doc for ParseFiles and Execute behaviour.

[siritinga]

Hello.

I recently spent some time trying to figure why a template with Funcmaps would work with Parse() but not with ParseFiles() when using Execute (instead of ExecuteTemplate with the name).

I found the answer in Stack Overflow http://stackoverflow.com/questions/10199219/go-template-function but the question also appeared in golang-nuts, for example here https://groups.google.com/forum/#!topic/golang-nuts/CI9WdC_sk00 and here https://groups.google.com/forum/#!topic/golang-nuts/vmZHHfLsH8M

Please consider if it should be better documented to make it less error-prone for inexperienced users.

Thank you.

[gobijan]

I came here because I also wanted to open an issue about this. This API is not really developer friendly. Maybe one should change the semantics too and not only the docs. It feels wrong to name the most outer template again in template new just to add a funcMap via .Funcs.

// This is what currently works
tmpl := template.Must(template.New("layout.html.go").Funcs(funcMap).ParseFiles("tmpl/layout.html.go","tmpl/index.html.go"))

One has to explicitly name the outer template. This should at least be documented :)