"Fossies" - the Fresh Open Source Software Archive

Member "aspell-0.60.8/README" (12 Oct 2019, 19961 Bytes) of package /linux/misc/aspell-0.60.8.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 0.60.7_vs_0.60.8.

    1 Appendix A Installing
    2 *********************
    3 
    4 Aspell requires gcc 2.95 (or better) as the C++ compiler.  Other C++
    5 compilers should work with some effort.  Other C++ compilers for mostly
    6 POSIX compliant (Unix, Linux, BeOS, Cygwin) systems should work without
    7 any major problems provided that the compile can handle all of the
    8 advanced C++ features Aspell uses.  C++ compilers for non-Unix systems
    9 might work but it will take some work.  Aspell at very least requires a
   10 Unix-like environment ('sh', 'grep', 'sed', 'tr', ...), and Perl in
   11 order to build.  Aspell also uses a few POSIX functions when necessary.
   12 
   13    The latest version can always be found at GNU Aspell's home page at
   14 <http://aspell.net>.
   15 
   16 A.1 Generic Install Instructions
   17 ================================
   18 
   19      ./configure && make
   20 
   21    For additional 'configure' options type './configure --help'.  You
   22 can control what C++ compiler is used by setting the environment
   23 variable 'CXX' before running configure and you can control what flags
   24 are passed to the C++ compile via the environment variable 'CXXFLAGS'.
   25 Static libraries are disabled by default since static libraries will not
   26 work right due to the mixing of C and C++.  When a C program links with
   27 the static libraries in Aspell it is likely to crash because Aspell's
   28 C++ objects are not getting initialized correctly.  However, if for some
   29 reason you want them, you can enable them via '--enable-static'.
   30 
   31    Aspell should then compile without any additional user intervention.
   32 If you run into problems please first check the sections below as that
   33 might solve your problem.
   34 
   35    To install the program simply type
   36 
   37      make install
   38 
   39    After Aspell is installed at least one dictionary needs to be
   40 installed.  You can find them at <http://aspell.net/>.  The 'aspell'
   41 program must be in your path in order for the dictionaries to install
   42 correctly.
   43 
   44    If you do not have Ispell or the traditional Unix 'spell' utility
   45 installed on your system then you should also copy the compatibility
   46 scripts 'ispell' and 'spell' located in the 'scripts/' directory into
   47 your binary directory which is usually '/usr/local/bin' so that programs
   48 that expect the 'ispell' or 'spell' command will work correctly.
   49 
   50 A.2 HTML Manuals and 'make clean'
   51 =================================
   52 
   53 The Aspell distribution includes HTML versions of the User and
   54 Developer's manual.  Unfortunately, doing a 'make clean' will erase
   55 them.  This is due to a limitation of automake which is not easily
   56 fixed.  If makeinfo is installed they can easily be rebuild with 'make
   57 aspell.html aspell-dev.html', or you can unpack them from the tarball.
   58 
   59 A.3 Curses Notes
   60 ================
   61 
   62 If you are having problems compiling 'check_funs.cpp' then the most
   63 likely reason is due to incompatibilities with the curses implementation
   64 on your system.  You should first try disabling the "wide" curses
   65 library with the '--disable-wide-curses' configure option.  By doing so
   66 you will lose support for properly displaying UTF-8 characters but you
   67 may still be able to get the full screen interface.  If this fails then
   68 you can disable curses support altogether with the '--disable-curses'
   69 configure option.  By doing this you will lose the nice full screen
   70 interface but hopefully you will be able to at least get Aspell to
   71 compile correctly.
   72 
   73    If the curses library is installed in a non-standard location then
   74 you can specify the library and include directory with
   75 '--enable-curses=LIB' and '--enable-curses-include=DIR'.
   76 
   77    'LIB' can either be the complete path of the library--for example
   78      /usr/local/curses/libcurses.a
   79    or the name of the library (for example 'ncurses') or a combined
   80 location and library in the form '-LLIBDIR -lLIB' (for example
   81 '-L/usr/local/ncurses/lib -lncurses').
   82 
   83    DIR is the location of the curses header files (for example
   84 '/usr/local/ncurses/include').
   85 
   86 A.3.1 Unicode Support
   87 ---------------------
   88 
   89 In order for Aspell to correctly spell check UTF-8 documents in full
   90 screen mode the "wide" version of the curses library must be installed.
   91 This is different from the normal version of curses library, and is
   92 normally named 'libcursesw' (with a 'w' at the end) or 'libncursesw'.
   93 UTF-8 documents will not display correctly without the right curses
   94 version installed.
   95 
   96    In addition your system must also support the 'mblen' function.
   97 Although this function was defined in the ISO C89 standard (ANSI
   98 X3.159-1989), not all systems have it.
   99 
  100 A.4 Loadable Filter Notes
  101 =========================
  102 
  103 Support for being able to load additional filter modules at run-time has
  104 only been verified to work on Linux platforms.  If you get linker errors
  105 when trying to use a filter, then it is likely that loadable filter
  106 support is not working yet on your platform.  Thus, in order to get
  107 Aspell to work correctly you will need to avoid compiling the filters as
  108 individual modules by using the '--enable-compile-in-filters'
  109 'configure' option.
  110 
  111 A.5 Using 32-Bit Dictionaries on a 64-Bit System
  112 ================================================
  113 
  114 Due to an oversight, Aspell compiled dictionaries not only depend on the
  115 endian order, they also depend on the the size of the 'size_t' type,
  116 which is generally different on 32 and 64-bit systems.  The 'size_t'
  117 type is used in the hash function of the compiled dictionaries.  To
  118 force the hash function to use a 32-bit integer instead, use the
  119 '--enable-32-bit-hash-fun' configure option.  This option will allow you
  120 to use dictionaries compiled on a 32-bit machine on a 64-bit one as long
  121 as the endian order is the same.  Of course, dictionaries compiled on a
  122 64-bit machine without this option enabled will no longer be usable.  If
  123 Aspell detects that an incompatible hash function is used, it will fail
  124 with:
  125      Error: The file "SOME-FILE" is not in the proper format.
  126      Incompatible hash function.
  127 
  128 A.6 Upgrading from Aspell 0.60.7
  129 ================================
  130 
  131 To prevent a potentially unbounded buffer over-read, Aspell no longer
  132 supports null-terminated UCS-2 and UCS-4 encoded strings with the
  133 original C API. Null-termianted 8-bit or UTF-8 encoded strings are still
  134 supported, as are UCS-2 and UCS-4 encoded strings when the length is
  135 passed in.
  136 
  137    As of Aspell 0.60.8 a function from the original API that expects an
  138 encoded string as a parameter will return meaningless results (or an
  139 error code) if string is null terminated and the encoding is set to
  140 'ucs-2' or 'ucs-4'.  In addition, a single:
  141      ERROR: aspell_speller_check: Null-terminated wide-character strings unsupported when used this way.
  142    will be printed to standard error the first time one of those
  143 functions is called.
  144 
  145    Application that use null-terminated UCS-2/4 strings should either
  146 (1) use the interface intended for working with wide-characters (*note
  147 Through the C API::); or (2) define 'ASPELL_ENCODE_SETTING_SECURE'
  148 before including 'aspell.h'.  In the latter case is is important that
  149 the application explicitly sets the encoding to a known value.  Defining
  150 'ASPELL_ENCODE_SETTING_SECURE' and not setting the encoding explicitly
  151 or allowing user of the application to set the encoding could result in
  152 an unbounded buffer over-read.
  153 
  154    If it is necessary to preserve binary compatibility with older
  155 versions of Aspell, the easiest thing would be to determine the length
  156 of the UCS-2/4 string--in bytes--and pass that in.  Due to an
  157 implemenation detail, existing API functions can be made to work with
  158 null-terminated UCS-2/4 strings safely by passing in either '-2' or '-4'
  159 (corresponding to the width of the character type) as the size.  Doing
  160 so, however, will cause a buffer over-read for unpatched version of
  161 Aspell.  To avoid this it will be necessary to parse the version string
  162 to determine the correct value to use.  However, no official support
  163 will be provided for the latter method.
  164 
  165    If the application can not be recompiled, then Aspell can be
  166 configured to preserve the old behavior by passing
  167 '--enable-sloppy-null-term-strings' to 'configure'.  When Aspell is
  168 compiled this way the version string will include the string ' SLOPPY'.
  169 
  170 A.7 Upgrading from Aspell 0.50
  171 ==============================
  172 
  173 The dictionary format has changed so dictionaries will need to be
  174 recompiled.
  175 
  176    All data, by default, is now included in 'LIBDIR/aspell-0.60' so that
  177 multiple versions of Aspell can more peacefully coexist.  This included
  178 both the dictionaries and the language data files which were stored in
  179 'SHAREDIR/aspell' before Aspell 0.60.
  180 
  181    The format of the character data files has changed.  The new
  182 character data files are installed with Aspell so you should not have to
  183 worry about it unless you made a custom one.
  184 
  185    The dictionary option 'strip-accents' has been removed.  For this
  186 reason the old English dictionary (up to 0.51) will no longer work.  A
  187 new English dictionary is now available which avoids using this option.
  188 In addition the 'ignore-accents' option is currently unimplemented.
  189 
  190    The flag '-l' is now a shortcut for '--lang', instead of '--list' as
  191 it was with Aspell 0.50.
  192 
  193 A.7.1 Binary Compatibility
  194 --------------------------
  195 
  196 The Aspell 0.60 library is binary compatible with the Aspell 0.50
  197 library.  For this reason I chose _not_ to increment the major version
  198 number (so-name) of the shared library by default which means programs
  199 that were compiled for Aspell 0.50 will also work for Aspell 0.60.
  200 However, this means that having both Aspell 0.50 and Aspell 0.60
  201 installed at the same time can be pragmatic.  If you wish to allow both
  202 Aspell 0.50 and 0.60 to be installed at the same time then you can use
  203 the configure option '--incremented-soname' which will increment
  204 so-name.  You should only use this option if you know what you are
  205 doing.  It is up to you to somehow ensure that both the Aspell 0.50 and
  206 0.60 executables can coexist.
  207 
  208    If after incrementing the so-name you wish to allow programs compiled
  209 for Aspell 0.50 to use Aspell 0.60 instead (thus implying that Aspell
  210 0.50 is not installed) then you can use a special compatibility library
  211 which can be found in the 'lib5' directory.  This directory will not be
  212 entered when building or installing Aspell so you must manually build
  213 and install this library.  You should build it after the rest of Aspell
  214 is built.  The order in which this library is installed, with relation
  215 to the rest of Aspell, is also important.  If it is installed _after_
  216 the rest of Aspell then new programs will link to the old library (which
  217 will work for Aspell 0.50 or 0.60) when built, if installed _before_,
  218 new programs will link with the new library (Aspell 0.60 only).
  219 
  220 A.8 Upgrading from Aspell .33/Pspell .12
  221 ========================================
  222 
  223 Aspell has undergone an extremely large number of changes since the
  224 previous Aspell/Pspell release.  For one thing Pspell has been merged
  225 with Aspell so there in no longer two separate libraries you have to
  226 worry about.
  227 
  228    Because of the massive changes between Aspell/Pspell and Aspell 0.50
  229 you may want to clean out the old files before installing the the new
  230 Aspell.  To do so do a 'make uninstall' in the original Aspell and
  231 Pspell source directories.
  232 
  233    The way dictionaries are handled has also changed.  This includes a
  234 change in the naming conventions of both language names and
  235 dictionaries.  Due to the language name change, your old personal
  236 dictionaries will not be recognized.  However, you can import the old
  237 dictionaries by running the 'aspell-import' script.  This also means
  238 that dictionaries designed to work with older versions of Aspell are not
  239 likely to function correctly.  Fortunately new dictionary packages are
  240 available for most languages.  You can find them off of the Aspell home
  241 page at <http://aspell.net>.
  242 
  243    The Pspell ABI is now part of Aspell except that the name of
  244 everything has changed due to the renaming of Pspell to Aspell.  In
  245 particular please note the following name changes:
  246 
  247      pspell -> aspell
  248      manager -> speller
  249      emulation -> enumeration
  250      master_word_list -> main_word_list
  251 
  252    Please also note that the name of the 'language-tag' option has
  253 changed to 'lang'.  However, for backward compatibility the
  254 'language-tag' option will still work.
  255 
  256    However, you should also be able to build applications that require
  257 Pspell with the new Aspell as a backward compatibility header file is
  258 provided.
  259 
  260    Due to a change in the way dictionaries are handled, scanning for
  261 '.pwli' files in order to find out which dictionaries are available will
  262 no longer work.  This means that programs that relied on this technique
  263 may have problems finding dictionaries.  Fortunately, GNU Aspell now
  264 provided a uniform way to list all installed dictionaries via the c API.
  265 See the file 'list-dicts.c' in the 'examples/' directory for an example
  266 of how to do this.  Unfortunately there isn't any simple way to find out
  267 which dictionaries are installed which will work with both the old
  268 Aspell/Pspell and the new GNU Aspell.
  269 
  270 A.9 Upgrading from a Pre-0.50 snapshot
  271 ======================================
  272 
  273 At the last minute I decided to merge the 'speller-util' program into
  274 the main 'aspell' program.  You may wish to remove that 'speller-util'
  275 program to avoid confusion.  This also means that dictionaries designed
  276 to work with the snapshot will no longer work with the official release.
  277 
  278 A.10 WIN32 Notes
  279 ================
  280 
  281 A.10.1 Getting the WIN32 version
  282 --------------------------------
  283 
  284 The native Aspell/WIN32 port is no longer being maintained.  The best
  285 way to get Aspell for Windows is to use the MSYS2 binaries.  MSYS2 is
  286 available at <https://www.msys2.org/>.
  287 
  288    Binaries for Aspell 0.50 are still available at
  289 <http://aspell.net/win32/> but they are no longer supported.  If you are
  290 interested in updating them for Aspell 0.60 please let me know.
  291 
  292 A.10.2 Building the WIN32 version
  293 ---------------------------------
  294 
  295 There are two basically different ways of building Aspell using GCC for
  296 WIN32: You can either use the Cygwin compiler, which will produce
  297 binaries that depend on the POSIX layer in 'cygwin1.dll'.  The other way
  298 is using MinGW GCC, those binaries use the native C runtime from
  299 Microsoft (MSVCRT.DLL).
  300 
  301 A.10.2.1 Building Aspell using Cygwin
  302 .....................................
  303 
  304 This works exactly like on other POSIX compatible systems using the
  305 './configure && make && make install' cycle.  Some versions of Cygwin
  306 GCC will fail to link, this is caused by an incorrect 'libstdc++.la' in
  307 the '/lib' directory.  After removing or renaming this file, the build
  308 progress should work (GCC-2.95 and GCC-3.x should work).
  309 
  310 A.10.2.2 Building Aspell using MinGW
  311 ....................................
  312 
  313 There are several different ways to build Aspell using MinGW. The
  314 easiest way is to use a Cygwin compiler but instruct it to build a
  315 native binary rather than a Cygwin one.  To do this configure with:
  316 
  317      ./configure CFLAGS='-O2 -mno-cygwin' CXXFLAGS='-O2 -mno-cygwin'
  318 
  319    You may also want to add the option '--enable-win32-relocatable' to
  320 use more windows friendly directories.  *Note Win32-Directories::.  In
  321 this case configure with:
  322 
  323      ./configure CFLAGS='-O2 -mno-cygwin' CXXFLAGS='-O2 -mno-cygwin' --enable-win32-relocatable
  324 
  325    It should also be possible to build Aspell using the MSYS
  326 environment.  But this has not been very well tested.  If building with
  327 MSYS _do not_ add 'CFLAGS ...' to configure.
  328 
  329 A.10.2.3 Building Aspell without using Cygwin or MSYS
  330 .....................................................
  331 
  332 It is also possible to build Aspell without Cygwin of MinGW by using the
  333 files in the 'win32/' subdirectory.  However, these files have not been
  334 updated to work with Aspell 0.60.  Thus the following instructions will
  335 not work without some effort.  If you do get Aspell to compile this way
  336 please send me the updated files so that I can include them with the
  337 next release.
  338 
  339    To compile Aspell with the MinGW compiler, you will need at least
  340 GCC-3.2 (as shipped with MinGW-2.0.3) and some GNU tools like 'rm' and
  341 'cp'.  The origin of those tools doesn't matter, it has shown to work
  342 with any tools from MinGW/MSys, Cygwin or Linux.  To build Aspell, move
  343 into the 'win32' subdirectory and type 'make'.  You can enable some
  344 additional build options by either commenting out the definitions at the
  345 head of the Makefile or passing those values as environment variables or
  346 at the 'make' command line.  Following options are supported:
  347 
  348 'DEBUGVERSION'
  349      If set to "1", the binaries will include debugging information
  350      (resulting in a much bigger size).
  351 
  352 'CURSESDIR'
  353      Enter the path to the pdcurses library here, in order to get a
  354      nicer console interface (see below).
  355 
  356 'MSVCLIB'
  357      Enter the filename of MS 'lib.exe' here, if you want to build
  358      libraries that can be imported from MS Visual C++.
  359 
  360 'WIN32_RELOCATABLE'
  361      If set to "1", Aspell will detect the prefix from the path where
  362      the DLL resides (see below for further details).
  363 
  364 'TARGET'
  365      Sets a prefix to be used for cross compilation (e.g.
  366      '/usr/local/bin/i586-mingw32msvc-' to cross compile from Linux).
  367 
  368    There are also a MinGW compilers available for Cygwin and Linux, both
  369 versions are able to compile Aspell using the prebuilt 'Makefile'.
  370 While the Cygwin port automatically detects the correct compiler, the
  371 Linux version depends on setting the 'TARGET' variable in the 'Makefile'
  372 (or environment) to the correct compiler prefix.
  373 
  374    Other compilers may work.  There is a patch for MS Visual C++ 6.0
  375 available at <ftp://ftp.gnu.org/gnu/aspell>, but it needs a lot of
  376 changes to the Aspell sources.  It has also been reported that the Intel
  377 C++ compiler can be used for compilation.
  378 
  379 A.10.3 (PD)Curses
  380 -----------------
  381 
  382 In order to get the nice full screen interface when spell checking
  383 files, a curses implementation that does not require Cygwin is required.
  384 The PDCurses (<http://pdcurses.sourceforge.net>) implementation is known
  385 to work, other implementations may work however they have not been
  386 tested.  See the previous section for information on specifying the
  387 location of the curses library and include file.
  388 
  389    Curses notes:
  390 
  391    * PDcurses built with MinGW needs to be compiled with
  392      '-DPDC_STATIC_BUILD' to avoid duplicate declaration of 'DllMain'
  393      when compiling 'aspell.exe'.
  394 
  395    * The curses enabled version can cause trouble in some shells (MSys
  396      'rxvt', 'emacs') and will produce errors like 'initscr() LINES=1
  397      COLS=1: too small'.  Use a non-curses version for those purposes.
  398 
  399 A.10.4 Directories
  400 ------------------
  401 
  402 If Aspell is configured with '--enable-win32-relocatable' or compiled
  403 with 'WIN32_RELOCATABLE=1' when using a Makefile, it can be run from any
  404 directory: it will set 'PREFIX' according to its install location
  405 (assuming it resides in 'PREFIX\\bin').  Your personal wordlists will be
  406 saved in the 'PREFIX' directory with their names changed from
  407 '.aspell.LANG.*' to 'LANG.*' (you can override the path by setting the
  408 'HOME' environment variable).
  409 
  410 A.10.5 Installer
  411 ----------------
  412 
  413 The installer registers the DLLs as shared libraries, you should
  414 increase the reference counter to avoid the libraries being uninstalled
  415 if your application still depends on them (and decrease it again when
  416 uninstalling your program).  The reference counters are located under:
  417      HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs
  418 
  419    The install location and version numbers are stored under
  420 
  421      HKLM\SOFTWARE\Aspell
  422 
  423 A.10.6 WIN32 consoles
  424 ---------------------
  425 
  426 The console uses a different encoding than GUI applications, changing
  427 this to to a Windows encoding (e.g.  1252) is not supported on Win9x/Me.
  428 On WinNT (and later) those codepages can be set by first changing the
  429 console font to 'lucida console', then changing the codepage using 'chcp
  430 1252'.
  431 
  432    Some alternative shells (e.g.  MSys' 'rxvt' or Cygwin's 'bash') do a
  433 codepage conversion (if correctly set up), so running Aspell inside
  434 those shells might be a workaround for Win9x.