Editing Template:Unichar/doc

{{Documentation subpage}}
{{lua|Module:Numcr2namecr|Module:Unicode alias|Module:Unicode data|noprotcat=yes}}
This template produces a formatted description of a [[Unicode]] character, to be used inline or otherwise with regular text. 
* <code>The character {{tlx|unichar|<nowiki>a9</nowiki>}} is about intellectual property.</code> →
*: The character {{unichar|a9}} is about intellectual property.

==Usage==
The <nowiki>{{unichar}}</nowiki> template takes the Unicode hexadecimal [[code point]] value as input. Thus, for example, <code><nowiki>{{unichar|00A9}}</nowiki></code> → {{unichar|00A9}}.

This template produces a ''formatted description'' of a [[Unicode]] character, to be used ''in-line'' with regular text. It follows the standard Unicode presentation of a character, using the "U+" prefix for displaying the hex code point, followed by its glyph, then optionally by the character name, using Unicode's inline formatting recommendation. In running text such as the Unicode Standard, Wikipedia, or other rich-text environments, the character name is preferredly displayed in {{sc2|SMALL-CAPS STYLE}}. (The all-caps presentation is mainly designed for plain-text environments.) 

The hexadecimal value is required (e.g. A9), other input is optional. The actual glyph is rendered using a font that contains the character. This can be set to something more specific, e.g. to language- or [[International Phonetic Alphabet|IPA]]-specific fonts. To show the glyph, the font character can be overridden with an image. A wikilink to an article on the character or set of characters, and another to the article [[Unicode]] can be created. It is also possible to add (bracketed like this), the calculated decimal value, HTML character codes, and a custom note.

Some special [[code point]]s are given extra care, like control and space characters. These are handled automatically (by the <code>[[Template:unichar/gc|unichar/gc]]</code> sub-template) without user intervention.

===Examples===
* <syntaxhighlight lang="wikitext" inline>{{unichar|00A9}}</syntaxhighlight> → {{unichar|00A9}}
<!-- * <syntaxhighlight lang="wikitext" inline>{{unichar|00A9|name=none}}</syntaxhighlight> → {{unichar|00A9|name=none}} -->
* <syntaxhighlight lang="wikitext" inline>{{unichar|00A9|nlink=}}</syntaxhighlight> → {{unichar|00A9|nlink=}}
* <syntaxhighlight lang="wikitext" inline>{{unichar|00A9|nlink=|note={{crossref|See also [[Copyleft]] symbol}}}}</syntaxhighlight> → {{unichar|00A9|nlink=|note={{crossref|See also [[Copyleft]] symbol}}}}
* <syntaxhighlight lang="wikitext" inline>{{unichar|00A9|nlink=|html=}}</syntaxhighlight> → {{unichar|00A9|nlink=|html=}}
* <syntaxhighlight lang="wikitext" inline>{{unichar|030D|cwith=◌}}</syntaxhighlight> → {{unichar|030D|cwith=◌}}{{snd}}[[combining character|combined with]] a [[dotted circle]]
* <syntaxhighlight lang="wikitext" inline>{{unichar|030D|cwith=&#x25CC;}}</syntaxhighlight> → {{unichar|030D|cwith=&#x25CC;}}{{snd}} combined with  a dotted circle

* <syntaxhighlight lang="wikitext" inline>{{unichar|4E95|note=[[Jingtian]]}}</syntaxhighlight> → {{unichar|4E95|note=[[Jingtian]]}}

===Parameters===
The blank template, with all parameters, is as follows:
<syntaxhighlight lang=xml>
{{unichar
| ulink = 
| image = 
| cwith = 
| size  = 
| use   = 
| use2  = 
| nlink = 
| html  = 
| note  = 
| name  =
| alias =
}}
</syntaxhighlight>

Inline version:
<syntaxhighlight lang=xml>
{{unichar| <!--hex value (do not add "U+")-->|ulink= |image= |cwith= |size= |use= |use2= |nlink= |html= |note= }}
</syntaxhighlight>

* '''First unnamed parameter''' or '''1=''' Required. The hexadecimal value of the code point, e.g. {{code|00A9}}.
*:''Notes'': The parameter accepts input like {{code|A9}}, {{code|a9}} and {{code|00A9}} as hexadecimal value. Decimal values are not detected being decimal, and will give unexpected results {{crossref|(see also {{section link||Possible errors}}, below)}}.
* <s>'''Second unnamed parameter''' </s> ''(The canonical name is fetched from Wikidata, there is no longer any need to specify it manually. If supplied, it is ignored. <!-- If is appropriate not to show the name, use {{code 1= |name=none}} -->)''
* '''nlink= <name>''' Optional wikilink target. Name of the Wikipedia page that will be linked to. If used, the Unicode name (second parameter) has a wikilink to the article.
:* <code><nowiki>{{unichar|00A9|nlink=Copyright symbol}}</nowiki></code> &rarr; {{unichar|00A9|Copyright sign|nlink=Copyright symbol}}
:''Notes'':
::* The name of the page is case-sensitive as with all Wikipedia pages. 
::* It is possible to give a Wiktionary page here, using the syntax {{code|1= nlink=wikt:<target article>}}, which may be appropriate if there is no suitable Wikipedia article. For example:
:::* <code><nowiki>{{unichar|204A|nlink=wikt:⁊}}</nowiki></code> &rarr; {{unichar|204A|Tironian sign et|nlink=wikt:⁊}}
:*When used without a name (i.e., {{para|nlink}}, blank with no value), the link points to the character itself except when that causes a problem with [[WP:NCTR]] in which case the name of the character is used or an error is produced if no such name exists (see {{slink||Presentation effects}}).
:**<code><nowiki>{{unichar|00A9|nlink=}}</nowiki></code> &rarr; {{unichar|00A9|Copyright sign|nlink=}} is equivalent to <code><nowiki>{{unichar|00A9|nlink=&amp;#xa9;}}</nowiki></code>.
* '''cwith=''' Optional. The only valid content is ◌ or (or its HTML code, &amp;#x25CC;). This parameter is useful when the Unicode character is {{em|combining}} (such as a [[combining diacritic]]). Using {{para|cwith|◌}}, the character will be combined with the placeholder symbol, {{unichar|25CC|html=|nlink=dotted circle}}.
*: without {{para|cwith}}:
*::<code><nowiki>{{unichar|0485}}</nowiki></code> &rarr; {{unichar|0485}}
*: {{para|cwith}} with dotted circle:
*::<code><nowiki>{{unichar|0485|cwith=◌}}</nowiki></code> &rarr; {{unichar|0485|cwith=◌}} ''or''
*::<code><nowiki>{{unichar|0485|cwith=&amp;#x25CC;}}</nowiki></code> &rarr; {{unichar|0485|cwith=&#x25CC;}}
** Note that {{code|1=cwith=◌◌}} does not provide the desired result if the intention is to display a diacritic that spans two characters (such as those in the range U+035C to U+0362): the diacritic will be offset. In such cases, editors must emulate the template output by hand, because the correct HTML sequence is "first-character + combining-diacritic + second-character". Thus, for example, to show the combining double tilde U+0360, write {{code|1= U+0360 &#x25cc;&#x0360;&#x25cc;}} then (in {{tl|small}}), COMBINING DOUBLE TILDE. This produces U+0360 &#x25cc;&#x0360;&#x25cc; {{small|COMBINING DOUBLE TILDE}}.
**Use of any other character except dotted circle as input to {{para|cwith}} is deprecated; this restriction is not currently enforced but if any other character is used, the output (grapheme and description) is at best misleading.
* '''html=''' Optional. Adds the HTML character reference to the text, like <samp>&amp;#160;</samp> in the bracketed note. If a ''named character reference'' exists, like <samp>"&amp;nbsp;"</samp>, that is added too.  In the latter case, you do not need to add the values manually, just add {{para|html}}, blank.
* '''note=''' Optional. Adds a comment such as a clarification or explanatory note. For example, as the canonical names of idoegraphs are not generally helpful, the {{code|1= note=}} option permits an added comment such as {{unichar|4E95|note=[[Jingtian]]}}
* '''ulink'''  Optional. Creates a wikilink from the <samp>U+</samp> prefix. When used without a name (i.e., {{para|ulink}}, blank with no value), the article [[Unicode]] is used as the default value in the output: <samp><nowiki>[[Unicode|U+]]</nowiki></samp> producing [[Unicode|U+]]. This only needs to change if you have a reason to link elsewhere than [[Unicode]], e.g. to an article on a subset of Unicode characters.
*'''use=''' Optional. Sets the font-hinting template to get the glyph, since the character may not be present in a regular browser font. Default is {{tlx|unicode}}, other options are {{tlx|IPA}}, {{tlx|lang}} and {{tlx|script}}.
*'''use2=''' Optional. When setting {{para|use|lang}} or {{para|use|script}}, {{para|use2}} should be used to set the language (e.g. {{para|use2|fr}}) or the script (e.g. {{para|use2|Cyrs}}). A glyph may still not show as expected due to browser effects. For a detailed description, see each template's documentation.
*: <code><nowiki>{{unichar|0485|cwith=|use=script|use2=Cyrs}}</nowiki></code> &rarr; {{unichar|0485|cwith=|use=script|use2=Cyrs}}
* '''image=''' Optional. Allows for a graphic image file to represent the glyph; overrides the font completely. The filename should include the extension (like <samp>.svg</samp> or <samp>.png</samp>), but {{em|not}} the prefix <samp>File:</samp>.
* '''size=''' Optional. Can be used to set the size ''of the glyph''. The default value is <samp>125%</samp>. For the font, all CSS font-size style inputs are accepted: <kbd>7px</kbd>, <kbd>150%</kbd>, <kbd>2em</kbd>, <kbd>larger</kbd>.
** For example, <code><nowiki>{{unichar|0041|size=2em}}</nowiki></code> &rarr; {{unichar|0041|size=2em}}
** When using an ''image'' (file) instead of a font, this size can only accept sizes in <samp>px</samp> like <kbd>12px</kbd>. Default for images is <samp>10px</samp>.
* '''name = '''.  Optional; if used, the only permitted content is ''none''. This parameter is provided for the rare cases where only the code-point and the corresponding character are wanted. 
**For example, <nowiki>{{unichar|a9|name=none}}</nowiki> produces {{unichar|a9|name=none}}.
* '''alias = '''. Optional; if used, the only permitted content is ''yes''. The purpose of this parameter is to handle the very rare cases where the Unicode Consortium has identified that a name is seriously defective and misleading, or has a serious typographical error, and has defined a formal alias that applications are encouraged to use in place of the official character name. (See [[Unicode#Alias]] for details.)   
** For example, U+A015 {{sc2|YI SYLLABLE WU}} has the formal alias {{sc2|YI SYLLABLE ITERATION MARK}}. Thus, rather than <nowiki>{{unichar|A015}}</nowiki> &rarr; {{unichar|A015}}, the style <nowiki>{{unichar|A015|alias=yes}}</nowiki> &rarr; {{unichar|A015|alias=yes}} is preferred in most contexts.

<syntaxhighlight lang="wikitext">
{{unichar
| A9
| ulink = Universal Character Set characters
| image = 
| size  = 150%
| nlink = Copyright symbol
| note  = Example
}}
</syntaxhighlight> Produces:
* {{unichar
| A9
| ulink = Universal Character Set characters
| image = 
| size  = 150%
| nlink = Copyright symbol
| note  = Example
}}

===Presentation effects===
Since this template is aimed at presenting a ''formatted, inline description'', some effects are introduced to sustain this target.
* '''Showing space characters''': All space characters (those with [[Unicode_character_property#General_Category|General Category]]: Zs) are presented with a light-blue background, to show their actual presence and width: <code>{{unichar|00A0|No-break space|nlink=NBSP}}</code>.
*:Incidentally, the regular space {{background color|#CEEEF2|&nbsp;}} is replaced with <code>&amp;#00A0;</code> (NBSP) to prevent wiki-markup deleting it as repeated spaces.
* '''Removing formatting characters''': Formatting characters (those with [[Unicode_character_property#General_Category|General Category]]: Cf, Zl and Zp) are removed from the output. By definition, formatting characters have no glyph. By removing them they cannot have a formatting effect.
*:Exception: five Arabic Cf/formatting number markings U+0600..U+0603 and U+60DD, are shown. While Cf formatting characters usually have no glyph, these five have. By internally adding "(visible)" to the category, these characters are shown.
*'''Removing whitespace''': The template removes formatting code and surrounding whitespace from the input. A &lt;Return&gt; in the Name-input (possibly unintended) would frustrate the in-line behaviour expectation.
* '''Showing a label like &lt;control-0007&gt;''': Unicode states that a code point has ''[[Unicode character property#General Category|no name]]'' when it is one of these: a control character, a private use character, a surrogate, a not assigned code point (reserved), or a non-character. These code points instead should be referred to by using a "Code Point Label", such as &lt;private-use&gt; or &lt;private-use-E000>. In this situation, this template ''replaces'' the glyph with that label. This way, the correct presentation wins it over Unicode-usage to the letter of the law.
* "Control" general category=Cc: <code>&lt;control&gt;</code> or <code>&lt;control-''0007''&gt;</code>
* "Surrogate" general category=Cs: <code>&lt;surrogate&gt;</code> or <code>&lt;surrogate-''D800''&gt;</code>
* "Private Use": general category=Co: <code>&lt;private-use&gt;</code> or <code>&lt;private-use-''E000''&gt;</code>
* "Not a character" (minus the reserved code points, see below): general category=Cn: <code>&lt;not-a-character&gt;</code>, <code>&lt;non-character&gt;</code> or <code>&lt;not-a-character-''FFFE''&gt;</code>

The second parameter (Unicode name) is not presented, since it cannot exist. It is possible to create a link to an article.
*''Note'': A &lt;reserved> (unassigned) code point cannot be detected yet, and so is not presented with this label. These code points too are given Cn category.
*:(Background on <>-labels: A Name can never have <>-brackets at all. These rules prevent mixing up a name with an actual control-character. So it will not happen that a [[Bell character|bell]] rings when a page is opened that contains a Name of U+0007).

==Possible errors==
* The template produces an {{error|Error-message|tag=span}} when {{para|1}} (or first unnamed parameter), the hex value, is missing, empty, or invalid.
<!-- This line is history now, I believe but best not delete it just yet 
      * <code><nowiki>{{unichar|2019|nlink=}}</nowiki></code> → {{unichar|2019|nlink=}} – 
        the wikilink target "[[RIGHT SINGLE QUOTATION MARK]]" is not an existing article, 
        even though "[[Right single quotation mark]]" is. -->
* A non-hexadecimal input like {{!mxt|00G9}} produces an error (because {{!mxt|G}} or {{!mxt|g}} is not hexadecimal).
* Do not add the {{!mxt|U+}} prefix, as in {{!mxt|U+00A9}}. It will not be recognised.
* The glyph may be overruled and changed into a {{em|label}} like <samp>&lt;control-0007&gt;</samp>. These characters have no Unicode name. An {{para|nlink}} will be directly to the article (entered in a form like {{para|nlink|Bell signal}}). A blank value of just {{para|nlink=}} cannot work for <samp>&lt;{{var|label}}-{{var|hhhh}}&gt;</samp> characters (there is no character name at all to make into a link). This produces an error.
* A decimal-value input like {{para|1|98}} will be read as being hexadecimal value <samp>0098</samp>. There is {{em|no way}} that the template can detect you intended to enter <kbd>98<sub>10</sub>=62<sub>16</sub></kbd>. No warning is issued, and the wrong character, <samp>U+0098<sub>16</sub></samp>, will be shown ({{em|not}} <samp>U+0062</samp>).
* The {{code |1= alias=}} cannot be used to create an unofficial alias. 
* If {{code |1= alias=yes}} is used but the code point does not have an official alias, no name whatever will be displayed.
* The text provided in {{code |1=nlink=}} should be the normal name of an article. Do not type it in all caps as a red link will result.

==Tracking==
* {{clc|Category:Pages using Unichar with unknown parameters}}
==Technical notes==
The string "unichar" is used only in English Wikipedia, as a name for this template. It has no meaning outside this context.<br/>

The template uses these subtemplates:
* {{tl|unichar/main}} Accepts all the input from {{tlx|unichar}}. Calls several subtemplates to produce the textstrings, and then strings them together. Also checks for the error non-hex input.
* {{tl|unichar/ulink}} Creates a piped link for the <samp>U+</samp> prefix.
* {{tl|unichar/gc}} Determines the Unicode general category, when this category is special (like, for control characters).
* {{tl|unichar/glyph}} For rendering the glyph by font. Accepts {{para|image}}, which overrides the font. Also processes {{para|use}}, {{para|use2}}, {{para|size}}, {{para|cwith}}.
* {{tl|unichar/name}} Produces the formatted name of the character in {{Smallcaps|smallcaps}}. Accepts the {{para|nlink}} to create a piped wikilink to an article. When the [[Unicode character property#General Category|general category]] (gc) is special, the name will change into a <samp>&lt;{{var|label}}-{{var|hhhh}}&gt;</samp>.
* {{tl|unichar/notes}} Shows notes in parentheses (round brackets): <samp>HTML</samp> (from {{para|html}} named entity like <samp>&amp;nbsp;</samp> if that exists, using {{mlx|LoadData|Numcr2namecr}}); and the free-text {{para|note}}.
* Using the main template as an easy-input feature, there are few calculations done (actually only two hex2dec), and allows for adding default values not too deep in the templates.
* The value <code>&lt;#salted#&gt;</code> is used internally to pass through a non-defined input parameter. This value is correct when about the Unicode name, because it cannot have the characters <##>, and so [[Salting the earth|salted]] is the right word (meaning uninhibitable). For ease of code maintenance, it is used in various places in the code.

* Named entities for {{unichar|22C1|N-ARY LOGICAL OR}}: {{mlx|LoadData|Numcr2namecr|0x22C1}} &rarr; {{#invoke:LoadData|Numcr2namecr|0x22C1}}

====Issues====
* Unassigned code points, to be labelled &lt;reserved&gt;, cannot be detected.
* When using {{para|use-script}}, then {{para|use2}} needs lowercase (e.g. 0485, Cyrs or cyrs){{clarify|date=December 2017|reason=This makes no sense. Numerals have no case, and "Cyrs" is not lowercase but mixed-case.}}
* When using for one of the RTL formatting marks, its effect may break out of the template (text following the template goes RTL, too). As it is now, this requires extra code.

==Code charts==
{| class="wikitable" style=""
|-
! colspan=4 | Key to the Unicode Code Charts (Ch 24)[https://www.unicode.org/charts/About.html]
|-
!Symbol
!Meaning
!Examples
|-
|※ ||	Character name alias ||	※ LATIN SMALL LETTER GHA
|-
|<nowiki>=</nowiki> ||	Informative alias(es) ||	= barred o, o bar
|-
| <nowiki>•</nowiki> ||	Informative note ||
{{ubl
|1=• lowercase is 0275 ɵ
|2=• Portuguese, Estonian
|3=• this is a spacing character
}}
|-
|→ ||	Cross-reference || 	→ 0283 ʃ  latin small letter esh
|-
|≡ ||	Canonical decomposition mapping ||	≡ 0075 u 031B ◌̛
|-
|≈ ||	Compatibility decomposition mapping ||	≈ 006E n 006A j
|-
|~ ||	Standardized variation sequence ||	~ 2205 FE00 zero with long diagonal stroke overlay form
|}

==TemplateData==
{{TemplateData header}}
{{cot|Template data|bg=lightgrey}}
<templatedata>
{
	"params": {
		"1": {
			"label": "Hex value",
			"description": "Hexadecimal unicode codepoint",
			"example": "031A",
			"type": "string",
			"required": true
		},
		"2": {
			"label": "Character name",
			"description": "The canonical name is fetched from Wikidata, there is no longer any need to specify it manually. If supplied, it is ignored.",
			"example": "COMBINING LEFT ANGLE ABOVE",
			"type": "string",
			"deprecated": true
		},
		"ulink": {
			"example": "Phonetic symbols in Unicode",
			"type": "line",
			"description": "Add link to the Unicode HEX code point"
		},
		"image": {},
		"cwith": {
			"type": "string",
			"description": "(for combing characters only) add the following character before this combining character:",
			"example": "◌",
			"suggestedvalues": [
				"◌"
			]
		},
		"size": {
			"description": "Relative size of rendered character",
			"example": "200%",
			"type": "string"
		},
		"use": {
			"type": "string"
		},
		"use2": {
			"type": "string"
		},
		"nlink": {
			"type": "string",
			"description": "Add link to the Unicode character name"
		},
		"note": {
			"type": "line"
		},
		"html": {
			"label": "HTML code",
			"description": "When present, shows HTML named entity",
			"example": "html= shows \"&copy;\"",
			"type": "string"
		},
		"alias": {
			"suggestedvalues": [
				"yes"
			]
		},
		"name": {
			"suggestedvalues": [
				"none"
			],
			"description": "Hide the name of the character"
		}
	},
	"description": "Formats a Unicode character description inline.",
	"format": "inline",
	"paramOrder": [
		"1",
		"2",
		"ulink",
		"nlink",
		"cwith",
		"size",
		"image",
		"use",
		"use2",
		"html",
		"note",
		"alias",
		"name"
	]
}
</templatedata>
{{cob}}

==See also==
* This template uses: [[:Module:Numcr2namecr]] -- "[[List of XML and HTML character entity references|named character reference]]". Returns the named entity for decimal-to-mnemonic: 
:::{{mono|1=U+00A9}} &rarr; {{mono|1=169<sub>dec</sub>}} &rarr; {{mono|&amp;copy;}} <small>(as literal code, not the character)</small>
* {{Tl|Emoji}}
===External research links===
Useful links for researching Unicode characters:
* [http://unicode.org/charts/ Unicode.org] charts in PDF format, showing the U+ hex values.
* [https://www.fileformat.info/info/unicode/char/search.htm Fileformat.info search], to search by ''name'' (whole or partial), by U+ ''hex value'' or ''decimal value'', or by the font ''symbol'' (copy-paste it). Extra information provided per character. One character only.
* [http://www.branah.com/unicode-converter branah.com's] a multi-character Unicode converter.
* Unicode properties overview, e.g comma U+002C: [http://unicode.org/cldr/utility/character.jsp?a=002C]
<includeonly>{{sandbox other||{{#ifeq:{{FULLPAGENAME}}|Template:Unichar|[[Category:Unicode character templates]]}}
}}</includeonly>

{{Unicode templates}}