Gentle suggestions improvements in documentation

[sdwarwick]

this package is such a great find. thanks so much for your work. Just a few suggestions

1. notwithstanding the assumption that folks are experienced go developers, it might be a good idea to mention that function names in the template must be capitalized to be accessible.

2. the use of ./template doesn't work if you are using go build .. I have a directory that I keep both the source and executable, which is necessary for this development. build wants an absolute path names for imports. It might be worth mentioning that the location of the template folder wants to be in your source tree and referenced with an absolute path.

3. the readme.md is a great reference on the template language, but did not strike me as the "definitive reference" Perhaps it is just a change in headings, or perhaps setting up a separate document as the reference would help to quell the uneasy feeling that there is more than mentioned there.

4. the basicserver example could really use some additional comments to describe what is really going on. The use of function pointers could be discussed in more detail. It really deserves more TLC

5. finally, our intended use requires the building of templates in parallel using multiple goroutines. It would be helpful to know if the rendering part of this system can handle that. the streaming to output we handle separately.

[valyala]

@sdwarwick , I'll be glad accepting pull requests that enhance quicktemplate documentation.

finally, our intended use requires the building of templates in parallel using multiple goroutines. It would be helpful to know if the rendering part of this system can handle that. the streaming to output we handle separately.

Template functions are safe to call from concurrent goroutines. Unless you access shared resources inside template functions and these resources may be modified by concurrent goroutines. -race flag should help detecting such cases - see the corresponding documentation.

[valyala]

Here is a blog post about race detector - https://blog.golang.org/race-detector

[b0o]

@valyala

I have to agree about the documentation being rather lacking.

My main issue is that the syntax is not clearly and consistently defined in the README. For example, it is never explicitly stated that there exists {% if %} and {% endif %} tags - the only hint of their existence lies within some examples.

I'm in the process of building a better .qtpl syntax highlighting plugin for Vim and the lack of good documentation is what's mostly holding me back.

I may submit a PR containing my preferred improvements to the README, but some of it will be guesswork due to the fact that there doesn't exist proper documentation of some things in the first place.