TODO list after PR #2584:

• Check PS_CHAR_ENCODING so it also works with Standard+ character set?
• Check arguments that are not processed by build_arg_string (e.g., text in Figure.text) Figure.text: Support non-ASCII characters in the 'text' parameter #2638
• Add a gallery example or a tutorial? Add a tutorial for typesetting non-ASCII characters #3389

Was trying to get the character ā (Latin small letter a with macron) to plot using either ISO-8859-4/ISO-8859-10/ISO-8859-13 in #2641 (comment), but doesn't work when setting pygmt.config(PS_CHAR_ENCODING="ISO-8859-4"), because we need to use --PS_CHAR_ENCODING inline according to https://docs.generic-mapping-tools.org/6.4/gmt.conf.html#term-PS_CHAR_ENCODING:

Note: Normally the character set is written as part of the PostScript header. If you need to switch to another character set for a later overlay then you must use --PS_CHAR_ENCODING=encoding on the command line and not via gmt gmtset.

Workaround was to use the composite character @!a\225 following https://docs.generic-mapping-tools.org/6.4/tutorial/session-2.html#plotting-text-strings. I'm not sure if it's worth adding --PS_CHAR_ENCODING as an option to plotting methods to make it easier. I think we discussed a while ago not to support double-dash -- inline options?

After PRs #2584, #2638, #3192, and #3199, PyGMT already provides basic support for non-ASCII characters.

In short, we're maintaining a big dictionary mapping non-ASCII characters to their octal codes. So users can pass a character like ɑ (alpha) and PyGMT will map it to @~\\141@~. There is no direct way to type ɑ using a keyboard (maybe there are shortcuts, but who can remember them all?), so users usually need to copy and paste from another source. However, many characters look similar. For example:

In [19]: "Ω" == "Ω"
Out[19]: False

In [20]: "Δ" == "∆"
Out[20]: False

In [21]: import unicodedata

In [22]: unicodedata.name("Ω")
Out[22]: 'OHM SIGN'

In [23]: unicodedata.name("Ω")
Out[23]: 'GREEK CAPITAL LETTER OMEGA'

In [24]: unicodedata.name("Δ")
Out[24]: 'GREEK CAPITAL LETTER DELTA'

In [25]: unicodedata.name("∆")
Out[25]: 'INCREMENT'

Since these characters are so similar, users may use the "incorrect" one and then get surprising results. Actually, we're using some incorrect characters in our mapping dictionary.

To solve the problem, we need character tables that users can copy. The official GMT documentation provides the tables (https://docs.generic-mapping-tools.org/dev/reference/octal-codes.html) in PNG/PDF format but they're not easy to copy. Better tables are available at

• https://www.compart.com/en/unicode/charsets/Adobe-Symbol-Encoding
• https://www.compart.com/en/unicode/charsets/Adobe-Standard-Encoding
• https://www.compart.com/en/unicode/charsets/x-Adobe-Zapf-Dingbats-Encoding

However, these tables are "incomplete" (some characters are missing) compared to the GMT ones. For example, in the Symbol table, \322 is ©, but in https://www.compart.com/en/unicode/charsets/Adobe-Symbol-Encoding, it's mapped to Unicode character U+F6DA, which belongs to the "Private Use Area" block (I guess there must be some historical reasons behind). So, instead of using the private, invisible U+F6DA, we should map © (U+00A9) to @~\\322@~. It also means we need to maintain our character tables.

This repository https://github.com/seisman/GMT-octal-codes maintains the mapping files that can map Unicode characters to GMT octal codes. Check the README files in that repository for how the mapping files are created.

With the well-maintained mapping files, we can refactor the mapping dictionary in the PyGMT project and add character tables for the supported encodings, as done in #3206.

@GenericMappingTools/pygmt-maintainers

After a series of PRs, I think we already provide good support for non-ASCII characters.

Things to note are:

• We're assuming that users are using the ISOLatin1+ encoding by default
• The "Standard" or "Standard+" encodings are not supported

Supporting "Standard"/"Standard+" or allowing any default encoding can be tricky because we need to inquire about the current character encoding using lib.get_default["PS_CHAR_ENCODING"] in some places (e.g., in the non_ascii_to_octal function).

We have some options:

1. Do nothing. Then we can close this issue.
2. In pygmt.begin(), check the current PS_CHAR_ENCODING. Raise a warning if PS_CHAR_ENCODING!=ISOLatin1+ and set PS_CHAR_ENCODING=ISOLatin1+. Assuming that users don't change PS_CHAR_ENCODING in the middle of a script.
3. Try hard to support "Standard"/"Standard+" encodings, which likely means we need to inquire the current character encoding in non_ascii_to_octal/_check_encoding, or we have to keep track of the changes of character encoding in a global variable.

I prefer option 2 and will work on it if there are no objections or comments in one week.

Acutally, there is option 4, i.e., adding --PS_CHAR_ENCODING=<encoding> even if the text string encoding is ISOLatin1+. I have implemented this option in #3611. Please see that PR for details.