-# Within a template, it recognizes tags delimited by tildes (~). When
-# the template is filled out, the tags will be replaced with the
-# corresponding data. Tags ending with '?' and '.' mark the start and
-# end of a sub-template (for optional or repeated text), and can be
-# wrapped in HTML comments (which will be removed along with the tags
-# when the template is filled out).
+# Within a template, it recognizes tags of the form ~name [arg...]~,
+# optionally wrapped in HTML comments (which will be removed along with
+# the tag markers when the template is filled out).
+#
+# { and } as the final argument mark those tags as being the start and
+# end of a sub-template (for optional or repeated sections). All other
+# tags represent slots to be directly filled by data values. On a }
+# tag, the name is optional, but must match the corresponding { tag if
+# present.
+#
+# For a value tag, arguments represent encodings to be applied
+# successively. For instance, ~foo html~ will encode it to be safe in
+# HTML ('&' to '&', '<' to '<', and so on).
+#
+# { tags can take one argument, which will call the corresponding
+# tem_auto_* function to munge the data, automating certain common use
+# cases. See the comments on the tem_auto functions for more details.