* -*- mode: outline -*-           Time-stamp: <2002-03-11 17:49:06 pok>

If you are reading this in Emacs, you may want to hit "C-c C-t" to see
the outline (and "C-h m" to learn about the outline mode).


* About this File

Name:         ./README
Content:      Information about Esperanto dictionary for the Ispell speller
Created:      1997-08-30 de Sergio Pokrovskij <pok@nbsp.nsk.su>
Version 3.3.

Copyright 1997, 1998, 2002 Sergio Pokrovskij

This dictionary package is available on the terms of GNU General Public License
(Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA).


* About the Package

Here is the Esperanto dictionary, compiled by Sergio Pokrovskij for
the version 3 of ispell.

** The Ispell utility program

You will first need to get ispell 3.0+ it is available from
ftp://ftp.cs.ucla.edu/pub/ispell-3.1; make sure that in its local.h
NO8BIT is commented out and MASKBITS = 64.  To see the options ispell
has been compiled with run
$ ispell -vv


** Esperanto encodings

Several encodings used with Esperanto text are supported:

1. The very best is Unicode or its subset, which contains the
   esperantic letters, like the Microsoft's WGL4; you can use it with
   xterm or Emacs under Unix, or with UniRed under Windows (the latter
   has not been checked yet for the current version).

   Unicode is available in UTF-8 encoding which is becoming standard
   for Unices.
   
2. The second best choice is the Latin-3 encoding (ISO-8859-3).

3. For the sake of the ASCII-impaired (and ANSI-impaired), there are
   two surrogates:

3.1. The TeX-like ^cirka^u-style: e^ho^san^go ^ciu^ja^ude.
     Presently this is made the reference representation, mainly
     because it is unambiguous (cf names like "Michaux") and 

3.2. The most popular cxirkaux-style, which is also convenient for
     lexicographical ordering and thus is used in the dictionaries;
     besides, it uses letters only, and that makes it suitable for
     variable names in computer programs.

     
* INSTALLATION

** Plain Install (Unix or Cygwin)

1. Unpack ispell-eo (you've done that since you are reading me).
2. Go to the root directory ispell-eo (where this README resides).
3. Say
   $ make first
   (or simly "make") in order to check your ispell program.
   Examine the output, e.g. do you have the permissions to write the
   hash file(s) at the install phase?

4. If everything is OK, say
   $ make eo
   (to built the strict dictionary), or
   $ make esperanto
   (to built a permissive dictionary), or
   $ make all
   (to built both).

   You'll get a few warnings of from buildhash, like this one:
,----
| eo.aff line 218: Flag must be alphabetic
`----
   Just ignore them.

5. Type
   $ make install
   to copy the hash file(s) to where ispell expects them to be
   (probably you already have your american.hash there; normally
   you shall need the root rights to make install).

After that you can call
                  ispell -d eo FILENAME


** Customized Build

In order to enable selective construction of dictionaries, some
entries in the source dictionary ./src/vortoj.l3 are marked with
keywords indicating the special field they belong to:

#arhx    archaic words, like ^hina or j
#Eujo    vocabulary of the Esperanto Movement (Esperantujo)
#etn     countries and ethnography
#komp    some computer-science terminology according to the
         "Komputika Leksikono"
         <http://www.esperanto.mv.ru/KompLeks/UTF8/DEFAULT.html> 
#mav     redundant words, which are used by some esperantists,
         though they are less precise and unnecessarily
         complicate the language; e.g. olda (maljuna or
         malnova), "mava" (malbona)
#pers    given names and names of important personalities
         (Petro, Zamenhof, Noa ...)
#pok     the words specific to my idiolect
#var     variant which I do not use but which is frequent enough
         (e.g. kemio, tekniko opposed to ^hemio and te^hniko).
...

You can
$ grep '#mav' ./src/vortoj.l3 | less
in order to see if you feel like me about them; you can either remove
all of them from the target dictionary, or remove the #mav mark from
those you do use and like; the setting in the ./Makefile, 

short_list	=	komp,etn,Eujo,pers,mll
eo_list         =	$(short_list),drv
esperanto_list	=	$(short_list),arhx,mav,rar


To make a customized dictionary, 

     sort -u -f -o eo.txt kerno.txt komputo.txt

Use buildhash to create the hashed dictionary:

     buildhash eo.txt eo.aff eo.hash

(A model command file `kunmetu' and the resulting eo.hash are included
in the package.)


* Usage

** Commandline

You can use ispell in a stand-alone mode; type

    ispell -d eo FILENAME

or you may prefer to customize your emacs; e.g. copy
./emacs/ispell-ini.el from this distribution into your site-lisp (or
somewhere else on your emacs load-path), and put this into your .emacs

(load "ispell-ini.el")

Some more comments are in legumin.l3 (in esperanto).

** emacs.el

I enclose the emacs/ispell.el file, which is a modified version of
ispell.el which comes with the Emacs distribution.  There are to
modifications:

1. the variable ispell-dictionary-alist-3 is modified to use the
   latin-3 encoding (it is latin-1 in the distribution);

2. the coordinates of the correction for the word being checked is
   done in a more thourough fashion.  The original version fails to
   account for the fact that ispell returnes multibyte representation,
   while the internal Emacs representation for the utf-8 takes one
   unut per character.  As a result, the "misalignment error" occurs,
   when the word is close to the end of line, and the correction end
   extends beyond the end of line.  With my patch the esperantic texts
   in utf-8 are spellchecked normally, unless a foreign character
   occurs in the buffer; but that is a dofferent bug, which is present
   for the unibyte encodings as well.

* New in v.3.1

1. More affix flags are defined; this requires an ispell built with
   MASKBITS = 64 (or more).

2. Presently the main ASCIIzation is in the TeX style.  (The
   cxirkaux-transcription is available as an alternative
   representation.)

3. Some non-esperantic letters are made available, like \c{c}, \"o,
   {\o} ktp for the names like W\"uster or St{\o}p-Bowitz.  This is
   done for a few most frequent letters only; more work is needed.

4. Two flavors of Esperanto dictionaries/grammars are introduced: the
   permissive "esperanto" and the rigorous "eo".

5. The installation process is automated on the basis of (gnu)make and
   some other Unix utilities.

6. All the specialized subdictionaries are merged into a single
   database (with subject area marks).

7. An Emacs function word+ is written for the dictionary database
   maintainance.


* TODO

1. More Latin letters.

2. Better and/or more portable tools for dictionary maintenance.
   (Maybe a Perl script?)

3. Try aspell (especially to improve the heuristics on the basis of
   graphical similarities for the scanned texts).