*! version 1.0 09jun2015

Title

grtext -- Inserting nonstandard characters in graph text

Syntax

grtext hexadecimal_number

Description

The purpose of grtext is to help creating graph texts with
nonstandard characters, i.e., characters that are not directly available on the
keyboard. grtext uses Unicode and requires Stata version 14 or higher;
users of earlier Stata versions may benefit from the user-written
asciiplot command; see later.

grtext reads a hexadecimal number and displays the corresponding
decimal number and the corresponding Unicode character. The decimal code is
stored in r(b10) and the character in r(char).

Find some background information on ASCII and Unicode codes in the
Remarks section of this help file.

Examples

You may find the Unicode code for a character by the code charts from the
Unicode Consortium, by Windows' charmap command, by similar functions in
MS Word and Open Office, or by Mac's Character Viewer. However, these facilities
all display the codes in hexadecimal format, while Stata's uchar(#)
function requires the code in decimal format.

We want to include the symbol for Indian Rupees (₹) in an axis
title. Use Unicode Corsortium's code charts,
http://unicode.org/charts/ and select:

Other Symbols > Currency Symbols

Locate the ₹ symbol and find its hexadecimal code, 20B9. To see
the code in decimal format, type:

. grtext 20b9

Hex: 20B9 Dec: 8377 uchar(8377) = ₹

Hexadecimal Unicode codes are sometimes prefixed by "U+" or
"0x". You may include or omit these prefixes when entering the code. Any
leading zeros may be omitted, and you may use uppercase or lowercase letters.

Here are two ways to enter the character in a graph text:

Method 1: Copy-and-paste ₹ from the Results window
to the graph command:

. graph command , ytitle("₹ per 100 $") ...

Method 2: Create a local macro containing the character, and
insert it in the graph command:

. local INR = uchar(8377)

. graph command , ytitle("`INR' per 100 $") ...

The ustrunescape() function uses the hexadecimal code directly,
albeit in a slightly more complex style:

. local INR = ustrunescape("\u20b9")

Alternatives

The Character Map in Windows and the Character Viewer on a Mac display
hexadecimal Unicode codes, but they also allow to copy characters directly to
the Command window or the Do-file Editor. To open the Character Map in Windows,
press Windows_key+R and enter charmap in the dialog that
opens.

Here we want to write the name of the Pravda newspaper with Cyrillic
characters. In the Caracter Map, locate the Cyrillic character set and
select the characters Правда. Click on the Copy button; go to the Do-file
Editor, and paste the text to the graph command:

. graph_command , title("Правда circulation 1912-1991") ...

The help for smcl describes how to insert some Western European
characters in graphs and other SMCL text without using the extended ASCII or
Unicode code. For example, you can generate the letter Æ with
{c AE }, the letter ç with
{c c, }, and the Euro symbol with
{c C= }. However, the list of characters is limited,
and nonstandard characters used in other than Western European languages are not
included.

The help for graph text describes SMCL tags for Greek
characters and for some other symbols and characters. To write a Greek
sigma, enter {&sigma}. To write a capital sigma, enter
{&Sigma}.

The user-written asciiplot command displays a graph with plain and
extended ASCII codes with their decimal numbers; it works both with Stata 14+
and with Stata <14. To install it, type:

. ssc install asciiplot

Remarks

Prior to version 14, Stata used ASCII encoding of characters. The
codes for plain ASCII are 33-127; for extended ASCII they are 128-255. There
are several extended ASCII encoding schemes, for example, Latin 1 and
Windows-1252 for Western European Languages, Latin 2 for some Central
and Eastern European languages, and Latin 4 using the Cyrillic
alphabet. Thus, the same extended ASCII code may display different characters
by computers using different encoding schemes.

From version 14, Stata uses Unicode encoding of characters. This
gives access to thousands of characters and symbols, including Arabic,
Cyrillic, Chinese, and other alphabets. The Unicode code point is the number
we use with uchar(#) and other functions, but behind it is a more complex
encoding (UTF-8) where each character is defined by one to four 8-bit
bytes. For the characters represented in plain ASCII and in the Latin 1
extended ASCII encoding, the Unicode code point is the same as the ASCII code.

Author

Svend Juul

Aarhus University

sj@ph.au.dk

Also see

help for graph text

help for smcl

help for unicode (Stata 14+ only)

help for uchar() (Stata 14+ only)