Editing Template:Truncate/doc

<noinclude>==Editor Docs==</noinclude>
Ensures the text argument does not exceed 250 characters, as described in the [[Editing Guidelines]] on this Wiki. Text longer than that limit is truncated, an error message is displayed in the article, and the article is flagged for review.

This Template is intended for use by other Templates rather than direct use in Wiki content. It should used as a "guardrail" to help inexperienced Wiki editors adhere to the Editing Guidelines. It should apply to any Template field that is intended to include direct quotes of game text to which the Editing Guidelines apply.

Ellipses in brackets such as "{{...}}" do not count towards the character limit and should be used to represent game text that has been elided to fit the length requirements. Line breaks, double- and triple-single quotes for <nowiki>''italics'' or '''bold'''</nowiki>, and HTML elements are also not counted for the character limit.

Other placeholder text can be used without counting towards truncation by wrapping the text in an <nowiki><span data-truncate="ignore">HTML element with the corresponding property</span></nowiki>. This should be used to indicate variant text or add formatting, not to paraphrase static text. Use templates for this when possible, e.g. using [[Template:Af]] to display the player's terms of address as {{IL|Addressed as:|Appearance=[formal address]}}.

===Arguments===
* '''1''' The first positional argument is the game text to be truncated.
* '''chars''' The character limited before truncation occurs. Defaults to 250. Intended for cases where a quote is split between multiple fields, in which case the character limit for the second field can be set to 250 minus the length of the first field.

<noinclude>
==Implementation Docs==
===Formatting Notes===
This template is intended to be used in multiple contexts. As such, when game text fits inside the character limit, it should not use any Block-type HTML elements like <nowiki><div> or <p></nowiki>. Block-type elements are not allowed inside Inline-type elements, and can cause rendering issues when used in that way.

Game text over the character limit is considered an error condition, and the Template is allowed to misbehave when that happens. This is considered somewhat of a feature rather than a bug, as it encourages editors to fix their text.  The error message that flags truncated text has line breaks which may cause rendering or accessibility issues. Trimmed text may also elide more characters than necessary.
===Patterns===
This Template handles Elipses by using Patterns, Lua's stand-in for Regular Expressions. Patterns share many of the readability issues of regexen, while also having syntax unfamiliar to most users of regular expressions. Additionally, most characters of note in the Elipses expressions are control characters in Lua Patterns.

The pattern will match any block of text that consists of:
* Either '''[''' or '''(''' at the beginning
* Any non-empty collection of '''.''' and '''…''' characters in the middle
* Either ''']''' or ''')''' at the end.

For the sake of simplicity, this Pattern does not check whether the opening character matches the closing one, and it matches single periods. In addition to the standard Elipses recommended in the Editing Guidelines such as {{...}}, [...], and (...), it also matches non-sensical patterns such as the following:
* (.)
* [………]
* (…]
* [..)

Such text patterns are unlikely to arise in game text, so this is not considered a pressing issue.
</noinclude>
<includeonly><templatedata>
{
	"params": {
		"1": {
			"label": "Game text",
			"description": "The game text that is to be truncated.",
			"type": "string",
			"suggested": true
		},
		"chars": {
			"label": "Maximum characters",
			"description": "The maximum allowed length before truncation.",
			"type": "number",
			"default": "250"
		}
	},
	"description": "Ensures the text argument does not exceed 250 characters, as described in the [[Editing Guidelines]] on this Wiki. Text longer than that limit is truncated, an error message is displayed in the article, and the article is flagged for review.\n\nThis Template is intended for use by other Templates rather than direct use in Wiki content. It should used as a \"guardrail\" to help inexperienced Wiki editors adhere to the Editing Guidelines. It should apply to any Template field that is intended to include direct quotes of game text to which the Editing Guidelines apply.\n\nEllipses in brackets such as \"{{...}}\" do not count towards the character limit and should be used to represent game text that has been elided to fit the length requirements. Line breaks, double- and triple-single quotes for <nowiki>''italics'' or '''bold'''</nowiki>, and HTML elements are also not counted for the character limit.\n\nOther placeholder text can be used without counting towards truncation by wrapping the text in an <nowiki><span data-truncate=\"ignore\">HTML element with the corresponding property</span></nowiki>. This should be used to indicate variant text or add formatting, not to paraphrase static text. Use templates for this when possible, e.g. using [[Template:Af]] to display the player's terms of address as {{IL|Addressed as:|Appearance=[formal address]}}."
}
</templatedata></includeonly>
<noinclude>[[Category:Template documentation]]</noinclude>