Merge branch 'master' into self-hosted

philwareham · philwareham · commit 35b6999a1c8e · 2021-02-17T14:58:28.000Z
diff --git a/tags/lang.md b/tags/lang.md
@@ -3,7 +3,7 @@ layout: document
 category: Tags
 published: true
 title: Lang
-description: Textpattern will replace this tag with the 2-letter code of the language which is set as the site's language preference.
+description: Textpattern will replace this tag with the 2-letter code of the language which is set as the website's language.
 tags:
   - Language tags
   - Markup tags
@@ -22,7 +22,7 @@ tags:
 <txp:lang />
 ~~~
 
-The **lang** tag is a *single* tag. Textpattern will replace this tag with the 2-letter code of the language which is set as the site's language preference in the Languages panel, according to [RFC 1766](https://www.ietf.org/rfc/rfc1766.txt).
+The **lang** tag is a *single* tag. Textpattern will replace this tag with the 2-letter code of the language which is set as the website's language in the Languages panel, according to [RFC 1766](https://www.ietf.org/rfc/rfc1766.txt).
 
 ## Attributes
 
@@ -43,6 +43,6 @@ This tag has no attributes of its own. It accepts only the {% include atts-globa
 </head>
 ~~~
 
-Why you might do this? When declaring a DTD, namespace and language that a site is served, the `lang` attribute is useful for ensuring translators, search engines and content parsers handle the document in the correct manner.
+When declaring a DTD, namespace and language that a site is served, the `lang` attribute is useful for ensuring translators, search engines and content parsers handle the document in the correct manner.
 
 Other tags used: [page_title](/tags/page_title), [text](/tags/text).
diff --git a/tags/link_to_home.md b/tags/link_to_home.md
@@ -33,15 +33,7 @@ In this mode it operates identically to [site_url](/tags/site_url).
 
 ## Attributes
 
-Tag will accept the following attributes (**case-sensitive**) as well as the {% include atts-global-link.html %}:
-
-### Common presentational attributes
-
-These attributes, which affect presentation, are shared by many tags. Note that default values can vary among tags.
-
-* `class="class name"`
-CSS class attribute to apply to the anchor. Will be ignored if used as a single tag.
-Default: unset.
+This tag has no attributes of its own. It accepts only the {% include atts-global-link.html %}.
 
 ## Examples
 
diff --git a/tags/link_to_next.md b/tags/link_to_next.md
@@ -52,37 +52,50 @@ Tag will accept the following attributes (**case-sensitive**) as well as the {%
 ### Example 1: Link to next article using the article title
 
 ~~~ html
-<txp:link_to_next>
+<txp:link_to_next wraptag="div" class="nav_next">
     <txp:title />
 </txp:link_to_next>
 ~~~
 
-### Example 2: Link to next article using static text
+Important: The `<txp:link_to_next>` tag automatically has its container context set to *the next article*. Thus to retrieve the article title of this article, use the `<txp:title />` tag and *not* the `<txp:next_title />` tag. Using the latter tag in the `<txp:link_to_next>` container would 'skip' an article title. Compare this usage to Example 3 where the single tag is used and the `<txp:next_title />` is therefore appropriate to fetch information from the next document.
+{: .alert-block .information}
+
+Other tags used: [next_title](/tags/next_title), [title](/tags/title).
+
+### Example 2: Link to next article
 
 ~~~ html
 <txp:link_to_next showalways="1">
     Next
 </txp:link_to_next>
 ~~~
 
+or to display the text in the current site language:
+
+~~~ html
+<txp:link_to_next showalways="1">
+    <txp:text item="next" />
+</txp:link_to_next>
+~~~
+
 This will always display the text 'Next', even when there is no next article.
 
-Note: While `showalways` will enable this tag to display what is wrapped inside it, [next_title](/tags/next_title) returns nothing if there is no next title, so nothing is displayed. Use text, or the returned value, that you need displayed.
+Note: While `showalways` will enable this tag to display what is wrapped inside it, [next_title](/tags/next_title) returns nothing if there is no next title, so nothing is displayed. Use fixed text instead in this case.
 {: .alert-block .information}
 
 ### Example 3: Customising links
 
-The container tag returns only a very basic link, which doesn't allow for customising the link title, or adding a CSS class, etc. Using the tag in its single tag capacity opens up a lot more possibilities.
+The container tag returns only a very basic link, which doesn't allow for customising the link title. Using the tag in its single tag capacity opens up more possibilities.
 
-For example, to give the link an HTML `title` attribute of the next article's title, and also apply a `class` to it:
+To give the link an HTML `title` attribute of the next article's title:
 
 ~~~ html
 <a class="link--next" href="<txp:link_to_next />" title="<txp:next_title />">
     Next article →
 </a>
 ~~~
 
-Other tags used: [prev_title](/tags/next_title), [title](/tags/title).
+Other tags used: [next_title](/tags/next_title).
 
 ## Genealogy
 
diff --git a/tags/link_to_prev.md b/tags/link_to_prev.md
@@ -52,11 +52,16 @@ Tag will accept the following attributes (**case-sensitive**) as well as the {%
 ### Example 1: Link to previous article using its title
 
 ~~~ html
-<txp:link_to_prev>
+<txp:link_to_prev wraptag="div" class="nav_prev">
     <txp:title />
 </txp:link_to_prev>
 ~~~
 
+Important: The `<txp:link_to_prev>` tag automatically has its container context set to *the previous article*. Thus to retrieve the article title of this article, use the `<txp:title />` tag and *not* the `<txp:prev_title />` tag. Using the latter tag in the `<txp:link_to_prev>` container would 'skip' an article title. Compare this usage to Example 3 where the single tag is used and the `<txp:prev_title />` is therefore appropriate to fetch information from the previous document.
+{: .alert-block .information}
+
+Other tags used: [prev_title](/tags/prev_title), [title](/tags/title).
+
 ### Example 2: Link to previous article using static text
 
 ~~~ html
@@ -65,24 +70,32 @@ Tag will accept the following attributes (**case-sensitive**) as well as the {%
 </txp:link_to_prev>
 ~~~
 
+or to display the text in the current site language:
+
+~~~ html
+<txp:link_to_prev showalways="1">
+    <txp:text item="prev" />
+</txp:link_to_prev>
+~~~
+
 This will always display the text 'Previous', even when there is no previous article.
 
-Note: While `showalways` will enable this tag to display what is wrapped inside it, [prev_title](/tags/prev_title) returns nothing if there is no previous title, so nothing is displayed. Use text, or the returned value, that you need displayed.
+Note: While `showalways` will enable this tag to display what is wrapped inside it, [prev_title](/tags/prev_title) returns nothing if there is no previous title, so nothing is displayed. Use fixed text instead in this case.
 {: .alert-block .information}
 
 ### Example 3: Customising links
 
-The container tag returns only a very basic link, which doesn't allow for customising the link title, or adding a CSS class, etc. Using the tag in its single tag capacity opens up a lot more possibilities.
+The container tag returns only a very basic link, which doesn't allow for customising the link title. Using the tag in its single tag capacity opens up more possibilities.
 
-For example, to give the link an HTML `title` attribute of the previous article's title, and also apply a `class` to it:
+To give the link an HTML `title` attribute of the previous article's title:
 
 ~~~ html
 <a class="link--prev" href="<txp:link_to_prev />" title="<txp:prev_title />">
     ← Previous article
 </a>
 ~~~
 
-Other tags used: [prev_title](/tags/prev_title), [title](/tags/title).
+Other tags used: [prev_title](/tags/prev_title).
 
 ## Genealogy
 
diff --git a/tags/newer.md b/tags/newer.md
@@ -21,13 +21,11 @@ tags:
 <txp:newer />
 ~~~
 
-The **newer** tag is both a *single* tag and a *container* tag. The tag should be used in a page after an article tag.
+The **newer** tag is both a *single* tag and a *container* tag. Textpattern will replace this tag with a link to the next list of articles in the sort order. As a single tag it outputs the URL for the next list page. If used as a container, it will wrap the text or tag assigned to the link.
 
-Textpattern will replace this tag with a link to the next list of articles in the sort order. The container tags wrap the text or tag assigned to the link. As a single tag it outputs the URL for the next list page.
+An article list consists of the assigned number of articles set by the [article tag](/tags/article). If there are no articles available having 'Newer' status (articles ranked higher, or later, in the present sort criteria than the article shown at the top of the present list) `<txp:newer />` will not display unless the `showalways` attribute is set. It is normally used in tandem with [older](/tags/older) or [pages](/tags/pages).
 
-An article list consists of the assigned number of articles set by the article tag. If there are no articles available having 'Newer' status (articles ranked higher, or newer, in the present sort criteria than the present top of page article) `<txp:newer />` will not display unless the `showalways` attribute is set to `1`. It is normally seen used in tandem with [older](/tags/older).
-
-Given a `<txp:article limit="5" />` tag on the page in question, `<txp:newer />` will page down five articles at a time from the most oldest post forward in time to the most recently posted article.
+Given a `<txp:article limit="5" />` tag on the page in question, `<txp:newer />` will page up five articles at a time from the oldest post forward in time to the most recently posted article.
 
 Note: This tag is context-sensitive, meaning it will only fetch content from the section or category being viewed.
 {: .alert-block .information}
@@ -36,11 +34,6 @@ Note: This tag is context-sensitive, meaning it will only fetch content from the
 
 Tag will accept the following attributes (**case-sensitive**) as well as the {% include atts-global-link.html %}:
 
-`escape="html"` <span class="footnote warning">v4.3.0+</span>
-: Escape [HTML entities](https://developer.mozilla.org/en-US/docs/Glossary/Entity) such as `<`, `>` and `&`.
-: **Values:** See the [tag escaping](/tags/learning/#tag-escaping) documentation for all possible values.
-: **Default:** `html`.
-
 `rel="text"` <span class="footnote warning">v4.7.0+</span>
 : [HTML rel attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes) to be applied to link.
 : **Default:** unset.
@@ -62,6 +55,12 @@ Tag will accept the following attributes (**case-sensitive**) as well as the {%
 <txp:newer rel="prev">Newer</txp:newer>
 ~~~
 
+or, to render the text in the current site language:
+
+~~~ html
+<txp:newer rel="prev"><txp:text item="newer" /></txp:newer>
+~~~
+
 ### Example 2: Single tag - link with image
 
 ~~~ html
diff --git a/tags/older.md b/tags/older.md
@@ -21,11 +21,9 @@ tags:
 <txp:older />
 ~~~
 
-The **older** tag is both a *single* tag and a *container* tag. The tag should be used in a page after an article tag.
+The **older** tag is both a *single* tag and a *container* tag. Textpattern will replace this tag with a link to the previous list of articles in the sort order. As a single tag it outputs the URL for the previous list page. If used as a container, it will wrap the text or tag assigned to the link
 
-Textpattern will replace this tag with a link to the previous list of articles in the sort order. The container tags wrap the text or tag assigned to the link. As a single tag it outputs the URL for the previous list page.
-
-An article list consists of the assigned number of articles set by the article tag. If there are no articles available having 'Older' status (articles ranked lower, or later, in the present sort criteria than the present bottom of page article) `<txp:older />` will not display unless the `showalways` attribute is set to `1`. It is normally seen used in tandem with [newer](/tags/newer).
+An article list consists of the assigned number of articles set by the [article tag](/tags/article). If there are no articles available having 'Older' status (articles ranked lower, or earlier, in the present sort criteria than the article shown at the bottom of the present list) `<txp:older />` will not display unless the `showalways` attribute is set. It is normally used in tandem with [newer](/tags/newer) or [pages](/tags/pages).
 
 Given a `<txp:article limit="5" />` tag on the page in question, `<txp:older />` will page down five articles at a time from the most recent post back in time to the oldest.
 
@@ -36,11 +34,6 @@ Note: This tag is context-sensitive, meaning it will only fetch content from the
 
 Tag will accept the following attributes (**case-sensitive**) as well as the {% include atts-global-link.html %}:
 
-`escape="html"` <span class="footnote warning">v4.3.0+</span>
-: Escape [HTML entities](https://developer.mozilla.org/en-US/docs/Glossary/Entity) such as `<`, `>` and `&`.
-: **Values:** See the [tag escaping](/tags/learning/#tag-escaping) documentation for all possible values.
-: **Default:** `html`.
-
 `rel="text"` <span class="footnote warning">v4.7.0+</span>
 : [HTML rel attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes) to be applied to link.
 : **Default:** unset.
@@ -62,6 +55,12 @@ Tag will accept the following attributes (**case-sensitive**) as well as the {%
 <txp:older rel="next">Older</txp:older>
 ~~~
 
+or, to render the text in the current site language:
+
+~~~ html
+<txp:older rel="next"><txp:text item="older" /></txp:older>
+~~~
+
 ### Example 2: Single tag - link with image
 
 ~~~ html
diff --git a/tags/popup.md b/tags/popup.md
@@ -3,7 +3,7 @@ layout: document
 category: Tags
 published: true
 title: Popup
-description: Textpattern will replace this tag with a popup selector for browsing by section or category.
+description: Textpattern will replace this tag with a selector for browsing by section or category.
 tags:
   - Navigation tags
 ---
@@ -21,53 +21,43 @@ tags:
 <txp:popup />
 ~~~
 
-The **popup** tag is a *single* tag. Textpattern will replace this tag with a popup selector for browsing by section or category.
+The **popup** tag is a *single* tag. Textpattern will replace this tag with a select list for browsing by section or category, wrapped in an HTML `<form>`. Selecting an entry will automatically submit the form unless scripting is disabled, in which case a 'submit' button will be displayed too.
 
 ## Attributes
 
 Tag will accept the following attributes (**case-sensitive**) as well as the {% include atts-global-link.html %}:
 
 `section="section_name"`
-: Jump to the selected category for the named section.
+: Filter the selected category by the named section, instead of listing all articles that match the category. Only of use if `type="category"`.
 : **Default:** unset.
 
 `this_section="boolean"`
-: Jump to the selected category for the currently active section.
+: Filter the selected category by the currently active section, instead of listing all articles that match the category. Only of use if `type="category"`.
 : **Values:** `0` (no) or `1` (yes).
 : **Default:** `0`.
 
 `type="type"`
 : **Values:** `section`, `category`.
 : **Default:** `category`.
 
-### Common presentational attributes
-
-These attributes, which affect presentation, are shared by many tags. Note that default values can vary among tags.
-
-`class="class name"` <span class="footnote warning">v4.3.0+</span>
-: HTML `class` to apply to the `wraptag` attribute value.
-: **Default:** tag name or unset (see [class cross-reference](/tags/tag-attributes-cross-reference#class)).
-
-`label="text"`
-: Label prepended to item.
-: **Default:** unset (but see [label cross-reference](/tags/tag-attributes-cross-reference#label) for exceptions).
-
-`wraptag="element"`
-: HTML element to wrap (markup) list block, specified without brackets (e.g. `wraptag="ul"`).
-: **Default:** unset (but see [wraptag cross-reference](/tags/tag-attributes-cross-reference#wraptag) for exceptions).
-
 ## Examples
 
 ### Example 1: Browse by category popup selector
 
 ~~~ html
-<txp:popup type="category" wraptag="p" />
+<txp:popup type="category" wraptag="div" />
+~~~
+
+### Example 2: Browse by section popup selector
+
+~~~ html
+<txp:popup type="section" wraptag="div" class="site_browse" />
 ~~~
 
-### Example 2: Popup selector with custom label
+### Example 3: Popup selector with custom label that filters by current section
 
 ~~~ html
-<txp:popup label="Browse this site" type="category" wraptag="p" />
+<txp:popup label="Browse by category" type="category" this_section />
 ~~~
 
 ## Genealogy
diff --git a/tags/text.md b/tags/text.md
@@ -21,22 +21,17 @@ tags:
 <txp:text />
 ~~~
 
-The **text** tag is a *single* tag which is primarily used to return localized language strings from the `txp_lang` database table.
+The **text** tag is a *single* tag which is used to return localized language strings from the `txp_lang` database table.
 
-Note: only language strings designated with a type of [`common`](https://github.com/textpattern/textpacks/blob/main/lang/en.ini#L265) or [`public`](https://github.com/textpattern/textpacks/blob/main/lang/en.ini#L776) are available to use. All other language string types are reserved for use within the Textpattern system itself.
+Note: only language strings designated with a type of [`common`](https://github.com/textpattern/textpacks/blob/main/lang/en.ini#L265) or [`public`](https://github.com/textpattern/textpacks/blob/main/lang/en.ini#L776) are available to use. All other language string types are reserved for use within the Textpattern back-end system itself.
 {: .alert-block .information}
 
 ## Attributes
 
 Tag will accept the following attributes (**case-sensitive**) as well as the {% include atts-global-link.html %}:
 
-`escape="html"` <span class="footnote warning">v4.6.0+</span>
-: Escape [HTML entities](https://developer.mozilla.org/en-US/docs/Glossary/Entity) such as `<`, `>` and `&` within text.
-: **Values:** See the [tag escaping](/tags/learning/#tag-escaping) documentation for all possible values.
-: **Default:** `html`.
-
 `item="text"`
-: Piece of text to display, preferably an item from the `name` column of the `txp_lang` database table. If the given item matches a key there, the contents of the respective item in the `data` column will be returned. Otherwise, whatever you supply as the `item` value is returned verbatim.
+: Piece of text to display, preferably an item from the `name` column of the txp_lang database table. If the given item matches a key in the currently selected site language, the contents of the respective item in the `data` column will be returned. Otherwise, whatever you supply as the `item` value is returned verbatim.
 
 ## Examples
 
@@ -48,7 +43,17 @@ Tag will accept the following attributes (**case-sensitive**) as well as the {%
 </txp:older>
 ~~~
 
-Outputs the text 'older' inside the `<txp:older />` tag, respecting the current Textpattern language, instead of using the tag like this: `<txp:older>older</txp:older>` which would always render the English text 'older', it replaces the contents with the value assigned to the name 'older' in the current language. So you would see a link with the word 'älter' if you were using German `de` as the Textpattern site language.
+Replaces the contents of the tag with the value assigned to the name 'older' in the current site language. It takes this information from the matching key 'older' in the txp_lang database table. So if you were using German `de` as the Textpattern site language, you would see a link with the word 'älter'.
+
+If, however, you had used the `<txp:older>` tag tag like this:
+
+~~~ html
+<txp:older>
+    Older
+</txp:older>
+~~~
+
+then it would always render English text, which is undesirable if your site is changed to show content in a different language.
 
 Other tags used: [older](/tags/older).
 
