                How to build Ispell on MS-DOS
		-----------------------------

This directory includes files necessary to build Ispell on MS-DOS
systems.  Two environments are supported: EMX/GCC and DJGPP; they both
generate 32-bit protected-mode programs and therefore aren't afflicted
by most of the MS-DOS memory-related limitations.  The EMX setup does
not currently support building the dictionaries, so you will need to
either build the dictionaries with DJGPP tools or get them elsewhere.
The DJGPP executables will also run on MS-Windows (3.x or 9x) as DOS
console applications.


1.  Building Ispell with EMX/GCC
    ----------------------------

    You will only need the basic EMX development tools to compile
    Ispell.  After unzipping the source archive, invoke the
    MAKEEMX.BAT batch file, like so:

	   pc\makeemx

    This generates ispell.exe and the following auxiliary programs:

	   buildhas.exe icombine.exe ijoin.exe sq.exe unsq.exe

    Install the programs anywhere along your PATH.  See the section
    named "Environment Variables" for information on environment
    variables used by the MS-DOS port of Ispell.


2.  Building Ispell (no dictionaries) with DJGPP
    --------------------------------------------

    If you only need to compile Ispell without building the
    dictionaries, use the MAKE-DJ.BAT batch file:

	   pc\make-dj

    You will need the standard DJGPP development environment
    (djdevNNN.zip, gccNNNNb.zip, bnuNNNb.zip) and the DJGPP port of
    GNU Bison (bsnNNNb.zip) for the above to work.  After the build is
    finished, read the section below about environment variables and
    install the executables and the dictionaries as you see fit.


3.  Building Ispell and the dictionaries with DJGPP
    -----------------------------------------------

    In addition to the standard development environment, you will need
    these tools to build Ispell and the dictionaries:

    a. A port of Unix-like shell.
       The only shell that was used successfully to build Ispell on
       MS-DOS is the `bash' port by Daisuke Aoyama <jack@st.rim.or.jp>
       which should be available from DJGPP archives:

	ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/bsh1147b.zip

       If not, try one of the URLs below (or write to the author of
       the port):
       
	  http://www.st.rim.or.jp/~jack/alpha/index.html
	  http://www.neongenesis.com/~jack/djgpp-work/alpha/index.html

       You should create a ``symlink'' named `sh.exe' which will run
       `bash.exe', for the Ispell Makefiles to work.  Here is how:

		stubify -g c:/djgpp/bin/sh.exe
		stubedit c:/djgpp/bin/sh.exe runfile=bash

       (change the pathname as appropriate for your installation of
       `bash').

       If you are thinking about using Stewartson's `ms_sh', don't:
       its method of passing long command lines is incompatible with
       DJGPP, and it will crash and burn on complex shell scripts.

    b. A DJGPP port of GNU Make 3.75 or later.
       This is available from DJGPP archives at the following URL:

	ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/makNNNb.zip

       Note that ports of GNU Make prior to 3.75 didn't support a
       Unix-like shell, so you won't be able to build Ispell with them.

    c. A DJGPP port of GNU Fileutils, GNU Textutils and GNU Sh-utils,
       also available from DJGPP archives:

	ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/filNNNb.zip
	ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/txtNNNb.zip
	ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/shlNNNb.zip

       In all of these URLs NNN is a version number.  If there is more
       than one ported version, get the latest one.

       The build process doesn't need *all* of the programs from these
       packages, so if you are short on disk space, you should be able
       to get away with these programs (I hope I didn't forget some):

	 Fileutils: rm, mv, chmod, install, mkdir, ln, cp, touch, ls
	 Textutils: cat, head, tail, sort, comm, wc, join, uniq
	 Sh-utils:  echo, expr, false, true

    d. GNU Sed (sed118b.zip from the DJGPP archives).

    e. GNU Awk (or any other port of Awk).  Gawk is available from the
       DJGPP site above (v2gnu/gwk303b.zip); if you use it, make a
       ``symlink'' called `awk.exe' to it:

		stubify -g c:/djgpp/bin/awk.exe
		stubedit c:/djgpp/bin/awk.exe runfile=gawk

    f. GNU Bison (bsn125b.zip from the DJGPP site).

    g. GNU Grep (grep21b.zip from the DJGPP site).

    h. Makeinfo from GNU Texinfo distribution (to produce the
       hypertext Info docs for Ispell).  Get txi390b.zip from the
       DJGPP site above.  If you have Emacs installed, you can use it
       to generate Info files instead.  The Makefile target which
       generates Info docs doesn't work on MS-DOS (see below), so you
       will have to invoke it manually.

    i. ctags and etags (for the `TAGS' and `tags' targets of the
       Makefile).  These are available from the Emacs distribution,
       also on the DJGPP archive site above (v2gnu/em1934b.zip).

    While you probably can find quite a few different ports of the
    above utilities, I would generally advise against using anything
    but the DJGPP ports, since the Makefiles and the shell scripts
    depend on long command lines and will most probably break
    otherwise.  DJGPP ports are a coherent set of tools which will
    work together well and ensure that the Makefiles and the scripts
    work as advertised.

    Here is what you should do to build Ispell:

    1) Install the above utilities anywhere along your PATH.  Make
       sure that you don't have any other executable called `sh'
       neither in /bin (if you have such a directory) nor anywhere
       along your PATH *prior* to the directory where you installed
       the bash port.  When Make runs, it will invoke the first
       program named `sh' that it finds in /bin or along the PATH, and
       you need to ensure that the right program is called.

    2) Review the options set on pc/local.djgpp and change them as you
       see fit.  Some things that you might consider changing are the
       pathnames of the standard directories, the dictionaries that
       will be built (see below), the backup extension ("~" by
       default), and the extra dictionary pathname (default:
       "c:/usr/lib/words"; make it empty if you have no extra
       dictionary).

    3) Set TMPDIR environment variable to point to a place which has
       at least 20MB of free space, for the temporary files produced
       by the dictionary build process.  This is especially important
       to those who point TMPDIR to a RAM drive, since these tend to
       be much smaller than 20MB.

    4) Type these commands:

	    pc\configdj
	    make

       This will run for some time, depending on the dictionaries that
       you've chosen to build.  The default setup builds a plus
       version of a medium-sized american dictionary, and should take
       about 20 minutes on an average 486-DX2/66.  Note that on MS-DOS
       the build time does not depend so much on the dictionary size
       as it is on Unix: it takes only about 25 minutes to build the
       extra-large plus version with /usr/dict/words file.  I believe
       the reason for this is that the build process is much more I/O
       bound on MS-DOS than it is on Unix, since MS-DOS pipes are
       simulated with disk files.

       If pc/configdj.bat complains that it runs out of environment
       space, enlarge the environment available to COMMAND.COM (or
       whatever your interactive command processor is).

       When the dictionaries are built, you will see error messages,
       about ``Improper links'', like so:

         c:/djgpp/bin/ln: cannot create symbolic link `./english.0' \
		to `../english/english.0': Improper link (EXDEV)

       You can safely disregard these messages: they are due to the
       fact that MS-DOS doesn't support symbolic links. The Makefile
       already has a provision for alternative methods which are
       automatically used in case of failures and which do work on
       MS-DOS.

       Another error message that you might see is something like
       this:

         Word 'U.S.A' contains illegal characters

       This means that some of the words in the EXTRADICT dictionary
       are incompatible with Ispell, and Ispell is ignoring them when
       it builds hashed dictionary.  (The file `/usr/dict/words' from
       Solaris machines is known to have this problem.)  The rest of
       the words are OK and will be used by Ispell, so here, too, you
       don't have to do anything about the error message.

    5) To produce the Info docs, you will have to invoke Makeinfo
       manually:

	    makeinfo ispell.texinfo

       This is because the `ispell.info' target of the Makefile fails
       on MS-DOS.  It uses the `iwhich' shell script which assumes too
       many Unixy things about where the binaries reside, and I
       decided it was not worth fixing for such a simple job.

    6) After Make finishes, install the programs and the dictionaries
       as you see fit.  The dictionary files you need to install are
       the files with a .hash extension in the subdirectories of
       languages/ directory (e.g. languages/american/amermedx.hash)
       and the file languages/english/english.aff. 

    7) If you need to use some of the shell scripts (such as iwhich,
       Makekit and splitdict), you will need to edit them to replace
       the first line which says:

	   : Use /bin/sh

       to say this instead:

	   #!/bin/sh


4.  Dictionary names
    ----------------

    The filenames used for the dictionaries on Unix are too long for
    MS-DOS, and will cause filename clashes or failed programs.
    Therefore, the MS-DOS configuration script for DJGPP edits the
    Makefiles to change these names as follows:

         americansml -> amersml
	 americanmed -> amermed
	 americanlrg -> amerlrg
	 americanxlg -> amerxlg
	 altamersml  -> altasml
	 altamermed  -> altamed
	 altamerlrg  -> altalrg
	 altamerxlg  -> altaxlg
	 britishsml  -> britsml
	 britishmed  -> britmed
	 britishlrg  -> britlrg
	 britishxlg  -> britxlg

    In addition, the `+' character (which is illegal in MS-DOS
    filenames) is converted into an `x', and if the `+' is at the end
    of the extension, it is moved into the first 8 characters of the
    basename.  Thus, americanlrg+.hash is converted into amerlrgx.hash
    and american.sml+ into americax.sml.

    These DOSified filenames are the ones that you should use if you
    decide to change the dictionaries generated by the build process.
    The easiest way to know what are the DOS names of the different
    dictionaries is to look at the edited Makefiles in languages/
    subdirectories after you build Ispell once for the default
    dictionaries.


5.  Environment variables
    ---------------------

    Ispell uses environment variables to make it easier to support
    different installations.  Most of these variables tell Ispell
    where to look for its hashed and private dictionaries.  These
    variables are documented on the ispell.1 man page and in the Info
    docs for Ispell.  Below is the list of DOS-specific environment
    variables which are not covered by the Ispell docs:

	ISPELL_OPTIONS - the default options to pass to Ispell.  These
			 are passed to Ispell as if they were typed by
			 you before all the options you actually
			 mentioned on the Ispell command line.  Since
			 Ispell parses options left to right,
			 options from the command line may override
			 those in `ISPELL_OPTIONS' variable.

	ISPELL_DICTDIR - the directory where Ispell will look for the
			 alternate hashed dictionary file.  The
			 default dictionary pathname is built into
			 Ispell when it is compiled (see the
			 definition of LIBDIR and DEFHASH on local.h
			 file, local.djgpp or local.emx), but you can
			 set this variable which will allow you to
			 name alternate dictionaries relative to the
			 directory named by it, avoiding a long
			 pathname.

	ISPELL_HOME    - replaces HOME on Unix systems.  This is where
			 Ispell looks for a personal dictionary if it
			 is given as a relative pathname.

	ISPELL_COLORS -  the colors which will be used by Ispell for
			 the normal and "standout" text.  By defualt,
			 these are the normal and inverse video
			 colors, but you may set them to any colors
			 you like.  The color descriptor is a pair of
			 numbers separated by a dot; the first number
			 is the color text attribute which will be set
			 for the normal text, and the second is the
			 attribute for the "standout" text (the
			 misspelled words).  The text color attributes
			 are the usual PC background/foreground
			 definitions.  My favorite setting is this:

			    set ISPELL_COLORS=0x1e.0x74

			 which sets the normal colors to yellow on
			 blue and the "standout" colors to red on
			 white.  The color descriptor is parsed by a
			 call to `strtoul' library function, so you
			 can use octal and hex numbers as well as
			 decimal ones.

			 This color feature is only supported by the
			 DJGPP port of Ispell.

	LINES	      -  the size of the screen to be used by Ispell.
			 Although this is not a DOS-specific variable,
			 it does have a DOS-specific effect on the
			 DJGPP port of Ispell: if the value of this
			 variable is different from the current screen
			 size, Ispell will set the screen size to the
			 size given by LINES (and restore the original
			 size when it exits or shells out to DOS).
			 The following sizes are supported by the
			 DJGPP port on a standard VGA display: 25, 28,
			 35, 40, 43 and 50 lines.  If you want to run
			 Ispell in some other non-standard screen
			 size, set the display to that size before
			 running Ispell and set LINES to that size.
