KOI-8 Step-By-Step for the X Window System

©1996 Marat Boshernitsan

This page has been accessed times since its creation on February 14, 1996.

06/12/96 Some long-awaited revisions had been done to this document. Check out the Table of Contents for details. Watch out for bugs.

02/14/96 Please beware that this page is constantly evolving. Things may not work as advertised and there is a high probability of errors and omissions. If you want to see this page improved, please send your comments to MBoshernitsan@lbl.gov

Coming (soon?):

Table of Contents


This document provides step-by-step instructions on how to set up Cyrillic (KOI-8) fonts for the X Window System (X11R5/R6). These instructions are aimed at the average user with moderate knowledge of the UNIX environment, i.e. one should know how to log in, log out, run commands and use some editor. If you are uncomfortable with X Window System or UNIX, take a look at
Introduction to UNIX and/or Introduction to X Windows.

How To Install Fonts

The instructions assume that you are like the most of us (i.e. without root access) and you are installing the fonts in your home directory. Presumably, if you are a system administrator, you can infer from these instructions how to set up Cyrillic fonts so that they are globally accessible.

NOTE: If your X server is configured to use the font server for fonts (sure thing if you are using an X terminal), you have no choice but to install the fonts globally, where the font server can find them. You can tell if you are using a font server by typing "xset q" at the prompt and looking toward the end of the output for the section named "Font Path". If this section contains a whole bunch of path names, you are probably in the good shape. If, instead, it contains "tcp/...", you are out of luck -- go bug your system administrator.

  1. Get the Cronyx font set as GNUzipped tar archive (354K) or Compressed tar archive (514K). The complete installation (assuming you removed BDF files) takes about 1M of disk space. The instructions that follow, assume that you are using Cronyx font set; you may or may not be able to follow these instructions with other font sets.

  2. Go to your home directory and unpack the font files:
    % cd
    If you have downloaded the .gz file:
    % gunzip < cronyx.tar.gz | tar xvf -
    or, if you have downloaded the .Z file:
    % zcat cronyx.tar.Z | tar xvf -
    This should create cronyx subdirectory with a whole bunch of files in it.

  3. Go to cronyx directory and compile the fonts:
    % cd cronyx
    % make
    This will compile the fonts for the architecture you are using. To save the disk space, the font files are also compressed by compress(1). If your server cannot read compressed fonts, you can decompress them by typing "uncompress *.Z" at the prompt or editing the Makefile to prevent compression in the first place.

    Note on font formats (read this if you are curious): The fonts are distributed in Binary Distribution Format (BDF), although all X servers can understand this format, the files in this format are large and the loading of the fonts is slower (not to mention the disk space). Compilation converts the font files into Portable Compiled Format (PCF). The files in this format are much smaller and are optimized to be read by the platform for which they are compiled. Although, other platforms can read PCF as well (hence the name), the reformatting takes time, so compile on the platform you use the most.

  4. Make sure the cronyx directory is readable and searchable by others and files in this directory are readable by others:
    % chmod o+rx .
    % chmod o+r *
    Also, make sure that all directories leading to it are also readable and searchable by others. Not doing so, may result in
    mysterious error messages from xset(1).

  5. Let the server know where to find the fonts:
    % xset fp+ `pwd`
    % xset fp rehash
    If you get mysterious error messages about failing requests, see the
    FAQ list for possible causes.

  6. Check your installation:
    % xlsfonts '*koi8*'
    You should see a listing of about 70 fonts scroll by your screen. If xlsfonts(1) replies with "pattern *koi8* unmatched", you've got a problem.

    See the FAQ list for possible solutions

  7. (Optional) Remove the BDF files from font directory to preserve disk space:
    % rm *.bdf
Congratulations, the fonts are now installed and may be used by the applications!

How To Set Up Software

  1. X server startup files. When you log in at the X terminal the X server executes certain startup files. You will need to edit these files and add commands so that the server can find Cyrillic fonts. Most common files are .xinitrc and .xsession. These reside in your home directory; however, if you don't have any of these, consult a local guru on how to customize your environment. Add the following lines to the beginning of the startup file that you are using (if you have both and are not sure which one is being used, add these lines to both files just to be on the safe side):
    xset fp+ <full-path-to-font-dir>
    xset fp rehash
    Where <full-path-to-font-dir> is precisely what pwd(1) returns within the font directory.

  2. X server resource files. When you log in at the X terminal, the X server reads a resource database file. A resource file is the usual place to specify fonts, colors and other things for the applications. Such file is usually called .Xdefaults or .Xresources and is located in your home directory. If you cannot find either of these files, create one, say .Xresources, and add the following line in your start up file before anything else:
    xrdb -l .Xresources
    You can leave the file empty for now -- you will want to add stuff to it later.

  3. To set up Netscape 1.x to use Cyrillic fonts, add the following lines to resource file:
    Netscape*documentFonts*registry:        koi8
    Netscape*documentFonts*encoding:        r
    and reload the resource database:
    % cd
    % xrdb -l <resource-file-name>
    Now, restart Netscape, and test Cyrillic fonts.

  4. To set up Netscape 2.x to use Cyrillic fonts, add the following lines to resource file:
    Netscape*documentFonts.defaultFont*iso-8859-2.prop:  cronyx-times-120-noscale
    Netscape*documentFonts.defaultFont*iso-8859-2.fixed: cronyx-courier-100-noscale
    Netscape*documentFonts.charsetlang*iso-8859-2:       Russian
    Netscape*documentFonts.charset*koi8-r:               iso-8859-2
    Netscape*menuBar*latin2.labelString:                 Russian (KOI-8)
    and reload the resource database:
    % cd
    % xrdb -l <resource-file-name>
    Now, restart Netscape, go to the Options menu and select General Preferences.... This should open a dialog box. Select Fonts, change encoding to Russian (iso-8859-2), change proportional font to Times (Cronyx), and change fixed font to Courier (Cronyx). You can switch to Cyrillic by going to the Options/Document Encoding menu and selecting Russian (KOI-8) encoding. You should now be ready to test Cyrillic fonts.

    See the FAQ list for information on how to set up Cyrillic fonts in Mail, News, Address Book, Bookmark windows, menus, dialogs, etc.

  5. (Note, the following has been tested with Netscape 3.0b4: your mileage may vary with older beta releases)

    Netscape 3.x (finally) includes some limited support for Cyrillic characters, so you only need to add two lines to the resource file, telling Netscape which fonts to use:

    Netscape*documentFonts.defaultFont*koi8-r.prop:      cronyx-times-120-noscale
    Netscape*documentFonts.defaultFont*koi8-r.fixed:     cronyx-courier-100-noscale
    That's it. You should now reload the resource database, restart Netscape and test Cyrillic fonts.

    Unfortunately, Netscape 3,x still does not use Cyrillic fonts outline/subject lists for Mail, News, Address Book, and Bookmark windows. Consult FAQ list for information on how to set this up.

  6. To use Cyrillic with Emacs 19.x, you will first need to make sure that Emacs is using Cyrillic fonts. If you have followed the above instructions exactly and your Emacs is using some fixed-width font, you are probably in good shape. Otherwise, you will need to add the following line to the resource file:
    emacs*font:  -cronyx-fixed-medium-r-normal--13-120-75-75-c-80-koi8-r
    Don't forget to reload the resource database and restart Emacs. To be able to view and input Cyrillic with Emacs, you will also need to turn on the support for international characters by adding the following lines to .emacs file (this file may be in your home directory, if it's not there -- create it):
    (standard-display-european t)
    (set-input-mode (car (current-input-mode))
                    (nth 1 (current-input-mode))
    You will also need to set up your keyboard to be able to input Cyrillic characters. See Frequently Asked Questions list for information on how to do that.

    A better approach that does not require special keyboard setup and allows Emacs commands to be issued in KOI-8 insertion mode, is to use russian.el mode. This file is available at ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive/packages/russian.el.Z. You will need to uncompress (using uncompress(1)) and install this file in cronyx directory, and add the following line to your .emacs file (Note that you no longer need to add any of the stuff mentioned above):

    (load-file "~/cronyx/russian.el")
    See the beginning of the russian.el file for the information on how to use this mode.

  7. Most other software that uses fixed fonts, will use Cyrillic fonts automatically. Software that requires some fancier font selection, will have to be configured individually. Please refer to your software documentation. (Hint: in most cases you will need to add some lines to the resource file, use the above instructions for Netscape as an example)

    See the FAQ list for instructions on configuring keyboard under X Window System.

Cyrillic font test for browsers

This is what your Cyrillic letters should look like in your browser with the above setup (these are images):

Proportional font:

Fixed font:

This is what Cyrlillic letters look like in your browser:

Proportional font:

Fixed font:

Frequently Asked Questions

  1. Mysterious error messages from xset(1)

    The xset(1) program (part of X11 distribution) is notorious for indecipherable error messages such as these:

    X Error of failed request:  BadValue (integer parameter out of range for operation)
      Major opcode of failed request:  51 (X_SetFontPath)
      Value in failed request:  0xa
      Serial number of failed request:  4
      Current serial number in output stream:  6
    The version supplied with X11R6 is a little better since it is somewhat more eloquent, but even its error messages are sometimes difficult to understand.

    If you get something like the above from xset(1) the first things to check are:

    • Valid path name. You should give the correct path name to the font directory. If you are running xset(1) from a shell script, don't forget that some shells (sh, ksh) do not understand the tilde (~) shortcut for the home directory.
    • Font directory permissions. The font directory as well as all directories leading to it must be readable and searchable by other and font files must be readable by other, otherwise, the X server can't find fonts.
    • Missing fonts.dir. This file must be present so that the server can map font names to files. If this file is missing, you can create it by typing "mkfontdir ." in font directory.
  2. "Pattern unmatched" error from xlsfonts(1)

    First off, make sure that you are doing "xlsfonts '*koi*'" (an asterisk before and after "koi"). If this does not show any fonts, try looking at fonts.dir in cronyx directory, it should show something like this:

    koi10x20.pcf.Z -cronyx-fixed-medium-r-normal--20-200-75-75-c-100-koi8-r
    koi12x24.pcf.Z -cronyx-fixed-medium-r-normal--24-170-100-100-c-120-koi8-r
    koi10x16b.pcf.Z -cronyx-fixed-bold-r-normal--16-120-100-100-c-80-koi8-r
    If this files is empty, or not there, it is possible that your X server does not recognize compressed fonts, in that case, type "uncompress *.Z" followed by "mkfontdir .", and repeat the stuff with "xset fp+ ..." and "xset fp rehash". Also, it is possible that your xset(1) does not show error message, so make sure that all permissions are set correctly. Lastly, it is absolutely necessary for font directory to be accessible on the machine which is running the X server (i.e. this will not work with fontservers and such).

    One more thing, some system administrators do not allow users to install their fonts and disable or cripple the corresponding commands. This is another thing to check.

  3. How to setup KOI-8 fonts in Netscape 2.x/3.x Mail, News, Bookmarks, and Address Book windows

    If you followed the instructions for Netscape 2.x/3.x, you may have noticed that Netscape still uses its standard fonts for outline/subject lists in Mail, News, Bookmarks, and Address Book windows. To fix that, add the following lines to .Xresources/.Xdefaults file:

    Note that there should be no spaces after commas. Reload the resource file and restart Netscape. You should now be able to see Cyrillic in message/article subjects, bookmark window, etc. To test, try reading relcom.humor newsgroup.
  4. How to setup KOI-8 fonts in Netscape 2.x/3.x menus/dialogs/etc. (this is useful if you would like to see Cyrillic titles in Bookmarks/Go menus, etc.)

    To have Netscape use Cyrillic fonts virtually everywhere, add the following lines to the resource file:

    Netscape*fontList:                           -*-helvetica-bold-r-*-*-*-140-*-*-*-*-koi8-r
    Netscape*XmTextField.fontList:		     -*-courier-medium-r-*-*-*-140-*-*-*-*-koi8-r
    Netscape*XmText.fontList:                    -*-courier-medium-r-*-*-*-140-*-*-*-*-koi8-r
    Netscape*XmList*fontList:                    -*-courier-medium-r-*-*-*-140-*-*-*-*-koi8-r
    Netscape*menuBar*fontList:                   -*-helvetica-bold-r-*-*-*-120-*-*-*-*-koi8-r
    Netscape*menuBar*historyTruncated.fontList:  -*-helvetica-medium-o-*-*-*-120-*-*-*-*-koi8-r
    Netscape*popup*fontList:                     -*-helvetica-bold-r-*-*-*-120-*-*-*-*-koi8-r
    Netscape*topArea*fontList:                   -*-helvetica-bold-r-*-*-*-120-*-*-*-*-koi8-r
    Netscape*topArea*XmTextField.fontList:       -*-courier-medium-r-*-*-*-120-*-*-*-*-koi8-r
    Netscape*topArea*XmText.fontList:            -*-courier-medium-r-*-*-*-120-*-*-*-*-koi8-r
    Netscape*mouseDocumentation.fontList:        -*-helvetica-medium-r-*-*-*-120-*-*-*-*-koi8-r
    Netscape*docinfoButton.fontList:             -*-helvetica-medium-r-*-*-*-120-*-*-*-*-koi8-r
    Netscape*mailto*urlLabel.fontList:           -*-helvetica-medium-r-*-*-*-140-*-*-*-*-koi8-r
    Netscape*licenseDialog*text.fontList:        -*-courier-medium-r-*-*-*-120-*-*-*-*-koi8-r
    (Note that this already includes all changes needed to Cyrillify outline/subject lists in Netscape Mail, News, Bookmarks, and Address Book windows.) Reload the resource file and restart Netscape. You should now be able to see Cyrillic everywhere. To test, try visiting some homepage with Russian in the title.
  5. Why Netscape 2.x shows some Russian-language pages with Latin letters, and some with proper Cyrillic?

    Some sites specify the character set with every page they send you. When this happens to be the case, their settings override your settings in Options/Document Encoding menu. Some Russian-language sites (National News Service, for example) set koi8-r as the desired character set. (This can be verified by selecting View/Document Info from the menu.) Unfortunately, koi8-r is not one of the character sets built into Netscape 2.x, and so you cannot view these pages with 2.x version of Navigator. Fortunately, release 3.0 of Netscape Navigator (at least starting with 3.0b4) does support koi8-r character set and will display these pages correctly. You can follow the instructions above to set up Netscape 3.x.

  6. Why doesn't Netscape use KOI-8 in window titles?

    Window titles are controlled by a separate program called window manager and not by Netscape. To use Cyrillic fonts in window titles, refer to your window manager documentation.

  7. Why can't Netscape print KOI-8 documents?

    The PostScript font names are hardcoded inside Netscape, and hence there is no way to instruct Netscape to use Cyrillic fonts. To work around this limitation, save the document you wish to print using File/Save As... and follow the instructions for printing KOI-8 to PostScript printers.

  8. How to print KOI-8 to PostScript printers

    To print KOI-8 text to PostScript printer you will need a special program-converter. One such program, a2ps is available here as ftp://genome.lbl.gov/pub/maratb/a2ps.tar.gz (GNUzipped tar archive) and as ftp://genome.lbl.gov/pub/maratb/a2ps.tar.Z (Compressed tar archive). Unfortunately, to use this program you need to compile it first. If you don't know how to compile programs on your computer, get some local guru to help you. Also, be sure to read all three README files for instructions.

  9. How to input KOI-8 from keyboard

    First of all, if you are just editing some files and you are using Emacs 19.x, you should be able to get by without installing X Window keyboard mapping by using russian.el. See the section for Emacs 19.x for details.

    If you need to input Cyrillic into some terminal-based editor, or any other program, for that matter, you will need to obtain and install X Window keyboard mapping. Firstly, you have to decide what kind of character mapping you wish to use:

    You should also get the default.xmm which is a default keyboard mapping, just in case you screw up your keyboard and wish to restore the defaults.

    To install the keyboard mapping, copy the .xmm file to cronyx directory and type:

    % xmodmap ~/cronyx/<your-.xmm-file>
    That's it. You should now be able to switch your keyboard to Cyrillic mode with Caps Lock key. You may add the xmodmap(1) command to the startup file. If you need to restore default keyboard mapping, load default.xmm. Note, that keyboard mappings are applied incrementally, so you should always load the default mapping before attempting to reload the Cyrillic map.

Great places to visit with KOI-8

Further references


All of this document is the original work by
Marat Boshernitsan. However, to give credit where credit is due, I should mention the following sites and people that inspired, motivated, and suggested material for this document:


This document is provided "AS IS". Although the author of this guide attempts to make everything as accurate as possible, there still is the potential for mistakes and errors. If mistakes and errors are found by the reader(s), please report them to
MBoshernitsan@lbl.gov. The author will not be held liable for any consequences incurred by the user for using this guide.

This page is by: Marat Boshernitsan <MBoshernitsan@lbl.gov>

Last updated: June 12, 1996