

                  _________________________________________
                 |                                         |
                 |           Freemacs MULE  1.0            |
                 |  Copyright (C) Francesco Zamblera 2006  |
                 |           under the  GNU GPL            |
                 |                                         |
                 |           vilnergoy@yahoo.it            |
                 |_________________________________________|


1. Freemacs MULE.
2. How to install MULE.
3. How to use Freemacs with MULE.
4. How Freemacs MULE works.
5. How to customize and update MULE.


-----------------
1. Freemacs MULE.
-----------------

    Welcome to Freemacs MULE.

    This package contains a series of utilities to help transforming
FREEMACS into a multilingual environment.

    FREEMACS MULE uses the FreeDOS utility XKEYB together with a
modified version of Kurt Zammit's GNUCHCP, to load fonts and keyboard
drivers.
    A series of mint functions has been written which permits the
user to switch character sets and keyboards from within FREEMACS, and
to print text to a PS file. You can later print that file directly
with a PostScript printer, or, using the GNU program GhostView, you
can view it or transform it into a PDF.

    You can refer to the file LISTING.TXT, for the lis of files
contained in the package.


-----------------------
2. How to install MULE.
-----------------------

    To install MULE, you will have to follow two step, and, if you
don't use a US keyboard, a preliminary step also. A simple batch
script has been included which performs the first step, and finding
the file INSTALL.MIN into Freemacs will help you perform the rest.

1)  If you use a keyboard other than an US one, first open the file

                             LANGCFG.MIN

    into EMACS, and follows the instructions therein.

2)  Make sure that you have the DOS environment variable EMACS
defined. (You already should have it, because, if you haven't, Freemacs
doesn't work). Then make sure you have no directory called "MULE"
into your EMACS directory (if you happen to have one, rename it
before you go ahead).

3) FIrst step: now you can switch to the directory where you unzipped
the MULE package, with all its .dat, .key, .exe, .ed, .ps, .txt and .bat
files.  Then just run

INSTALL

and a subdirectory \mule will be created in your EMACS directory; all
files will be copied to their proper positions, then EMACS should be
invoked, and the file INSTALL.MIN visualized. For the second step,
just follow the instructions therein.


---------------------------------
3. How to use Freemacs with MULE.
---------------------------------

    MULE provides your Freemacs editor with five new functions,
which get installed into the USER library (they have have prefix U:).
    If you have chosen a key binding for the functions during the
installation, you can invoke them by hitting the corresponding
keychords. If not, you can invoke them with M-x, followed by the
funcion's name.

    The functions are:

1. kbd-fnt-ld ("keyboard and font loading"). This function loads a
font into the video memory, in the upper ASCII table (characters 128
to 255), and a keyboard driver, which will have your keyboard display those
characters.
    When you invoke this function, you will be prompted for an
encoding name (see files ENCODING.TXT and LANGS.TXT for more info).
    If you type "cyr1", your Freemacs should start displaying
Cyrillic characters.

    To find out how to get the various Russian letters with your
keyboard, see the keyboard mappings in the files "cyr1_map.ps" (if
you use the .txt version, make sure you first loaded Cyrillic fonts!).

2. kbd-fnt-uld ("unload keyboard and font"). Restores font and
keyboard driver. If you have typed something in Russian and then
invoke kbd-fnt-uld, you will now see strange signs in place of the
Russian characters you typed. However, don't worry. The data you
typed are still all in. If you invoke again kbd-fnt-ld and respond
"russian" at the prompt, you will see your Russian letters again.
    And if you make a PS while still seeing the strange signs, you'll
get the correct characters in the PS.

3. kbd-load ("Load keyboard") and
4. kbd-unload ("Unload keyboard"). This functions load/unload only
the keyboard driver; the font remains loaded in memory. So, if you are
typing Russian, and need to enter something in English, you need only
to temporarily unload the keyboard driver. Invoke kbd-unload, and
you'll see Russian characters still in place.
    However, if you type something now, you'll get Latin letters. When
you are done with English, and want to switch back to Russian, you
can invoke kbd-load.
    If you have to invoke some Freemacs command, remember to invoke
kbd-unload first, in order to switch off the keyboard driver.
Otherwise, if you are prompted for a "y/n" answer and type a "n",
you'll be actually typing a Cyrillic n (with a differen ASCII code),
and your answer will not be recognized! (If you get into such a
situation by mistake, simply exit the command by typing C-G, then invoke
kbd-unload to switch off the keyboard driver, then try again).
    Using kbd-load and kbd-unload, you can toggle between keyboard
drivers if you have to write a mixed-language text.

5. print-to-ps. This function "prints" the current buffer to a PS
file. If your buffer has a filename associated with it, the PS file
will have the same name, only with a .ps extension. If you are using
a buffer without associated file name, the output file will be named
"print.ps", and will be located in the current directory.


--------------------------
4. How Freemacs MULE works
--------------------------

    This multilingual environment is aimed first of all at American
First Nation Languages, but I have included some basic charsets as latin1
(Western Europe), latin2 (Central and Eastern Europe), Cyrillic and
Greek. For these I have followed ISO 8859 codepages.
    In this way, a text in, say, Russian, written with Freemacs,
should be properly rendered by other text editors as well, provided
that the correct encoding is set.

    For American First Nation Languages, on the other hand, I have
tried to define some new "codepages". These encodings won't work with
other text editors or word processors (they will work if you load the
font file with gnuchcp2: for example, to load Inuktitut syllabary,
which is specified by the "afn3" encoding, enter

                        gnuchcp3 %EMACS%mule\fonts\afn3.dat

before you invoke the editor, and

                        gnuchcp3 %EMACS%mule\fonts\afn3.dat

    PS files should be properly printed by every PostScript printer,
and displayed correctly by every PS viewer such as GhostView, because
print2ps embeds a font dictionary into the text, building it from the
bitmaps stored in the .dat file. If you have GNU GhostScript (which is
available for many platforms, including DOS), you'll be able to make a
PDF from the PS file, and this PDF should show the correct glyphs
everywhere (only, this PDF won't be of a very high quality because of
the bitmap fonts).

    Every .dat file in the set is associated to a keyboard driver with
extension .key, and with a similar name. I have used three or four
character names for the .dat files.
    The .key files are ASCII text files to be used by XKEYB. Their
name starts with the .dat file name, followed by a "_", and a further
two-letter  code which identifies the keyboard installed, and finally
the .key extension.
    Finally, every .key file has an associated text file with the
same name and extension .map. Such a file contains a list of the key
bindings for the corresponding keyboard driver. Have a look at this
file to find out which keys to hit in order to get the characters you
want. Hence, for an Italian keyboard, you will have:


FONTS		KEYBOARDS		MAPPINGS

cyr1.dat	cyr1_it.key		cyr1_it.map (cyr1_it.ps)
grk.dat		grk_it.key		grk_it.txt (grk_it.ps)
etc.


    In this package, I have provided .key files for US, SP and IT
keyboards, but if you have another keyboard installed in your DOS,
you can easily make your own keyboard driver with MAKEKEYB
(downloadable from my web page). Please note that, having an Italian
keyboard, I couldn't test the US and SP series properly (feedback will be
warmly welcomed).
    Of course, if you are not satisfied with the mapping I provide, you can
make your own driver with MAKEKEYB (for example, if you already have
a Russian keyboard, you probably will want to use the mapping you are
accustomed to, rather than the US-, IT- or SP-keyboard compliant).

    (Please note that keyboard mappings and encoding are independent
of each other. In the Cyrillic fonts provided here, for example, a
Cyrillic uppercase "A" is encoded as ASCII 176, irrespectively of
which key a keyboard driver binds that character to).


    MULE directory tree:

%EMACS%MULE          MULE main directory. Contains .exe and .ed files,
                     the .ps template file, and COPYING.TXT.

%EMACS%MULE\SRC      Contains mint and PASCAL sources.

%EMACS%MULE\DOC      Contains .txt files for documentation.

%EMACS%MULE\KEY      Contains the keyboard drivers.

%EMACS%MULE\FONTS    Contains the bitmaps.

%EMACS%MULE\MAPPINGS Contains the .map files.


------------------------------------
5. How to customize and update MULE.
------------------------------------

    If you want to install some new font and keyboard driver, you will
have to:

-give the font bitmap file a .dat extension, and copy it into the
%EMACS%MULE\FONTS directory;

-copy the keyboard driver source file, with extension .key, into the
%EMACS%MULE\KEYB directory. These two filenames must obey the MULE
fonts and keyboards naming convention (see above at the end of section 4);

     If you changed your system keyboard, you will need to define new
mappings with MAKEKEYB and  move all your new .key and .map files
into the appropriate subdirectories. Then open the file

                      %EMACS%MULE\SRC\LANGCFG.MIN

with FREEMACS and follow the instructions therein.



