#title README about ispell eo dictionary
<contents>
* About this File

This is a short htmlized version of the =readme= file from the
=ispelleo.tar.bz2= distribution tarball.

Name:    | ./readme
Content: | Information about Esperanto dictionary for the Ispell speller
Created: | 1997-08-30 by Sergio Pokrovskij <sergio.pokrovskij(ĉe)gmail.com>
Version  | 3.7

Copyright © 1997, 1998, 2003, 2006, 2008 by Sergio Pokrovskij

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


* About the Package

Here is an 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][here]]; make sure that in its =local.h=
the =NO8BIT= thing is commented out and <code>MASKBITS = 64</code>.  To see the
options ispell has been compiled with please 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.

    Unicode is available in UTF-8 encoding, which is preferred
    for the Unices.
   
 2. The second best choice used to be the Latin-3 encoding
    (ISO-8859-3); it is obsolete by now.
 
 3. For the sake of the ASCII-impaired (and ANSI-impaired), there are
    two surrogates:
 
    - The TeX-like =^cirka^u-style: e^ho^san^go ^ciu^ja^ude=.
      Presently this is used as the reference representation, mainly
      because it is unambiguous (cf names like *Michaux*); and 
 
    - The 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

** Simple Install (Unix or Cygwin)

1. Unpack =ispelleo.tar.bz2=.

2. Go to the root directory =ispell-eo= (where this =readme= resides).

3. Say
>  =$ make first=
(or simply =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*

** Open Office

You'll need emacs to produce the dictionary for myspell which works
with Open Office.  Customize the word provision as described in
“Customized Build” (except the buildhash step); and then say
>  =$ make OO=
That should produce the files =eo_l3.aff= and =eo_l3.dic= in the =work/=
subdirectory.


** 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 *ĥina* (= *ĉina*) or *malkompreni* (= *miskompreni*)
=#bot=  | a rare botanic word
=#Eujo= | vocabulary of the Esperanto Movement (of *Esperantujo*)
=#etn=  | countries and ethnography
=#komp= | some computer-science terminology according to the [[http://www.esperanto.mv.ru/KompLeks/UTF8/DEFAULT.html][Komputada Leksikono]]
=#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 (e.g. *Petro, Zamenhof* ...)
=#pok=  | the words specific to my idiolect
=#rar=  | rare words which may coincide with a misspelling of a more frequent word; e.g. *ajuna*, *komanditi*, *liona*
=#var=  | variant which I do not use but which is frequent enough (e.g. *kemio, tekniko* opposed to *ĥemio* and *teĥniko*)
...     |  

You can
<example>
  $ grep '#mav' ./src/vortoj.l3 | less
</example>
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 default setting in the =./Makefile= is 
<example>
short_list      =  komp,etn,Eujo,pers,mll
eo_list         =  $(short_list),drv
esperanto_list  =  $(short_list),arhx,mav,rar
</example>
Unless included in the custom list (like =eo_list=), a marked word is
considered as a special one and is excluded from the build; the above
custom lists thus specify “positive criteria”.  But some words have
several marks (e.g. a word may be “ethnic” and “obsolete” or
dangerously close to a  misspelling of a frequent word).  Thus a
“negative” filtration is available via the =$(sen)= macro; you can
specify it in =src/Makefile=, or in the command-line:
<example>
  $ make eo sen="arhx,rar"
</example>

In this way some otherwise eligible words from the =komp= or =etn= or
=mll= categories shall be discarded, if they are also obsolete or rare.

* Usage

** Command line

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")=

In order to get a list of all misspelled or unknown words from a text
in the Latin-3 encoding you could say (in Linux):
<example>
   export LC_ALL=eo_XX.ISO-8859-3
   ispell -d esperanto -T .l3 -l < FILENAME | sort -u
</example>

Some more comments are in =legu-min.l3= (in esperanto).

** emacs.el

This probably is no longer required for emacs-21 or newer.

I enclose the =emacs/ispell.el= file, which is a modified version of
ispell.el which comes with the Emacs-20 distribution.  There are two
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 thorough fashion.  The original version fails to
    account for the fact that ispell returns multibyte representation,
    while the internal Emacs representation for the UTF-8 takes one
    unit 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 different bug, which is present
    for the unibyte encodings as well.

; LocalWords:  MASKBITS vv Unicode esperantic WGL UniRed UTF Unices cirka san ja
; LocalWords:  ciu ude cf Michaux cxirkaux Cygwin eo esperanto buildhash aff OO
; LocalWords:  american myspell dic arhx hina cina malkompreni miskompreni bot
; LocalWords:  Eujo Esperantujo etn komp Komputada Leksikono mav esperantists te
; LocalWords:  olda maljuna malnova mava malbona pers Petro Zamenhof Noa pok rar
; LocalWords:  ajuna komanditi liona var kemio tekniko hemio hniko grep mll drv
; LocalWords:  sen src ini LC legumin alist latin spellchecked unibyte uster
; LocalWords:  ASCIIzation Bowitz subdictionaries