docs/reference/glk-output.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-Output">
   6 <refmeta>
   7 <refentrytitle>Output</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>CHIMARA Library</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>Output</refname>
  13 <refpurpose>Printing basics</refpurpose>
  14 </refnamediv>
  15 <refsect1>
  16 <title>Description</title>
  17 <para>
  18 When you are sending text to a window, or to a file open in text mode, you can print any of the printable Latin-1 characters: 32 to 126, 160 to 255. You can also print the newline character (linefeed, <keycombo action="simul"><keycap function="control">control</keycap><keycap>J</keycap></keycombo>, decimal 10, hex 0x0A.)
  19 </para>
  20 <para>
  21 It is <emphasis>not</emphasis> legal to print any other control characters (0 to 9, 11 to 31, 127 to 159). You may not print even common formatting characters such as tab (<keycombo action="simul"><keycap function="control">control</keycap><keycap>I</keycap></keycombo>), carriage return (<keycombo action="simul"><keycap function="control">control</keycap><keycap>M</keycap></keycombo>), or page break (<keycombo action="simul"><keycap function="control">control</keycap><keycap>L</keycap></keycombo>).
  22 </para>
  23 <note><para>
  24 As usual, the behavior of the library when you print an illegal character is undefined. It is preferable that the library display a numeric code, such as <quote><computeroutput>\177</computeroutput></quote> or <quote><computeroutput>0x7F</computeroutput></quote>, to warn the user that something illegal has occurred. The library may skip illegal characters entirely; but you should not rely on this.
  25 </para></note>
  26 <para>
  27 Printing Unicode characters above 255 is a more complicated matter &mdash; too complicated to be covered precisely by this specification. Refer to the Unicode specification, and good luck to you.
  28 </para>
  29 <note><para>
  30 Unicode combining characters are a particular nuisance. Printing a combining character may alter the appearance of the previous character printed. The library should be prepared to cope with this &mdash; even if the characters are printed by two separate glk_put_char_uni() calls.
  31 </para></note>
  32 <para>
  33 Note that when you are sending data to a file open in binary mode, you can print any byte value, without restriction. See <link linkend="chimara-File-Streams">File Streams</link>.
  34 </para>
  35 <para>
  36 A particular implementation of Glk may not be able to display all the printable characters. It is guaranteed to be able to display the ASCII characters (32 to 126, and the newline 10.) Other characters may be printed correctly, printed as multi-character combinations (such as <quote><computeroutput>ae</computeroutput></quote> for the <quote>&aelig;</quote> ligature), or printed as some placeholder character (such as a bullet or question mark, or even an octal code.) You can test for this using #gestalt_CharOutput.
  37 </para>
  38 </refsect1>
  39 </refentry>