1 files changed, 91 insertions, 0 deletions
diff --git a/src/pkg/template/doc.go b/src/pkg/template/doc.go
new file mode 100644
index 000000000..e778d801d
--- /dev/null
+++ b/src/pkg/template/doc.go
@@ -0,0 +1,91 @@
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+	Package template implements data-driven templates for generating textual
+	output such as HTML.
+
+	Templates are executed by applying them to a data structure.
+	Annotations in the template refer to elements of the data
+	structure (typically a field of a struct or a key in a map)
+	to control execution and derive values to be displayed.
+	The template walks the structure as it executes and the
+	"cursor" @ represents the value at the current location
+	in the structure.
+
+	Data items may be values or pointers; the interface hides the
+	indirection.
+
+	In the following, 'Field' is one of several things, according to the data.
+
+		- The name of a field of a struct (result = data.Field),
+		- The value stored in a map under that key (result = data["Field"]), or
+		- The result of invoking a niladic single-valued method with that name
+		  (result = data.Field())
+
+	If Field is a struct field or method name, it must be an exported
+	(capitalized) name.
+
+	Major constructs ({} are the default delimiters for template actions;
+	[] are the notation in this comment for optional elements):
+
+		{# comment }
+
+	A one-line comment.
+
+		{.section field} XXX [ {.or} YYY ] {.end}
+
+	Set @ to the value of the field.  It may be an explicit @
+	to stay at the same point in the data. If the field is nil
+	or empty, execute YYY; otherwise execute XXX.
+
+		{.repeated section field} XXX [ {.alternates with} ZZZ ] [ {.or} YYY ] {.end}
+
+	Like .section, but field must be an array or slice.  XXX
+	is executed for each element.  If the array is nil or empty,
+	YYY is executed instead.  If the {.alternates with} marker
+	is present, ZZZ is executed between iterations of XXX.
+
+		{field}
+		{field1 field2 ...}
+		{field|formatter}
+		{field1 field2...|formatter}
+		{field|formatter1|formatter2}
+
+	Insert the value of the fields into the output. Each field is
+	first looked for in the cursor, as in .section and .repeated.
+	If it is not found, the search continues in outer sections
+	until the top level is reached.
+
+	If the field value is a pointer, leading asterisks indicate
+	that the value to be inserted should be evaluated through the
+	pointer.  For example, if x.p is of type *int, {x.p} will
+	insert the value of the pointer but {*x.p} will insert the
+	value of the underlying integer.  If the value is nil or not a
+	pointer, asterisks have no effect.
+
+	If a formatter is specified, it must be named in the formatter
+	map passed to the template set up routines or in the default
+	set ("html","str","") and is used to process the data for
+	output.  The formatter function has signature
+		func(wr io.Writer, formatter string, data ...interface{})
+	where wr is the destination for output, data holds the field
+	values at the instantiation, and formatter is its name at
+	the invocation site.  The default formatter just concatenates
+	the string representations of the fields.
+
+	Multiple formatters separated by the pipeline character | are
+	executed sequentially, with each formatter receiving the bytes
+	emitted by the one to its left.
+
+	As well as field names, one may use literals with Go syntax.
+	Integer, floating-point, and string literals are supported.
+	Raw strings may not span newlines.
+
+	The delimiter strings get their default value, "{" and "}", from
+	JSON-template.  They may be set to any non-empty, space-free
+	string using the SetDelims method.  Their value can be printed
+	in the output using {.meta-left} and {.meta-right}.
+*/
+package template