Merge commit 'e5568488051a571df48401e03f1304b95dbc9028'

3 files changed, 11 insertions, 5 deletions

diff --git a/docs/content/en/templates/pagination.md b/docs/content/en/templates/pagination.md
index bd4176761..5c20f8ad0 100644
--- a/docs/content/en/templates/pagination.md
+++ b/docs/content/en/templates/pagination.md
@@ -43,10 +43,16 @@ Setting `Paginate` to a positive value will split the list pages for the homepag
 There are two ways to configure and use a `.Paginator`:
 
 1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page*.
-2. Select a subset of the pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g. `{{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }}`.
+2. Select another set of pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g.
+  * `{{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }}` or
+  * `{{ range (.Paginate .RegularPagesRecursive).Pages }}`.
 
 For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created.
 
+If you call `.Paginator` or `.Paginate` multiple times on the same page, you should ensure all the calls are identical. Once *either* `.Paginator` or `.Paginate` is called while generating a page, its result is cached, and any subsequent similar call will reuse the cached result. This means that any such calls which do not match the first one will not behave as written.
+
+(Remember that function arguments are eagerly evaluated, so a call like `$paginator := cond x .Paginator (.Paginate .RegularPagesRecursive)` is an example of what you should *not* do. Use `if`/`else` instead to ensure exactly one evaluation.)
+
 The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page:
 
 * `{{ range (.Paginator 5).Pages }}`
diff --git a/docs/content/en/templates/sitemap-template.md b/docs/content/en/templates/sitemap-template.md
index dee28fc3b..acc90a1c8 100644
--- a/docs/content/en/templates/sitemap-template.md
+++ b/docs/content/en/templates/sitemap-template.md
@@ -43,7 +43,7 @@ For multilingual sites, we also create a Sitemap index. You can provide a custom
 
 ## Hugo’s sitemap.xml
 
-This template respects the version 0.9 of the [Sitemap Protocol](https://www.sitemaps.org/protocol.html).
+This template respects the version 1.0 of the [Sitemap Protocol](https://www.sitemaps.org/protocol.html).
 
 ```xml
 {{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }}
diff --git a/docs/content/en/templates/taxonomy-templates.md b/docs/content/en/templates/taxonomy-templates.md
index 15e0ff5c9..3f93052d9 100644
--- a/docs/content/en/templates/taxonomy-templates.md
+++ b/docs/content/en/templates/taxonomy-templates.md
@@ -158,11 +158,11 @@ Hugo uses both `date` and `weight` to order content within taxonomies.
 
 Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to.
 
-When iterating over content within taxonomies, the default sort is the same as that used for section and list pages first by weight then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first.
+When iterating over content within taxonomies, the default sort is the same as that used for section and list pages: first by weight, then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first.
 
-The default weight for any piece of content is 0.
+The default weight for any piece of content is 0. Zero means "does not have a weight", not "has a weight of numerical value zero".
 
-Weights of zero are treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end.
+Weights of zero are thus treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end.
 
 ### Assign Weight