\documentstyle[cyrillic]{report}
\addtolength{\oddsidemargin}{-.875in}
\addtolength{\evensidemargin}{-.875in}
\addtolength{\textwidth}{1.75in}
\setlength{\topmargin}{-.75in}
\setlength{\textheight}{8.75in}
\title{\begin{center}
\hspace*{1mm}\special{psfile=funky-owl.PS hoffset=-100}\hspace*{1mm}
\vspace{2cm}
\end{center}
\bf{Inessential Cyrillic}}

\author{Grisha Golberg ({\em grisha@mit.edu}) and Dima Dribinsky ({\em dimon@mit.edu})\\\\Student Information
Processing Board}
\date{September 3, 1996\\Revision 1.5}

\def\thesection {\arabic{section}}
\def\thesubsection {\thesection.\arabic{subsection}}
\def\thesubsubsection {\thesubsection .\arabic{subsubsection}}
\input cyracc.def
\font\tencyr=wncyr10
\font\sevencyr=wncyr7
\font\fivecyr=wncyr6
\font\tenboldcyr=wncyb10
\font\tenitcyr=wncyi10
\newfam\cyrfam
\textfont\cyrfam=\tencyr  \scriptfont\cyrfam=\sevencyr
\scriptscriptfont\cyrfam=\fivecyr
\def\cyr{\fam\cyrfam\tencyr\cyracc}
% Next two lines are new:
\def\cyrbold{\fam\cyrfam\tenboldcyr\cyracc}
\def\cyrit{\fam\cyrfam\tenitcyr\cyracc}

\begin{document}
\maketitle
\tableofcontents
\pagebreak
\begin{tabbing}
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\=aaaaaaaaa\=aaaaaaaaaaaa\kill
\>{\cyr Proniknoven\cprime e nashe po planete} \\
\>{\cyr Teper\cprime\ osobenno zametno vdaleke:}\\
\>{\cyr V obwestvennom parizhskom tualete }\\
\>{\cyr Est\cprime\ nadpisi na russkom yazyke.}\\
\>\>{\cyr Vladimir Vysotski\u\i}
\end{tabbing}
\section{Introduction: About Cyrillic and this document}
First, a bit of history. Cyrillic is the alphabet used by Russian and
various other Slavic languages. It was invented, if you care, by
St.Cyril (aka Constantine) and St.Methodius, Christian missionaries to
Slavs, in the 9th 
century A.D. Since they were Greek, the Cyrillic alphabet is based on
the Greek one, and you will find many common symbols in both alphabets.
The alphabet has been changing since then, until it arrived at the
present stage -- with several variations of it available for different
Slavic languages. Since the variations are slight, we will mostly speak
of Russian alphabet, as it is the most commonly used. 
\par
This document will explain how to generate documents in Cyrillic with
\LaTeX, how to read and write Cyrillic in your X applications and how to
convert among various formats of representation of Cyrillic characters.
To more fully understand this document, we recomment you familiarize
yourself with {\em Inessential \LaTeX} and {\em Inessential X Resources}
documents, available from SIPB office (W20-557).
\par 
Obviously, this document is concerned with making Cyrillic available in
the {\em Athena} environment. If you have any questions as to how make
Cyrillic available on your home computer for MS-DOS, Windows, Mac, or
whatever, you are welcome to ask the authors. If you want to know about
the availability of tools for other foreign languages on Athena, wait a
little --- there may be an {\em Inessential Foreign Languages} document
coming soon from the friendly folks in SIPB. Also, please explore the
resources listed in the section on where to get more information later
in this manual. 
\par
This is Revision 1.5 of {\em Inessential Cyrillic}, which contains
several {\bf major}
changes and additions from the previous release. Some useful utilities
which have recently been installed in the {\bf russian-club} and {\bf cyrillic}
lockers, are described here. 
If you have read this document before, read it again to make sure your
new customizations for Cyrillic  are according to this document, not the
previous versions. 
\section{Producing Cyrillic documents with \LaTeX}\label{sec:latex}
\subsection{Introduction}
This section describes how to typeset a document in Cyrillic using
\LaTeX. We assume you already know how to use \LaTeX{} to typeset simple
documents. If not, do read {\em Inessential \LaTeX}.\\
\par
The Cyrillic font for \LaTeX, developed by the American Mathematical
Society, ``contains all letters found in the modern
(post-revolutionary) Cyrillic alphabet, as well as others found by
Mathematical Reviews to be necessary for rendering bibliographic
information in Russian, Ukrainian, Serbian, Georgian, and other Slavic and
non-Slavic languages ordinarily published in Cyrillic.''\footnote{ {\em
Mathematical Symbols and Cyrillic Fonts Ready for Distribution}, Barbara
Beaton, American Mathematical Society.} \\
\subsection{How to start} 
To begin with, you should tell \LaTeX{} where to look for for Cyrillic
fonts. To do that, enter
\begin{verbatim}
attach sipb
setenv TEXINPUTS .:/mit/sipb/lib/tex/macros//:
\end{verbatim}
at your {\tt athena\%} prompt (note the trailing colon!). These lines
can also be placed in your {\tt .environment} file.
\par
Now you can start writing your Cyrillic document. Before you use any
Cyrillic font, however, you should put the following in your {\tt .tex}
file:
{\tt Cyrillic} in the options section of the {\tt $\backslash$documentstyle} line,
e.g.\\
{\tt $\backslash$documentstyle[Cyrillic]\{article\}}\\
and in the preamble -- after the {\tt $\backslash$documentstyle} line and before
{\tt $\backslash$begin\{document\}}, -- put 
\begin{verbatim}
\input cyracc.def
\font\tencyr=wncyr10
\font\sevencyr=wncyr7
\font\fivecyr=wncyr6
\font\tenboldcyr=wncyb10
\font\tenitcyr=wncyi10
\newfam\cyrfam
\textfont\cyrfam=\tencyr  \scriptfont\cyrfam=\sevencyr
\scriptscriptfont\cyrfam=\fivecyr
\def\cyr{\fam\cyrfam\tencyr\cyracc}
\def\cyrbold{\fam\cyrfam\tenboldcyr\cyracc}
\def\cyrit{\fam\cyrfam\tenitcyr\cyracc}
\end{verbatim}
You are all set. Now you can enter Cyrillic like this: {\tt
\{$\backslash$cyr {\em text}\}}, where {\em text} is the AMS \LaTeX{}
representation of Cyrillic characters. You can typeset Cyrillic in {\bf
bold} and {\it italic} by substituting $\backslash$cyrbold and
$\backslash$cyrit for $\backslash$cyr respectively. For example, use the
following 
\begin{verbatim}
{\cyrbold \`Eto zhirny\u{i} shrift}
{\cyrit A \'eto kursiv}
\end{verbatim}
To produce \\
\par \noindent
{\cyrbold \`Eto zhirny\u{i} shrift}\\
{\cyrit A \`eto kursiv}\\
\subsection{Representation of Cyrillic characters}
The representation is mostly phonetic, somewhat similar to the generally
accepted Library of Congress transliteration standard. See Appendix A
for the table of Russian alphabet in Cyrillic and in corresponfing
\LaTeX{} symbols. Here are some examples. This:  \\

\noindent {\cyr 
Ne migayut, slezyat\null sya ot vetra \\
Beznad\"ezhnye karie vishni. \\
Vozvrawat\cprime sya plohaya primeta -- \\
Ya tebya nikogda ne uvizhu.} 
\\
\\
\noindent was created from the following source:
\begin{verbatim}
{\cyr Ne migayut, slezyat\null sya ot vetra \\
Beznad\"ezhnye karie vishni.\\
Vozvrashchat\cprime sya plohaya primeta -- \\
Ya tebya nikogda ne uvizhu.} 
\end{verbatim}
and this\\

\noindent {\cyr Zdes\cprime\ lapy u ele\u\i\ drozhat na vesu, \\
Zdes\cprime\ pticy webequt trevozhno. \\
Zhivex\cprime\ v zakoldovannom dikom lesu, \\
Otkuda u\u\i ti nevozmozhno. \\
Pust\cprime\ qeremuhi sohnut bel\cprime \"em na vetru, \\
Pust\cprime\ dozhd\"em opadayut sireni, \\
Vs\"e ravno ya ot\null syuda tebya zaberu \\
Vo dvorec, gde igrayut svireli.}
\\
\\
\noindent was created from the following source:
\begin{verbatim}
{\cyr Zdes\cprime\ lapy u ele\u\i\ drozhat na vesu, \\
Zdes\cprime\ pticy webequt trevozhno. \\
Zhivex\cprime\ v zakoldovannom dikom lesu, \\
Otkuda u\u\i ti nevozmozhno. \\
Pust\cprime\ qeremuhi sohnut bel\cprime \"em na vetru, \\
Pust\cprime\ dozhd\"em opadayut sireni, \\
Vs\"e ravno ya otsyuda tebya zaberu \\
Vo dvorec, gde igrayut svireli.}
\end{verbatim}
\noindent This should be enough to let you insert Cyrillic text
into your documents.
\section{Displaying Cyrillic in X applications}
\subsection{Introduction}
There are several ways of representing Cyrillic letters. There are
schemes to code not only Russian letters but some other Slavic ones:
Ukranian, Serbocroatian, Macedonian. Those tables are slightly different
one from another but the basic rule is the same: all Cyrillic letters
are located beyond 127th number of ASCII which is a 7 bit table. That
means that in all of these coding schemes (like KOI-8) cyrillic letters
take place of the characters like \"u, \'o, etc. The
most common scheme is probably KOI-8 (for {\cyr Kody Obmena
Informacie\u\i}, the 8-bit Codes for Information Interchange). Another
scheme, common for PC's, is ALT (for ``alternative''). But since KOI-8
is by far the most 
widely used, they are the ones installed in {\bf cyrillic} locker on
Athena, and they are the ones we are going to talk about. 
\subsection{Installing fonts for your X session}
\label{sec:startupx}
All public cluster machines can be ``russified''. It is important to
note for those who want to russify their private machine, that the fonts
will only work on machines with X11R4 and later versions of X 
server. If you are not russifying an Athena platform, you can find out
which revision you are running by entering command 
\begin{verbatim}
xdpyinfo 
\end{verbatim}
and looking for ``vendor release number'' (it should be close to the
beginning of the output). It should be 4 or greater for
the fonts to work properly. If you are on Athena, don't worry --- the
fonts will work properly on all Athena platforms.
\par
To install KOI-8 fonts for the current X session, execute the following
commands:
\begin{verbatim}
xset fp default
xset fp+ /afs/sipb.mit.edu/project/sipb/lib/X11fonts/@sys/
xset fp+ /afs/athena.mit.edu/course/other/cyrillic/Fonts
xset fp rehash
\end{verbatim}
You can make these changes go into effect every time you start your X
session. To do that, put the above four {\tt xset} commands in your {\tt
.startup.X} (if you don't have a {\tt .startup.X} file in your home
directory, create it). 
\subsection{Making it work for SGI}
For a Silicon Graphics workstation, there is one more thing you need to
do to enjoy Cyrillic on Athena. You need to create  a {\tt .startup.sgi}
file with the above {\tt xset} commands.
\label{sec:sgi}
\subsection{Configuring X resources}
Now that you have installed the fonts, you still need to configure your
applications' X resources to display those fonts. Aside from the 
special cases, each of which is explained in its own subsection below, 
very easy to do if you are
familiar with setting X resources\footnote{ {\em 
Inessential X Resources} is a helpful document available from SIPB}. For
the information on these special cases, read the respective subsections
below.  The list of KOI-8 fonts available is provided in Appendix C. 
\par 
If, however, you just want to quickly do what you have to do without
going into details, here is an example of what the authors have in their
{\tt .Xresources} files to enable an X application to display KOI-8 --- in our
example, it's {\tt xrn} or {\tt xemacs}, so that you can read all these
relcom newsgroups: 
\begin{verbatim}
xrn*font:		-cronyx-fixed-medium-r-semicondensed--13-120-75-75-c-60-koi8-r
xemacs*font:		-cronyx-fixed-medium-r-semicondensed--13-120-75-75-c-60-koi8-r
\end{verbatim}
These are only the resources we {\em recommend}, because we
like them. If you want other fonts, look at the list of them in the
Appendix C and experiment.
\par
Finally, for the changes in X resources to take effect in the same X
session you changed them, you must run command
\begin{verbatim}
xrdb ~/.Xresources
\end{verbatim}
and restart the affected application.
\par
And one more point: Zephyr. While Zephyrgrams are also X windows during
your X session, there are issues with russifying Zephyr that have
nothing to do with X resources; so for instructions, see below in
Section \ref{sec:zephyr}. Let us now move on to special cases.
\subsection{Special case 1: Netscape}{\label{sec:mozilla}}
Everyone's least or most favorite Web browser is russified as
follows. Start the browser, pull down the {\tt Options} menu, go to {\tt
Document Encoding} submenu, and select {\tt Cyrillic (KOI8-R)}
option. Then go to {\tt Options} menu once again, and select {\tt Save
Options}. You are all set. 

\subsection{Special case 2: Mosaic}\label{sec:mosaic}
The version of Mosaic available on Athena in the {\bf sipb} locker is
multilingual. It supports a lot of fonts for various languages -- look
in Options-Fonts menu to see for yourself. You don't need to load X
fonts for this multilingual Mosaic -- just tell it which font to use. In
our case, go to the Fonts submenu from Options menu in Mosaic window,
and select {\tt  Cyrillic (KOI8)} (NOT {\tt  Cyrillic (ISO
8859-5)}, which is very rarely used). You are all set. You won't even
need to reload the current document to see it properly with the new font
-- Mosaic will do the right thing automagically. 
\par
To make Mosaic automatically load KOI8 font every time you run it, put
the following line into your {\tt .Xresources}:\\
{\tt Mosaic*defaultCharset:	koi}
\subsection{Cyrillic on the Web}\label{sec:www}
Now that you can display Cyrillic in Mosaic and/or Netscape, here are
some sites for you to check out:
\begin{verbatim}
http://www.mit.edu:8001/activities/russian-club/catalog.html
\end{verbatim}
This is a collection of lyrics to some 2,500 Russian songs, many of them
with guitar chords. It's an effort of {\em SovInformBuro} at MIT Russian
Club, of which the two authors of this document are members. You can
reach us at {\em SovInformBuro@MIT.EDU}. 
\par
The following two sites are the repository of a wealth of information
of interest to you.
\begin{verbatim}
http://solar.rtd.utk.edu/friends/home.html
http://sunsite.oit.unc.edu/sergei/Grandsons.html
http://www.pitt.edu/~cjp/rees.html
http://www.mit.edu:8001/activities/russian-club/russian-club.html
\end{verbatim}
has pointers to many other sites of interest to Cyrillic readers on the
Web. 
\subsection{Special case 3: XTerm}
Once again, in XTerm, that notorious 8th bit is stripped away. So even
if you set the XTerm X resource ({\tt xterm*font}) to a correct font,
you will not be able 
to see Cyrillic in the window. To correct that you have to force XTerm
to allow 8th bit to go through. For that, enter {\tt stty cs8 -istrip}
in your XTerm window.
That'll allow the 8th bit to pass through, but {\bf only in that
window}. To automate this process for every window, put the following
commands in your {\tt .cshrc.mine} file:
\begin{verbatim}
stty cs8 -istrip
\end{verbatim}
\subsection{Special case 4: Emacs} Setting X resources for Emacs would not do
any good. Emacs will still display the Cyrillic characters' octal
encoding instead of the characters themselves. There is an answer: {\tt
xemacs}. You have already seen how to enable it to display Cyrillic
fonts ({\tt xemacs*font:koi6x13} in your {\tt .Xresources} file will do
the trick).  But, then, can we edit Cyrillic text? Well, that brings us
right to the next section. 
\section{Typing real Cyrillic}
\subsection{Installing Cyrillic keyboard map}
In order to be able to type Cyrillic in some of the applications you use
--- for example, to post to USENET with {\tt xrn} --- you need to install
a Cyrillic keyboard table for KOI-8 codes. To install it, enter\\
\par
\noindent{\tt attach russian-club}\\
{\tt xmodmap /mit/russian-club/Fonts/Keymaps/}{\em keymap}\\
\par
\noindent where the {\em keymap} is one of the two keyboard layouts
available in the {\bf russian-club} locker for typing KOI-8: {\tt
yawerty.koi8.xmm} and {\tt jcuken.koi8.xmm}. The {\tt jcuken.koi8.xmm}
models the layout of a real Russian keyboard -- named for the first 6
letters on that keyboard, {\cyr \u{I}CUKEN}. It is helpful if you are
comfortable with that layout. If you aren't, we recommend the {\tt
yawerty.koi8.xmm} ({\cyr YaVERTY}) layout, where Cyrillic letters will
be placed on keys of similar latin letters. See Appendix B for the
table containing summary of all three (QWERTY, {\cyr \u{I}CUKEN} and
{\cyr YaVERTY}) keyboard layouts.
\par
To switch between Latin and Cyrillic, hit {\tt Caps Lock} key. To
uninstall the Cyrillic mapping, enter
\begin{verbatim}
xmodmap /mit/russian-club/Fonts/Keymaps/default.xmm
\end{verbatim}
\subsection{XEmacs}\label{sec:xemacs}
This is all good if you don't really want to directly {\em edit}
Cyrillic text. One way, of course, is to write a \LaTeX{} document (or a
document in some other phonetic transliteration of Cyrillic) and then
edit it and convert it to whatever other format you want -- like KOI-8,
for example\footnote{See the next Chapter for explanation of how to
convert among various representations of Cyrillic}. But what if you want
sort of a WYSIWYG, what if you want to see the Cyrillic letters as you
are typing them, and you want to use a familiar editor -- Emacs? Setting
X resources for Emacs fonts to KOI-8 fonts will not work, as we said above.
There is a way to use Emacs to edit and convert between some of the
representations (see next section), but that may not really be what you 
want. But does that mean there is no solution to this problem?
\par
Nope, in fact there are {\em two} solutions. One is {\tt xemacs} which
we have already mentioned before. All you need to edit Cyrillic text
with it you have already done: you have set proper X resources for it,
and specified a keyboard layout to use. Just start it --- xemacs is in its
own locker, and to start it you need to enter
\begin{verbatim}
add xemacs
xemacs&
\end{verbatim}
--- and you are ready to go! 
\subsection{Mule}
Another editor suitable for this purpose is {\tt mule} -- a
MUltiLanguage Emacs, available on 
Athena which can be used for Cyrillic input. To use it, enter the
following commands:
\begin{verbatim}
setup babel
mule -l quail-Cyrillic &
\end{verbatim}
This will bring up a {\tt mule} window, which is just like Emacs.  The file
``quail-Cyrillic'' loads several different keyboard layouts that you can
use.  By default, what you type will be in English.  To switch to and
from quail input mode, type {\tt C-]} The default keyboard layout is
{\cyr YaVERTY}. The mode line should indicate the layout currently in use.  
To change the layout, from the quail input mode type {\tt M-s}, and 
it will prompt you for a different layout.  {\tt TAB} at this prompt
will get you a list of the available layouts. The layouts currently
available are Byelorussian, {\cyr \u{I}CUKEN}, Macedonian, Ukrainian,
Serbian and {\cyr YaVERTY}.
\par
When you save your file, {\tt mule} saves it in its own format. It is
possible to convert it to KOI-8 format (see next Chapter). If you want
a hardcopy of what you typed, you can convert it to KOI-8, from KOI-8 to
\LaTeX{}, and then \LaTeX{} it and print out. This conversion process
will generate hardcopy of better quality than the easier method that is
recommended for use with {\tt mule}, but if you do want worse quality
and faster method -- without going through all the conversions -- here
it is.
\par
First, you must save your Russian buffer in {\tt mule} internal encoding.
To do that, enter
\begin{verbatim}
M-x set-file-coding-system
\end{verbatim}
in {\tt mule}. At the {\tt File-coding-system:} prompt enter {\tt
*internal*}. Now that you saved the file, you can print it out using {\tt
m2ps} command in the {\bf babel} locker. The general format of the command is \\
\smallskip
{\tt m2ps < }{\em infile }{\tt > }{\em outfile}\\
\smallskip
for saving it in the PostScript format, or \\
\smallskip
{\tt m2ps < }{\em infile}{\tt | lpr -P}{\em printer} \\
\smallskip
to get a hardcopy.
\section{Convert!}
Ok. Now that you have learned many ways of getting the
Cyrillic, you might want to convert them from one to another. And there
are now two ways to do that.
\subsection{Translit}\label{sec:translit}
You can use a program, called {\tt translit}. To use it, 
you have to {\tt add russian-club}. With {\tt translit} you can convert 
between \LaTeX{}, phonetic, mule, KOI-8, KOI-7, ALT, Library of Congress
and other encodings.  To convert a file just type the following command:\\
\noindent {\tt translit -i }{\em infile }{\tt -o }{\em outfile table}\\
where {\em infile} is the name of the ``source'' file you want to
convert, and {\em outfile} is the name of the ``target'' file, where
you want to place the converted ``source''.
If input or output files are not specified,
the program uses standard input or standard output. The {\em table}
is the full path of the conversion table file to be used. The tables
are located in /mit/russian-club/lib/tables; see table below for correct
usage\footnote{Note that the {\tt tables} directory has been moved into
the {\tt lib} directory, and that the files containing tables no longer
have {\tt .rus} extension -- saves you typing, you know...}. 
If you are going
to use the program a lot, it might be very useful to set the default
path and default table. To do that in  you can just add the
following lines to your {\tt .environment} file:\\
{\tt setenv TRANSP /mit/russian-club/lib/tables/}\\
{\tt setenv TRANSF }{\em most-used-table}\\
The following translaton tables are available\footnote{The most
useful tables are boldfaced}:\\

\smallskip

\begin{tabular}{ll}
alt-gos & ALT to GOSTCII table\\
alt-koi8 &        ALT to KOI-8 table\\
gos-alt   &       GOSTCII to ALT table\\
gos-koi8   &      GOSTCII to KOI-8 table\\       
koi7-8   &        KOI-7 to KOI-8 table\\
koi7nl-8 &        KOI-7 (no Latin) to KOI-8 table\\
koi8-7   &        KOI-8 to KOI-7 table\\
koi8-alt &        KOI-8 to ALT table\\
koi8-gos &        KOI-8 to GOSTCII table\\
{\bf koi8-lc} &   KOI-8 to Library of Congress table\\
{\bf koi8-mule}&  KOI-8 to Mule format\\
koi8-phg  &       KOI-8 to GOST transliteration\\
koi8-php  &       KOI-8 to Pokrovsky transliteration\\
koi8-tex  &       KOI-8 to LaTeX \\
{\bf mule-koi8} & Mule to KOI-8 \\
phg-koi8  &       GOST transliteration to KOI-8\\
pho-8sim  &       Simple phonetic to KOI-8\\
pho-koi8  &       Various phonetic to KOI-8\\
php-koi8  &       Pokrovsky to KOI-8\\
tex-koi8  &       \LaTeX{} to KOI-8\\
tex-mule  &       \LaTeX{} to Mule\\

\end{tabular}
\par
If you have any problems using this program or you find some
bugs in the tables, you are encouraged to mail them to {\em
SovInformBuro@mit.edu}.
\subsection{Converting with Emacs: it's interactive!}
You can also edit and convert files with Emacs 19 (default Emacs now on
Athena). First of all, you'll need to put the following in
your {\tt .emacs} file: 
\begin{verbatim}  
(setq load-path (append load-path
                          '("/afs/athena/activity/r/russian-club/src/El")))
(require 'russian "/afs/athena/activity/r/russian-club/src/El/russian")
\end{verbatim}
That will enable you to dispay files in arbitrary encodings, translating
contents of Emacs buffer(s) between encodings without changing the
actual file, or saving the changed buffer and thereby changing the file
on disk. One advantage of that over {\tt translit} is that you are able
to edit, convert back and forth, and edit the file again in one
application. The encodings available are:\\
\par
\begin{tabular}{ll}
8koi&     KOI-8 RFC 1489 = old KOI-8 GOST 19768-74 with {\cyr \"e} and {\cyr \"E} \\
    &     CAPITAL IO added, used in relcom.* newsgroups and much of e-mail\\
7koi&     KOI-7 \\
alt &     {\cyr Al{\cprime}ternativny\u{i} Variant} = MS DOS code page CP 866\\
gostcii&  ISO 8859-5\\
osn   &   {\cyr Osnovno\u{i} Variant} (the only difference in the Cyrillic\\
      &    range between this standard and GOSTCII is {\cyr \"E})\\
cp1251 &  MS Windows code page CP 1251\\
mac    &  Macintosh standard\\
dkoi   &  DKOI-8 (Russian EBCDIC) GOST 19768-87, obscure\\
cp500  &  Code page CECP 500, obscure\\
ebcdic &  EBCDIC GOST 19768-74, obscure\\
ascii  &  American keyboard, phonetic transliteration,
         probably, the most natural keyboard layout\\
jcuken &  Russian typewriter keyboard layout, used in some TrueType
         fonts for MS Windows\\
libcon &  Library of Congress transliteration standard\\
%\end{tabular}
%\newpage
%\begin{tabular}{ll}
naive  &  The most common transliteration\\
broken-8koi&  This is what some mailers/gateways do to your email
              to/from Russia\\
ascii2  & One more transliteration, without {\cyr \"e, \"E, \Cdprime}\\
\end{tabular}\\
\par
So how do you actually use it? {\tt M-x russian-display} sets the
standard display table so that you can see russian characters encoded
according to various standards. The actual file or a buffer won't
change, only the way of presenting it. Using {\tt M-x
russian-translate-region} and {\tt M-x russian-translate-buffer} --
which will prompt you for the current encoding and the target encoding
-- you can translate the contents of the buffer into various encodings.
\par
You can even conveniently edit the buffer. {\tt M-x
russian-insert-mode} will toggle a mode which, when it's on, will cause
emacs to translate characters you type in into corresponding sequence in
the default encoding. For example, typing {\tt a} will result in the display
of {\tt $\backslash$\null 301} if KOI-8 is the current encoding.
\par
\noindent Other functions available are:\\
\par
\begin{tabular}{ll}
{\tt M-x russian-undisplay}& Turns russian display mode off \\
{\tt M-x set-buffer}& Set new encoding of the buffer \\
{\tt M-x set-keyboard}& Set new keyboard (ascii and jcuken are
available) \\
{\tt M-x set-mode}& Set insertion mode \\
{\tt M-x set-font}& Set font or transliteration\\
\end{tabular} \\
\par
\noindent We suggest you experiment with these functions to really learn what they
mean and how you can put them to use.
\subsection{Getting a hard copy}\label{sec:a2ps}
Now, if you have already gotten a Cyrillic document that you want to
print, what do you do? Sure, you can {\tt translit} it into \LaTeX{},
and then \LaTeX{} it and print it; but there's an easier way to print
out files in KOI-8, the most common format (if you have a file in
another format, you can always just {\tt translit} it into KOI-8) -- the
program is {\tt a2ps} in the {\tt russian-club} locker. This
is not a supplement for \LaTeX{} or {\tt mule}, rather a complement.
\LaTeX{} is very good to typeset complex documents with Cyrillic in it,
{\tt mule} is fine to type simple Cyrillic documents, and {\tt a2ps},
is just what you need to quickly get a hard copy of an already existing
Cyrillic document. 
\par
The command {\tt a2ps} converts the KOI-8 file into PostScript, the
language that Athena laser printers understand; the PostScript can then
be fed to the printer to produce the desired hard copy, so a command to
print a KOI-8 file will look like this:\\
{\tt a2ps [{\em options}] {\em filename} | lpr -P{\em printer}}\\
This utility has many features (such as printing in landscape mode,
numbering lines, framing the output, etc.) that can be enabled by a number of
options; read the man page to figure out which ones suit you most. The
following two combination of options are the most useful; the first
prints the KOI-8 files in portrait mode without any extra features or
information (just like {\tt lpr} for plain text files), and the second
one prints two pages on one, in landscape mode. Here they are:
\begin{verbatim}
a2ps -8 -b -f -p -ns -nh -nn
a2ps -8 -b -f -np -ns -nn -nh
\end{verbatim}
Note that {\tt -8} option will be necessary always to keep that famous
8th bit intact.
\section{Communicating with other users}
\subsection{Zephyr}\label{sec:zephyr}
There are two parts to communicating in Cyrillic via Zephyr: sending and
receiving. To be able to successfully receive Zephyrgrams on your X
display, you only need to have Cyrillic X fonts in your path, which is
achieved by either issuing the three {\tt xset} commands mentioned above
at your {\tt athena\%} prompt, or putting them in {\tt .Xresources}
file.
\par
\paragraph{Displaying transliteration} You will not be able to receive
Cyrillic while on dialup, but there is a 
way to make the Cyrillic Zephyrgrams appear in transliteration (rather
than garbage) when you are not on an X display, or when some (poorly
written, no doubt) X
application you are running complains about fonts {\em and exits}. You will
need to edit 
your {\tt .zwgc.desc}\footnote{If you don't have a {\tt
.zwgc.desc} in your home directory, you may get the default Athena one
by {\tt cp}'ing it from 
{\tt /usr/athena/lib/zephyr/zwgc.desc}; or you can copy the default
Athena file with customizations for Cyrillic already made from {\tt /mit/russian-club/src/zwgc/zwgc.desc.default}} file; it is the file which tells
Zephyr how you want Zephyrgrams to look on your screen\footnote{For more
information, check out {\em Inessential Zephyr} from SIPB}. The code
below is also available by itself, within a default {\tt .zwgc.desc}
file, and within an example of a customized file -- one of the authors'
personal -- in {\tt /mit/russian-club/src/zwgc}. 
\par
In the beginning of the file, insert
\begin{verbatim}
set xsession = getenv ("XSESSION")
set machtype = getenv ("HOSTTYPE")
execport "transp" "sh" "-c" "ls /tmp | grep dotrans" 
set translitp = (get ("transp") != "")
closeport "transp"
\end{verbatim}
Then go to the place in the file where the format of a generic
Zephyrgram is specified. For most users, the place is right after the
line {\tt fields signature body}, and you should have no trouble finding
that in your {\tt .zwgc.desc}; if your {\tt .zwgc.desc} is hacked beyond
recognition, we think that you have enough expertise to decide where to
put the following code.
\begin{verbatim}
if (upcase($opcode) == "AHOOY" & ($xsession=="" | $translitp)) then
    execport "transport" "/afs/athena.mit.edu/activity/r/russian-club/"+\$machtype+"bin/translit" 
"/afs/athena.mit.edu/activity/r/russian-club/lib/tables/koi8-lc" 
    put "transport" $body
    closeoutput "transport"
    set body=""
    set stroka=get ("transport")
    while ($stroka!="") do
        set body = $body+$stroka
        set stroka=get ("transport")
    endwhile
    closeport "transport"
    # Comment out next portion if you don't want to waste
    # extra time on processing sigs
    execport "transport" "/afs/athena.mit.edu/activity/r/russian-club/"+\$machtype+"bin/translit" 
"/afs/athena.mit.edu/activity/r/russian-club/lib/tables/koi8-lc" 
    put "transport" $signature
    closeoutput "transport"
    set signature=""
    set stroka=get ("transport")
    while ($stroka!="") do
        set signature = $signature+$stroka
        set stroka=get ("transport")
    endwhile
    closeport "transport"
    # If you are commenting code out, stop here	
endif
\end{verbatim}
That's it. Save your file; and do {\tt zctl wg\_read} to effect the
changes during your current session. The additions we just made work as
follows. If you run a teletype-style session (for example, on dialup),
the zephyrgrams coming in Cyrillic will automagically be displayed in
appropriate transliteration. If you are on an X display, you may toggle
between displaying transliteration and Cyrillic by respectively creating
and removing file {\tt /tmp/dotrans} on your local workstation. When you log
in, there is no such file by default, and you get Cyrillic Zephyrgrams.
If you create the file -- very easily done by doing {\tt touch
/tmp/dotrans} -- subsequently incoming Cyrillic Zephyrgrams will be
displayed  in transliteration, until you again remove the file. You can
just set up two aliases (and put them into your {\tt .cshrc.mine} for
such toggling between displays, for example as follows: 
\begin{verbatim}
alias trans "touch /tmp/dotrans"
alias cyr "rm /tmp/dotrans"
\end{verbatim}
\paragraph{Sending}
Sending is very easy. Just {\tt add russian-club} (put this command in
your {\tt .environment} to automate the process for each login). You are
now able to use a command called {\tt cwrite}. It takes mostly the same
arguments as {\tt zwrite}, so it should be very easy to use (type {\tt
cwrite} without arguments at your command prompt to see the options it
takes). For your convenience, you input the transliteration of Cyrillic
letters and words, and the {\tt cwrite} takes care of converting them to
appropriate fonts. To force it to send something not converted -- that
is, to insert Latin text in a Cyrillic message -- include Latin text in
braces when inputing it into {\tt cwrite}. 
\subsection{E-mail}
So you say it would be nice to communicate in Cyrillic via e-mail?
Indeed, it would be, but there are some obstacles. KOI-8 is the de facto
standard for e-mail in Russia, and when
KOI-8 passes into the mostly 7-bit Western e-mail system the 8-th bit is
(usually) stripped leaving the Russian text in KOI-7, as Western
networks do not (again, {\em usually}) support 8th bit. That may be
annoying, but is not really a barrier, as you have {\tt translit}
program that can handle KOI-8--KOI-7 conversion.
\par
But do you want to go through the hassle of this conversion when sending
e-mail? It is true that for your correspondents in the countries with
Cyrillic alphabet it may be easier to write that way. However, for you
we suggest two approaches: if you are writing to your correspondent in
.su (or .ru, or .ua, or another Eastern Europe) domain, convert your file to
KOI-7 and send it. Of course, this method is not entirely suitable for
documents that have both Cyrillic and Latin characters. For those
documents an option is to use another reversible 8-7 bit encoding (such
as the good old {\tt uuencode}). However, if the person you are writing
to is to the 7 bit side of the ``7 vs. 8 bit barrier'', we suggest the
Library of Congress transliteration method as it is more easily read in
e-mail.

\section{Where to seek and find (and not to yield) more information}
SIPB documents can be very helpful for learning \LaTeX{} or about X
resources. As we mentioned before, there will be a new document, {\em
Inessential Foreign Languages}, coming soon to the SIPB document racks. 
To learn how to install Cyrillic fonts on your system, 
read the documentation in /mit/russian-club/doc. For more information
about Cyrillic fonts for X, try this URL: {\tt
http://sunsite.oit.unc.edu/sergei/cysoft.html}. There are also man pages
available for most of the programs described here, and additional
information can be found in /mit/russian-club/doc directory.
\par
Various software (fonts, editors, word-processing programs, etc.) for
various platforms (VAX, MS-DOS, MS Windows, Mac, various VT terminals
etc.) and documentation is available from the following sites: 
\begin{verbatim}
gopher://sunsite.oit.unc.edu/11/.pub/academic/russian-studies/Software
ftp://ftp.cs.umd.edu/pub/Cyrillic
http://www.pitt.edu/~cjp/rssoft.html
\end{verbatim}
\par
You can also come by the SIPB office (W20-557) or call us (253-7788). 
You can also e-mail your comments, bug reports and questions on
the use of Cyrillic on Athena to {\em SovInformBuro@MIT.EDU}. As a lot
of stuff described in this manual was only recently installed on Athena
and not sufficiently tested, we welcome your bug reports. 
\par
In addition, visit the sites recommended in Section \ref{sec:www}.
\section{Acknowledgments}
We would like to thank Roustem Akhiarov, Sergey Ryzhkov, Lev Belov, 
Serge Vakulenko ({\em vak@kiae.su}) and Vadim Maslov ({\em
vadik@cs.umd.edu}), for designing and developing
KOI-8 and ALT fonts for X Window System; Jan Labanowski ({\em jkl@osc.edu}),
for writing {\tt translit}; Miguel Santana ({\em miguel@imag.imag.fr})
for writing {\tt a2ps}; Valery Alexeev ({\em ava@math.jhu.edu}) for
writing the conversion utility for Emacs 19, and the people at the
American Mathematical Society who created the Cyrillic fonts for
\LaTeX{}. Thanks are due also to Mike Decerbo ({\em mike@mit.edu}) for
designing some useful conversion tables for {\tt translit} and some
valuable input that was incorporated in this document, to Calvin
Clark ({\em ckclark@mit.edu}) for providing info on {\tt mule} and maintaining
the {\bf babel} locker, and to Boris Berdnikov ({\em berdn@mit.edu}) who
convinced us of ther need for the new release of the document, and
proofread this new release. We are also thankful to the {\tt relcom.*}
community for random but valuable pieces of information. 
\par
This manual has been brought to you by the number 37.
\appendix
\chapter{Cyrillic alphabet}
\begin{center}
\begin{tabular}{||c|c||}\hline
Cyrillic  & \LaTeX{} (inside {\tt \{$\backslash$cyr \}})    \\ \hline
{\cyr A a}& A a \\
{\cyr B b}& B b \\
{\cyr V v}& V v \\
{\cyr G g}& G G\\
{\cyr D d}& D d\\
{\cyr E e}& E e\\
{\cyr \"E \"e}& $\backslash$"E $\backslash$"e \\
{\cyr Zh zh}& Zh zh\\
{\cyr Z z}& Z z\\
{\cyr I i}& I i\\
{\cyr \u{I} \u{i}}& $\backslash$u\{I\} $\backslash$u\{i\}\\
&(or $\backslash$u\{I\} $\backslash$u$\backslash$i) \\
{\cyr K k}& K k\\
{\cyr L l}& L l\\
{\cyr M m}& M m\\
{\cyr N n}& N n\\
{\cyr O o}& O o\\
{\cyr P p}& P p\\
{\cyr R r}& R r\\
{\cyr S s}& S s\\
{\cyr T t}& T t\\
{\cyr U u}& U u\\
{\cyr F f}& F f\\
{\cyr H h}& H h\\
{\cyr C c}& C c (or Ts ts)\\
{\cyr Ch ch}& Ch ch (or Q q)\\
{\cyr Sh sh}& Sh sh (or X x)\\
{\cyr Shch shch}& W w (or Shch shch, Xq xq)\\
{\cyr \Cdprime\ \cdprime}& $\backslash$Cdprime $\backslash$cdprime\\
{\cyr Y y}& Y y\\
{\cyr \Cprime\ \cprime}& $\backslash$Cprime $\backslash$cprime\\
{\cyr \`E \`e}& $\backslash$`E $\backslash$`e\\
{\cyr Yu yu}& Yu yu\\
{\cyr Ya ya}& Ya ya\\ \hline
\end{tabular}
\end{center}
Note what is an annoying misfeature here: a very common digraph {\cyr
t\null s} is not represented by  {\tt ts}, because the latter 
is reserved for the representation of {\cyr c}. To write {\cyr t\null s}
use {\tt t$\backslash$null s}.

\chapter{Keyboard layouts}
\begin{tabular}{||c|c|c|||c|c|c||}
\hline
\hline
English&  Russian& Mixed& English&  Russian& Mixed\\       
(QWERTY)& ({\cyr \u{I}CUKEN})&  ({\cyr YaVERTY})& (QWERTY)& ({\cyr \u{I}CUKEN})&  ({\cyr YaVERTY})\\ \hline 
 q Q&  {\cyr \u\i\ \u{I}}&     {\cyr ya Ya}& m M&  {\cyr \cprime\ \Cprime}&  {\cyr m M}\\
 w W&  {\cyr c C}&     {\cyr v V}& {\tt [} \{ &{\cyr h H}&{\cyr x X}\\
 e E&  {\cyr u U}&           {\cyr e e}& {\tt ]} \} &{\cyr \cdprime\ \Cdprime}&{\cyr w W}\\
 r R&  {\cyr k K}&         {\cyr r R}&  ; :&  {\cyr zh Zh} &\\
 t T&  {\cyr e E}&         {\cyr t T}&  ' "&  {\cyr \`e \`E} &\\
 y Y&  {\cyr n N}&         {\cyr y Y}&   , {\tt <}&  {\cyr b B}& \\
 u U&  {\cyr g G}&         {\cyr u U}&  . {\tt >}&  {\cyr yu Yu}& \\
 i I&  {\cyr x X}&         {\cyr i I}&  ` $\sim$ &    &       {\cyr yu Yu}\\
 o O&  {\cyr w W}&         {\cyr o O}&  3 \# &&       {\cyr 3 \cdprime}\\
 p P&  {\cyr z Z}&        {\cyr p P}&  4 \$ & 4 " & \\
 a A&  {\cyr f F}&        {\cyr a A}&  5 \% & 5 : & \\
 s S&  {\cyr y Y}&      {\cyr s S}&  6 \^{}& 6 , & \\
 d D&  {\cyr v V}&         {\cyr d D}&  7 \& & 7 . & \\
 f F&  {\cyr a A}&         {\cyr f F}&  = +&  &       {\cyr q Q}\\
 g G&  {\cyr p P}&          {\cyr g G}&$\backslash$ |&       &       {\cyr \`e \`E}\\
 h H&  {\cyr r R}&          {\cyr h H}&&&\\
 j J&  {\cyr o O}&          {\cyr \u\i\ \u{I}}&&&\\
 k K&  {\cyr l L}&        {\cyr k K}&&&\\
 l L&  {\cyr d D}&         {\cyr l L}&&&\\
 z Z&  {\cyr ya Ya}&         {\cyr z Z}&&&\\ 
 x X&  {\cyr q Q}&         {\cyr \cprime\ \Cprime}&&&\\
 c C&  {\cyr s S}&         {\cyr c C}&&&\\
 v V&  {\cyr m M}&         {\cyr zh Zh}&&&\\  
 b B&  {\cyr i I}&         {\cyr b B}&&&\\
 n N&  {\cyr t T}&          {\cyr n N}&&&\\
% m M&  {\cyr \cprime\ \Cprime}&  {\cyr m M}&&&\\
% {\tt [} \{ &{\cyr h H}&         {\cyr x X}&&&\\
% {\tt ]} \} &{\cyr \cdprime\ \Cdprime}&{\cyr w W}&&&\\
% ; :&  {\cyr zh Zh}&&& \\  
% ' "&  {\cyr \`e \`E}&&& \\
% , {\tt <}&  {\cyr b B}&&& \\
% . {\tt >}&  {\cyr yu Yu}&&& \\
% ` $\sim$ &         &    {\cyr yu Yu}&&&\\
% 3 \# &     &       {\cyr 3 \cdprime}&&&\\
% 4 \$ & 4 " & \\ 
% 5 \% & 5 : & \\ 
% 6 \^{}& 6 , & \\ 
% 7 \& & 7 . & \\
% = +&              &    {\cyr q Q}\\
% $\backslash$ |&      &    {\cyr \`e \`E}\\
\hline
\end{tabular}

\chapter{Available fonts list}
\begin{tabular}{llllllll}
koi-8&
koi10x20&
koi12x24&
cour12&
cour24&
cour10&
cour14&
cour08\\
cour18&
koi10x16b&
koi8x8&
time08i&
menu12&
time18i&
courcc01&
menu10\\
courcc02&
courcc03&
time08b&
courbc01&
time18b&
courbc02&
courbc03&
time12i\\
time24i&
time10i&
courac01&
time14b&
courac02&
courac03&
time12b&
time24b\\
time14i&
time10b&
term14d&
term10n&
cour12b&
cour24b&
cour14o&
term14b\\
cour10b&
term10d&
term14n&
cour10o&
term10b&
cour14b&
cour12o&
cour24o\\
cour08b&
term18n&
courec01&
cour18b&
courec02&
courec03&
term18d&
cour18o\\
courdc01&
term18b&
courdc02&
cour08o&
courdc03&
helvec04&
helvec05&
helvec06\\
helvec01&
helvec02&
helvec03&
helvdc04&
851401&
helvdc05&
helvdc06&
helvdc01\\
helvdc02&
helvdc03&
helvcc04&
helvcc05&
helvcc06&
helvcc01&
helvcc02&
helvcc03\\
helvac04&
helvac05&
helvac06&
helvac01&
helvac02&
helvac03&
helv08&
koi6x13\\
helv18&
koi6x10&
helv12&
helv24&
helv10&
helv14&
koi8x13&
koi8x16\\
koi8x14&
koi9x15&
avan18bo&
cour18bo&
avan08do&
avan08bo&
cour08bo&
avan18do\\
term18bn&
term18bd&
term14bn&
avan10bo&
cour10bo&
avan12do&
avan24do&
term14bd\\
avan12bo&
avan24bo&
cour12bo&
cour24bo&
avan10do&
term10bn&
avan14bo&
cour14bo\\
term10bd&
avan14do&
helv10bo&
time14bi&
helv12bo&
helv24bo&
helv14bo&
time10bi\\
time12bi&
time24bi&
helv18bo&
helv08bo&
time18bi&
time08bi&
term14&
term10\\
term18&
time08&
time18&
time14&
time12&
time24&
time10&
tmsrbc02\\
tmsrec04&
tmsrec05&
tmsrec06&
tmsrec01&
tmsrec02&
tmsrec03&
helv08b&
helv18b\\
helv18o&
helv08o&
helv12b&
helv24b&
helv14o&
helv10b&
helv10o&
helv14b\\
helv12o&
helv24o&
avan10d&
avan12b&
avan24b&
avan12d&
avan24d&
avan10b\\
avan14d&
avan14b&
avan18d&
avan08b&
avan08d&
avan18b&
koinil2&
crox2ho\\
crox2hb&
crox1ho&
crox4hbo&
crox3hb&
crox1cbo&
crox1cb&
crox2co&
crox4hb\\
crox3co&
crox5hb&
crox2cbo&
crox6ho&
crox3cb&
crox6hb&
crox5ho&
crox6hbo\\
crox2cb&
crox1co&
crox3cbo&
crox4ho&
crox6tb&
crox1hbo&
crox5to&
crox4to\\
crox4tb&
crox5tb&
crox6to&
crox2tb&
crox1to&
crox3hbo&
crox3tb&
crox2hbo\\
crox3to&
crox1tb&
crox2to\\

\end{tabular}
\end{document}
