Merge pull request #830 from hairyhenderson/document-go-template-acti…

…ons-824

Improve documentation for upstream functions & actions

docs/content/syntax.md

@@ -5,7 +5,7 @@ menu: main
 ---
 
 Gomplate uses the syntax understood by the Go language's [`text/template`][]
-package. This page documents some of that syntax, but see [the docs][`text/template`]
+package. This page documents some of that syntax, but see [the language docs][`text/template`]
 for full details.
 
 ## The basics
@@ -207,41 +207,47 @@ renders as:
 The word is c3dvcmRmaXNo
 ```
 
-The [Go text/template]() language provides a number of built-in functions and 
-operators that can be used in templates.
+Go's [`text/template`][] language provides a number of built-in functions, 
+operators, and actions that can be used in templates.
 
 Here is a list of the built-in functions, but see [the documentation](https://golang.org/pkg/text/template/#hdr-Functions)
 for full details:
 
-- `and`
-- `call`
-- `html`
-- `index`
-- `js`
-- `len`
-- `not`
-- `or`
-- `print`
-- `printf`
-- `println`
-- `urlquery`
+- `and`, `or`, `not`: Returns boolean AND/OR/NOT of the argument(s).
+- `call`: Returns the result of calling a function argument.
+- `html`, `js`, `urlquery`: Safely escapes input for inclusion in HTML, JavaScript, and URL query strings.
+- `index`: Returns the referenced element of an array or map. See also [Arrays](#arrays) and [Maps](#maps).
+- `len`: Returns the length of the argument.
+- `print`, `printf`, `println`: Aliases for Go's [`fmt.Print`](https://golang.org/pkg/fmt/#Print),
+[`fmt.Printf`](https://golang.org/pkg/fmt/#Printf), and [`fmt.Println`](https://golang.org/pkg/fmt/#Println)
+functions. See the [format documentation](https://golang.org/pkg/fmt/#hdr-Printing)
+for details on `printf`'s format syntax.
 
 And the following comparison operators are also supported:
 
-- `eq`
-- `ne`
-- `lt`
-- `le`
-- `gt`
-- `ge`
+- `eq`: Equal (`==`)
+- `ne`: Not-equal (`!=`)
+- `lt`: Less than (`<`)
+- `le`: Less than or equal to (`<=`)
+- `gt`: Greater than (`>`)
+- `ge`: Greater than or equal to (`>=`)
+
+There are also a few _actions_, which are used for control flow and other purposes. See [the documentation](https://golang.org/pkg/text/template/#hdr-Actions) for details on these:
+
+- `if`/`else`/`else if`: Conditional control flow.
+- `with`/`else`: Conditional execution with assignment.
+- `range`: Looping control flow. See discussion in the [Arrays](#arrays) and [Maps](#maps) sections.
+- `template`: Include the output of a named template. See the [Nested templates](#nested-templates) section for more details, and the [`tmpl`](../functions/tmpl) namespace for more flexible versions of `template`.
+- `define`: Define a named nested template. See the [Nested templates](#nested-templates) section for more details.
+- `block`: Shorthand for `define` followed immediately by `template`.
 
 See also gomplate's functions, defined to the left.
 
 ## The Context
 
 Go templates are always executed with a _context_. You can reference the context
 with the `.` (period) character, and you can set the context in a block with the
-`with` keyword. Like so:
+`with` action. Like so:
 
 ```
 $ gomplate -i '{{ with "foo" }}The context is {{ . }}{{ end }}'