docs/reference/glk-character-encoding.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 ]>
   5 <refentry id="chimara-Character-Encoding">
   6 <refmeta>
   7 <refentrytitle>Character Encoding</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>CHIMARA Library</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>Character Encoding</refname>
  13 <refpurpose>Latin-1 and Unicode characters</refpurpose>
  14 </refnamediv>
  15 <refsect1>
  16 <title>Description</title>
  17 <para>
  18 Glk has two separate, but parallel, APIs for managing text input and output. The basic functions deal entirely in 8-bit characters; their arguments are arrays of bytes (octets). These functions all assume the Latin-1 character encoding. Equivalently, they may be said to use code points U+00..U+FF of <ulink url="http://unicode.org">Unicode</ulink>.
  19 </para>
  20 <para>
  21 Latin-1 is an 8-bit character encoding; it maps numeric codes in the range 0 to 255 into printed characters. The values from 32 to 126 are the standard printable ASCII characters (<code>' '</code> to <code>'~'</code>). Values 0 to 31 and 127 to 159 are reserved for control characters, and have no printed equivalent.
  22 </para>
  23 <note><para>
  24 Note that the basic Glk text API does not use UTF-8, or any other Unicode character form. Each character is represented by a single byte &mdash; even characters in the 128..255 range.
  25 </para></note>
  26 <para>
  27 The extended, or <quote>Unicode</quote>, Glk functions deal entirely in 32-bit words. They take arrays of words, not bytes, as arguments. They can therefore cope with any Unicode code point. The extended functions have names ending in <quote><code>_uni</code></quote>.
  28 </para>
  29 <note><para>
  30 Since these functions deal in arrays of 32-bit words, they can be said to use the UTF-32 character encoding form. (But <emphasis>not</emphasis> the UTF-32 character encoding <emphasis>scheme</emphasis> &mdash; that's a stream of bytes which must be interpreted in big-endian or little-endian mode. Glk Unicode functions operate on long integers, not bytes.) UTF-32 is also known as UCS-4, according to the Unicode spec (appendix C.2), modulo some semantic requirements which we will not deal with here. For practical purposes, we can ignore the whole encoding issue, and assume that we are dealing with sequences of numeric code points.
  31 </para></note>
  32 <note><para>
  33 Why not UTF-8? It is a reasonable bare-bones compression algorithm for Unicode character streams; but IF systems typically have their own compression models for text. Compositing the two ideas causes more problems than it solves. The other advantage of UTF-8 is that 7-bit ASCII is automatically valid UTF-8; but this is not compelling for IF systems, in which the compiler can be tasked with generating consistent textual data. And UTF-8 is a variable-width encoding. Nobody ever wept at the prospect of avoiding that kettle of eels.
  34 </para></note>
  35 <note>
  36 <para>
  37 What about bi-directional text? It's a good idea, and may show up in future versions of this document. It is not in this version because we want to get something simple implemented soon. For the moment, print out all text in reading order (not necessarily left-to-right) and hope for the best. Current suggestions include a <code>stylehint_Direction</code>, which the game can set to indicate that text in the given style should be laid out right-to-left. Top-to-bottom (or bottom-to-top) may be desirable too. The direction stylehints might only apply to full paragraphs (like justification stylehints); or they might apply to any text, thus requiring the library to lay out <quote>zig-zag</quote> blocks. The possibilities remain to be explored. Page layout is hard.
  38 </para>
  39 <para>
  40 Another possibility is to let the library determine the directionality of text from the character set. This is not impossible &mdash; MacOSX text widgets do it. It may be too difficult.
  41 </para>
  42 <para>
  43 In the meantime, it is worth noting that the Windows Glk library does not autodetect directionality, but the CheapGlk library running on MacOSX does. Therefore, there is no platform-independent way to handle right-to-left fonts at present.
  44 </para>
  45 </note>
  46 </refsect1>
  47 </refentry>