  The Linux Cyrillic HOWTO
  Alexander L. Belikoff, (abel@wisdom.weizmann.ac.il)
  v1.0, 13 August 1995

  This document describes how to set up your Linux box to typeset, view
  and print the documents in Russian language.

  1.  Introduction


  This document covers the things you need to successfully typeset view
  and print documents in Russian.

  There is some conflict between MS-DOG and Un*x Cyrillic codesets. In
  MS-DOG, the most popular Cyrillic codeset is Alt (so-called
  alternative codeset). In Un*x, however, the traditional codeset with
  Russian characters is KOI-8. It is specified in the RFC 1489
  ("Registration of a Cyrillic Character Set").

  The difference in two codesets is usage is pretty minimal (except the
  TeX packages). Therefore, we will describe only KOI-8 codeset setup.

  Various people put a lot of effort to create useful packages and
  documents. These are listed through the text.

  I appreciate any comments corrections and suggestions concerning the
  document. Don't hesitate to contact me at abel@wisdom.weizmann.ac.il.



  2.  Further plans


  The next version of this document will be accessible on
  sunsite.unc.edu and tsx-11.mit.edu in HOWTO directory of the Linux
  Document Project.

  I am looking forward to include section on TeX and LaTeX and some
  issues on Internationalization and Localization.



  3.  Setting up the environment




  3.1.  Console


  All stuff needed for russification of the Linux console is contained
  in the kbd package. The package is accessible at sunsite.unc.edu or
  tsx-11.mit.edu. Usually, that package is already installed (it is a
  standard part of at least Slackware distribution).

  To setup the Cyrillic stuff, one should do three things:


  1. Set the appropriate screen font. This is performed by the setfont
     program. The fonts files are placed in /usr/lib/kbd/consolefonts.

     NOTE: Never run the setfont program under X or it will hang your
     system. This is because it works with low-level video card calls
     which X doesn't like.


  2. If you use the font in Alt coding (as I do) then you have to set up
     the screen mapping program to perform automatic conversion from Alt
     to KOI-8. For that purpose use the mapscrn program and the
     /usr/lib/kbd/consoletrans/koi2alt file.

  3. Load the appropriate keyboard layout with the loadkeys program.

  4. Output an ESC(K escape sequence on the screen (ESC stands for the
     Escape character with code 033). Only God knows the purpose of that
     combination. I stole it from the Danish-HOWTO
     <file://sunsite.unc.edu/pub/Linux/docs/HOWTO/Danish-HOWTO> (thanks,
     Thomas Petersen) and it works for me!

  The following is an example of a script which sets up the Cyrillic
  mode for console:


  #!/bin/bash
  #
  # load cyrillic defs for console
  #
  # *** NEVER TRY IT UNDER X!!! ***

  loadkeys /usr/lib/kbd/keytables/ru.map
  setfont /usr/lib/kbd/consolefonts/Cyr_a8x16
  mapscrn /usr/lib/kbd/consoletrans/koi2alt
  echo -ne 'ESC(K'        # use the REAL ESCAPE character here !
  echo "Use the right Ctrl key to switch the mode..."





  3.2.  The X Window System


  Like the console mode, the X environment also requires some setup.
  This involves setting up the input mode and the X fonts. Both are
  being discussed below.



  3.2.1.  The X fonts.


  First of all, you have to obtain the fonts collection having the
  Cyrillic glyphs at the appropriate places.

  There is a number of such fonts on the net. The author's favorite one
  is the collection VakuFonts created by Serge Vakulenko (vak@kiae.su).
  It can be found in the collection of cyrillic stuff for the X Window
  System <ftp://ftp.funet.fi/pub/culture/russian/comp/xwin> where you
  can find many useful packages for X.

  Usually the X fonts are distributed in the BDF format which is
  actually the textual font description. You should compile the fonts to
  the PCF format using the bdftopcf command:


       bdftopcf -o name.pcf name.bdf


  It is also possible to compress the compiled font using the compress
  program (I am not sure about the gzip support).


  Now you should do three things to set everything up:


  1. Put the compiled (and possibly compressed) fonts to the specified
     directory. If that directory is not already known to the X server,
     then you should make it known. To achieve that, add the following
     commands to the xinitrc file (either local or global one):


       xset +fp directory_with_fonts xset fp rehash



  2. Recreate the list of fonts for the directory. Simply cd to it and
     run:


       mkfontdir .



  You should run it once. This will upgrade the the fonts catalog file
  fonts.dir.

  3. If the fonts package provides the file of fonts' aliases (usually
     fonts.alias) then append it's contents to the fonts' aliases file
     in the directory containing the fonts.

  After you have made the settings above, you can check the availability
  of the new fonts by running the following command:


       xfd -fn fontname


  This should show the table of characters of the specified font.



  3.2.2.  The input translation


  The switching between the different input translations is set up by
  the xmodmap program. This program allows customization of codes
  emitted by various characters and their combinations. It sets the
  things up based on the file containing the translation table, usually
  named ~/.Xmodmap. If you want to create your own table, refer to the
  xmodmap(1). However such tables are generally supplied with the
  various X Cyrillic stuff packages. The good example is the tables in
  the perfect package by Serge Vakulenko described above.

  Once you have such file containing the table, you should run the
  command:


       xmodmap filename


  every time you start X. Modify your .xinitrc file to perform it. NOTE:
  your .xinitrc can already contain the code to run the xmodmap over
  your local table if the one exists.

  The table distributed with the Serge's Vakulenko package didn't work
  for the author. The following patch fixed the problem:


  diff -u --new-file jcuken.xmm jcuken.xmm.mod
  --- jcuken.xmm  Mon May 20 09:11:36 1991
  +++ jcuken.xmm.mod      Sun Aug 13 15:44:06 1995
  @@ -2,6 +2,8 @@
   ! Cyrillic keyboard mapping table.
   ! Produced by Serge Vakulenko, <vak@kiae.su>, Moscow.
   !
  +! Modified by Alexander L. Belikoff (abel@wisdom.weizmann.ac.il), 1995
  +!
   ! Russian JCUKENG keyboard layout implemented.
   ! Cyrillic characters are entered in koi8 encoding.
   !
  @@ -10,7 +12,9 @@

   ! Use CapsLock as rus/lat switch key.
   remove lock = Caps_Lock
  -add mod2 = Caps_Lock
  +keysym Caps_Lock = Mode_switch
  +add mod2 = Mode_switch
  +add lock = Mode_switch

   !       Key             Base            Shift           Caps    ShiftCaps
   !------------------------------------------------------------------------



  Now I can use the Caps Lock key to switch between normal and Cyrillic
  input modes.

  The author would appreciate the version of the table to support the
  different mode switch key, say Alt or Control.

  NOTE: The following is an excerpt from the list of new features
  announced in the XFree 3.1.2:


       Cyrillic fonts (using KIO8-R encoding) from Cronyx Ltd.


  Unfortunately the author hasn't had a chance to check it yet.



  4.  Miscellaneous utilities setup




  4.1.  bash


  Three variables should be set on order to make bash understand the
  8-bit characters. The best place is ~/.inputrc file. The following
  should be set:


  set meta-flag on
  set convert-meta off
  set output-meta on







  4.2.  csh/tcsh


  The following should be set in .cshrc:


  setenv LC_CTYPE ISO-8859-5
  stty pass8





  4.3.  remote access


  Use 'rlogin -8'



  4.4.  emacs


  The minimal cyrillic support in emacs is done by adding the following
  calls to one's .emacs (provided that the Cyrillic character set
  support is installed for console or X respectively):


  (standard-display-european t)

  (set-input-mode (car (current-input-mode))
     (nth 1 (current-input-mode))
     0)



  This allows the user to view and input documents in Russian.

  However, such mode is not of a big convenience because emacs doesn't
  recognize the usual keyboard commands while set in Cyrillic input
  mode. There is a number of packages which use the different approach.
  They don't rely on the input mode stuff established by the environment
  (either X or console. Instead, they allow the user to switch the input
  mode by the special emacs command and emacs itself is responsible for
  re-mapping the character set. There are, at least, two packages of
  that type. One is cyr.el. It can be found in most Emacs-Lisp archives.
  The other one is the package remap which tries to make such support
  more generic. This package is written by Per Abrahamsen
  (abraham@iesd.auc.dk) and is accessible at ftp.iesd.auc.dk.



  4.5.  less


  So far, less doesn't support the KOI-8 character set, but the
  following environment variable will do the job:


  LESSCHARSET=latin1






  4.6.  ispell


  Check the sunsite.unc.edu:/pub/academic/russian-studies/Software for
  the russian dictionary created by Neal Dalton (nrd@cray.com) for the
  ispell package.



  4.7.  Netscape


  Set the following resource:


  *documentFonts*registry:        koi8





  5.  Printing


  To print the text files containing the Russian characters using on
  PostScript printers, you need two things: the fonts and the 8bit-aware
  software able to print the texts using those fonts. The best package
  to print the text files in PostScript is a2ps by Evan Kirshenbaum
  (evan@csli) and Miguel Santana (miguel@imag.imag.fr). The last version
  is 8bit-aware. You can get it from imag.imag.fr:/archive/postscript/.

  Check the sunsite.unc.edu:/pub/academic/russian-studies/Software/ in
  order to obtain the Cyrillic PostScript fonts. Also, there is a lot of
  fonts in the SimTel <ftp://oak.oakland.edu/pub/SimTel/> collection.



  6.  Summary of the various useful resources


  The remap package for Emacs <ftp://ftp.iesd.auc.dk/>

  Many fonts collections for X
  <ftp://ftp.funet.fi/pub/culture/russian/comp/xwin>

  Useful Cyrillic packages <ftp://sunsite.unc.edu/pub/academic/russian-
  studies/Software>

  The kbd package for Linux
  <ftp://sunsite.unc.edu/pub/Linux/system/Keyboards/>

  X fonts collections <ftp://ftp.switch.ch/mirror/linux/X11/fonts/>

  rspell <ftp://sunsite.unc.edu/pub/academic/russian-
  studies/Software/rspell.tar.gz>
