DarkMavis: Created page with "{{Documentation subpage}} This template produces a formatted description of a Unicode character, to be used in-line with regular text. * `The character {{tlx|unichar..."`


2015-07-16T11:05:26Z
Created page with "{{Documentation subpage}} This template produces a formatted description of a Unicode character, to be used in-line with regular text.  * <code>The character {{tlx|unichar..."
New page
{{Documentation subpage}}

This template produces a formatted description of a [[Unicode]] character, to be used in-line with regular text. 

* <code>The character {{tlx|unichar|<nowiki>a9|Copyright sign</nowiki>}} is about intellectual property.</code> →

:The character {{unichar|a9|Copyright sign}} is about intellectual property.

==Usage==

This template produces a ''formatted description'' of a [[Unicode]] character, to be used ''in-line'' with regular text. It needs Unicode hexadecimal value and name as input, like <code><nowiki>{{unichar|00A9|Copyright sign}}</nowiki></code> → {{unichar|00A9|Copyright sign}}.



It follows the standard Unicode presentation of a character such as using the pattern "U+00A9", and allowing Unicode's all caps naming habit (which is undesired in Wikipedia text) by using {{smallcaps|small caps}}. The hexadecimal value is required (e.g. A9), other input is optional. The actual glyph is looked for in a font that covers Unicode quite well, and this can be set more specific to e.g. language or IPA-specialized fonts. To show the glyph, the font character can be overridden with an image. A wikilink to an article and another to Unicode can be created, it is possible to add (in brackets), the calculated decimal value, HTML-notations, and a note.



Some special code points are given extra care, like controls and space characters. These special code points are automatically detected by the [[Template:unichar/gc|unichar/gc]] sub-template.



===Examples===

* <code><nowiki>{{unichar|00A9|Copyright sign}}</nowiki></code> → {{unichar|00A9|Copyright sign}}

* <code><nowiki>{{unichar|00A9|Copyright sign|nlink=Copyright symbol}}</nowiki></code> → {{unichar|00A9|Copyright sign|nlink=Copyright symbol}}

* <code><nowiki>{{unichar|00A9|Copyright sign|nlink=Copyright symbol|note=See also [[Copyleft]] symbol}}</nowiki></code> → {{unichar|00A9|Copyright sign|nlink=Copyright symbol|note=See also [[Copyleft]] symbol}}

* <code><nowiki>{{unichar|00A9|Copyright sign|nlink=Copyright symbol|dec=|html=}}</nowiki></code> → {{unichar|00A9|Copyright sign|nlink=Copyright symbol|dec=|html=}}

* <code><nowiki>{{unichar|00A0|No-break space|note=NBSP}}</nowiki></code> → {{unichar|00A0|No-break space|note=NBSP}}

* <code><nowiki>{{unichar|0007|nlink=Bell character}}</nowiki></code> → {{unichar|0007|nlink=Bell character}}



===Parameters===

The blank template, with all parameters, is as follows:

<pre>

{{unichar

| <!-- hex value, code point (do not add the "U+")  -->

| <!-- Unicode name -->

| ulink =

| image =

| cwith =

| size  =

| use   =

| use2  =

| nlink =

| dec   =

| html  =

| note  =

}}

</pre>



Inline version:

<pre>

{{unichar| <!-- hex value (do not add "U+") -->| <!-- Unicode name -->|ulink= |image= |cwith= |size= |use= |use2= |nlink= |dec= |html= |note= }}

</pre>



* '''First parameter''', '''1=''' Unnamed, required (prefix "1=" may be omitted). 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 (see Error messages, below).



* '''Second parameter''', '''2=''' Unnamed (prefix "2=" may be omitted). The Unicode name of the character. The template uses this input as the {{Smallcaps|name in small caps}}, forced into these small capitals whatever the input. This name may differ from the name of the corresponding Wikipedia article (see below: nlink=).



* '''nlink=''' Optional.wikilink.  Name of the Wikipedia page that will be linked to. If used, the Unicode name (second parameter) has a wikilink to the article. When the article name and the Unicode name are the same, using a straight "nlink=" without a name will do. <br/>

::For control characters using the ''nlink'' parameter, the Unicode name parameter is not used: the ''nlink'' parameter is displayed instead, without small caps.

:''Note'': the name of the page is case sensitive as with all wikipages.



:<code><nowiki>{{unichar|00A9|Copyright sign|nlink=Copyright symbol}}</nowiki></code> &rarr; {{unichar|00A9|Copyright sign|nlink=Copyright symbol}}

:<code><nowiki>{{unichar|00A3|Pound sign|nlink=}}</nowiki></code> &rarr; {{unichar|00A3|Pound sign|nlink=}}.



* '''ulink'''  Optional. Creates a wikilink in the "U+" prefix. When used without name ({{code|ulink={{!}}}}), the default value, [[Unicode]] page, is used: [[Unicode|U+]].



* '''dec=''' Optional. Adds the decimal value to the text, in the bracketed note.



* '''html=''' Optional. Adds the HTML character reference to the text, like <code>&amp;#160;</code> in the bracketed note. If a ''named character reference'' exists, like <code>"&amp;nbsp;"</code>, that is added too.



*'''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 {{tl|unicode}}, other options are {{tl|IPA}}, {{tl|lang}} and {{tl|script}}. When setting "use=lang" or "use=script", '''use2''' should be used to set the language ("use2=fr") or the script ("use2=Cyrs"). A glyph may still not show as expected due to browser effects. For a detailed description, see the templates documentation.

: <code><nowiki>{{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA|cwith=|use=script|use2=Cyrs}}</nowiki></code> &rarr; {{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA|cwith=|use=script|use2=Cyrs}}



* '''image=''' Optional. Allows for a ''file'' (graphic image) to represent the glyph, overrules the font completely. The filename should include the extension like ".svg", but ''not'' the prefix "File:".



* '''cwith=''' Optional. Useful when the Unicode character is ''combining''. Using {{code|1=cwith=}} adds a space before the character, allowing the combining effect. So when used with a character like {{code|1=cwith=a}}, the character will be combined with the letter "a". In Unicode, a general glyph used to place a combined character is {{unichar|25CC|DOTTED CIRCLE|html=}}.

: without '''cwith=''':

::<code><nowiki>{{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA}}</nowiki></code> &rarr; {{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA}}

: '''cwith=''' without parameter:

::<code><nowiki>{{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA|cwith=}}</nowiki></code> &rarr; {{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA|cwith=}}

: '''cwith=''' with dotted circle:

::<code><nowiki>{{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA|cwith=&amp;#9676;}}</nowiki></code> &rarr; {{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA|cwith=&#9676;}}



* '''size=''' Optional. Can be used to set the size ''of the glyph''. By default "size=125%". For the font, all font-size style inputs are accepted: "7px", "150%", "2em", "larger".

:<code><nowiki>{{unichar|0041|LATIN CAPITAL LETTER A|size=2em}}</nowiki></code> &rarr; {{unichar|0041|LATIN CAPITAL LETTER A|size=2em}}

: When using an ''image'' (file) instead of a font, this size can only accept sizes in px like "12px". Default for images is "10px" .



<pre>

{{unichar

| A9

| Copyright sign

| ulink = Universal Character Set characters

| image = 

| size  = 150%

| nlink = Copyright symbol

| note  = Example

}}

</pre> Produces:

* {{unichar

| A9

| Copyright sign

| 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 <nowiki> </nowiki> 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 <Return> in the Name-input (possibly unintended) would frustrate the in-line behaviour expectation.



* '''Showing a label like <control-0007>''': Unicode states, that an 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 <private-use> or <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><control></code> or <code><control-''0007''></code>

* "Surrogate" general category=Cs: <code><surrogate></code> or <code><surrogate-''D800''></code>

* "Private Use": general category=Co: <code><private-use></code> or <code><private-use-''FFA0''></code>

* "Not a character" (minus the reserved code points, see below): general category=Cn: <code><not-a-character></code>, <code><non-character></code> or <code><not-a-character-''FFA0''></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 <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 parameter #1 (hex value) is missing.

* A non-hexadecimal input like ''00G9'' produces an error (Because ''G/g'' is not hexadecimal).

* Do not add the U+-prefix like ''U+00A9''. It will not be recognised.

* If the template ''only'' shows the code point number, like "{{unicode|2038}}", you're probably using the wrong template {{tlb|unicode}}, instead of {{tlb|unichar}}.

* The glyph may be overruled and changed into a ''label'' like <control-0007>. These characters have no Unicode name. An nlink will be directly to the article (entered in "nlink=Bell signal"). A blank like this "nlink=", (which links fine for regular characters like Pound sign), cannot work for <labeled> characters (there is no character name at all to make into a link). This produces an error.

* A decimal value input like ''1=98'' will be read as being hexadecimal value 0098. There is ''no way'' that the template can detect you intended to enter 98<sub>10</sub>=62<sub>16</sub>.No warning is issued, and the wrong character, U+0098<sub>16</sub>, will be shown (''not'' U+0062).



===Technical notes===

The word "unichar" is used only in this English Wikipedia, as a name for this template. It has no meaning outside.<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 "U+" 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 "image=" that overrules the font. Uses also "use", "use2", "size", "cwith".

* {{tl|unichar/na}} Produces the formatted name of the character in {{Smallcaps|smallcaps}}. Accepts the "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 <''label''-''hhhh''>.

* {{tl|unichar/notes}} - Produces the three optional notes in brackets: ''decimal value'', ''HTML-character reference'' (both decimal and by name like {{code|&amp;nbsp;}} if that exists using {{tlx|numcr2namecr}}) and the free text ''note'' as provided by the editor. Also does the brackets themselves.



* Using the main template as an input-easy feature, there are few calculations done (actually only two hex2dec), and allows for adding default values not too deep in the templates.



* The value "<#salted#>" is used internally to pass through a non-defined input parameter. This value is correct when about the Name, because a Unicode name 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 more places around.



====Issues====

* Unassigned code points, to be labelled <reserved>, cannot be detected.

* When using use-script, use2 needs lowercase (e.g. 0485, Cyrs or cyrs)

* When using for one off the RTL formatting marks, its effect may break out of the template (text following goed rtl too). As it is now, this requires extra code.



===See also===

* {{tl|unicode}} - Produces rare characters, using fonts that cover Unicode more widely.

{{Unicode templates}}



===External links===

Useful links for researching Unicode characters:

* [http://unicode.org/charts/ Unicode charts], gives the chart (in PDF) on which the U+value is located.

* [http://www.fileformat.info/info/unicode/char/search.htm Fileformat.com search], to search by ''name'' (whole or partial), by U+ ''hex value'' or ''decimal value'', by the font ''symbol'' (copy-past it). Extra information per character. One character only.

* [http://www.branah.com/unicode-converter] a multi-character converter.

<includeonly>

<!-- CATEGORIES AND INTERWIKIS HERE, THANKS -->

[[Category:Unicode templates]]

</includeonly>
Template:Unichar/doc - Revision history

DarkMavis: Created page with "{{Documentation subpage}} This template produces a formatted description of a Unicode character, to be used in-line with regular text. * The character {{tlx|unichar..."

DarkMavis: Created page with "{{Documentation subpage}} This template produces a formatted description of a Unicode character, to be used in-line with regular text. * `The character {{tlx|unichar..."`
