ଛାଞ୍ଚ:Unichar/doc

This is a documentation subpage for ଛାଞ୍ଚ:Unichar.
It may contain usage information, categories and other content that is not part of the original ଛାଞ୍ଚ page.

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 {{unichar|00A9|Copyright sign}} → U+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 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.

Examples

{{unichar|00A9|Copyright sign|nlink=Copyright symbol}} → U+00A9 © copyright sign
{{unichar|00A9|Copyright sign|nlink=Copyright symbol|note=See also [[Copyleft]] symbol}} → U+00A9 © copyright sign (See also Copyleft symbol)
{{unichar|00A9|Copyright sign|nlink=Copyright symbol|dec=|html=}} → U+00A9 © copyright sign (169_decimal, HTML: © ©)
{{unichar|00A0|No-break space|note=NBSP}} → U+00A0 no-break space (NBSP)
{{unichar|0007|BELL|nlink=Bell character}} → U+0007 <control-0007> Bell character

Parameters

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

{{unichar
| 
| 
| ulink =
| image =
| cwith =
| size  =
| use   =
| use2  =
| nlink =
| dec   =
| html  =
| note  =
}}

First parameter, 1= Unnamed, required (prefix "1=" may be omitted). The hexadecimal value of the code point, e.g. "00A9".

Notes: The parameter accepts input like "A9", "a9" and "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 name in small caps, forced into capitals whatever the input. This name may differ from the name of the corresponding Wikipedia article (see below: nlink=).

nlink= Optional. Name of the Wikipedia 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 is enough.

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

{{unichar|00A9|Copyright sign|nlink=Copyright symbol}} → U+00A9 © copyright sign

{{unichar|00A3|Pound sign|nlink=}} → U+00A3 £ pound sign.

ulink Optional. Creates a wikilink in the "U+" prefix. When used without name ("ulink=|"), the default value "Unicode" is used: U+.

dec= Optional. Adds the decimal value to the text, in a bracketed note.
html= Optional. Adds the HTML character reference to the text, like   in a bracketed note. If a named character reference exists, like " ", 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 {{unicode}}, other options are {{IPA}}, {{lang}} and {{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.
ímage= 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 "cwith=" adds a space before the character, allowing the combining effect. So when used with a character like "cwith=a", the character will be combined with the letter "a". In Unicode, a general glyph used to place a combined is U+25CC ◌ dotted circle (HTML: ◌).
{{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA|cwith=}} → U+0485 ҅ combining cyrillic dasia pneumata
{{unichar|0485|COMBINING CYRILLIC DASIA PNEUMATA|cwith=|use=script|use2=Cyrs}} → U+0485 ҅ combining cyrillic dasia pneumata

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".

{{unichar|0041|LATIN CAPITAL LETTER A|size=2em}} → U+0041 A latin capital letter a

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

{{unichar
| A9
| Copyright sign
| ulink = Unicode character mapping
| image = 
| size  = 150%
| nlink = Copyright symbol
| note  = Example
}}

Produces:

U+00A9 © copyright sign (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 general category: Zs) are presented with a light-blue background, to show their actual width: U+00A0 no-break space.

Also, the regular space is replaced with &#00A0; (NBSP) to prevent wiki-markup deleting it as repeated spaces.

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 name like <control-0007>?: Unicode states, that an code point has 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. The second parameter is still presented in small caps. This way, the correct presentation wins it over Unicode-usage to the letter of the law.

Note: A <reserved> (unassigned) code point cannot be detected yet, and so is not presented with this label.

(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 rings when a page is opened that contains a Name of U+0007).

Possible errors

The template produces an Error-message when parameter #1 (hex value) is missing.
A non-hexadecimal input like 00G9 produces an error.
Allowing input with the U+-prefix like U+00A9 is 'expensive' and would slow down the refreshing the pages too much. Therefore using the prefix "U+" produces an error.
If the template only shows the code point number, like "2038", you're probably using the wrong template {{unicode}}, instead of {{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₁₀=62₁₆.No warning is issued, and the wrong character, U+0098₁₆, 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.

The template uses these subtemplates:

{{unichar/main}} Accepts all the input from {{unichar}}. Calls several subtemplates to produce the textstrings, and then strings them together. Also checks for the error non-hex input.
{{unichar/ulink}} creates a piped link for the "U+" prefix.
{{unichar/gc}} determines the Unicode general category, when this category is special (like, for control characters).
{{unichar/glyph}} for rendering the glyph by font. Accepts "image=" that overrules the font. Uses also "use", "use2", "size", "cwith".
{{unichar/na}} Produces the formatted name of the character in smallcaps. Accepts the "nlink=" to create a piped wikilink to an article. When the general category (gc) is special, the name will change into a <label-hhhh>.
{{unichar/notes}} - Produces the three optional notes in brackets: decimal value, HTML-character reference (both decimal and by name like &nbsp; if that exists using {{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 trough a non-defined input parameter. This value is correct when about the Name, because a Unicode name cannot have the characters <##>, and so 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)
Bidi-controls do work: U+202B ‭right-to-left embedding (RLE: needs &202D; LRO to prevent RTL-writing!), U+202E ‭right-to-left override (RLO; needs 202D LRO to prevent RTL-writing).

External links

Useful links for researching Unicode characters:

Unicode charts, gives the chart (in PDF) on which the U+value is located.
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.