cpp/galago/contrib/libstemmer_c/README

   1 libstemmer_c
   2 ============
   3
   4 This document pertains to the C version of the libstemmer distribution,
   5 available for download from:
   6
   7 http://snowball.tartarus.org/dist/libstemmer_c.tgz
   8
   9
  10 Compiling the library
  11 =====================
  12
  13 A simple makefile is provided for Unix style systems.  On such systems, it
  14 should be possible simply to run "make", and the file "libstemmer.o"
  15 and the example program "stemwords" will be generated.
  16
  17 If this doesn't work on your system, you need to write your own build
  18 system (or call the compiler directly).  The files to compile are
  19 all contained in the "libstemmer", "runtime" and "src_c" directories,
  20 and the public header file is contained in the "include" directory.
  21
  22 The library comes in two flavours; UTF-8 only, and UTF-8 plus other character
  23 sets.  To use the utf-8 only flavour, compile "libstemmer_utf8.c" instead of
  24 "libstemmer.c".
  25
  26 For convenience "mkinc.mak" is a makefile fragment listing the source files and
  27 header files used to compile the standard version of the library.
  28 "mkinc_utf8.mak" is a comparable makefile fragment listing just the source
  29 files for the UTF-8 only version of the library.
  30
  31
  32 Using the library
  33 =================
  34
  35 The library provides a simple C API.  Essentially, a new stemmer can
  36 be obtained by using "sb_stemmer_new".  "sb_stemmer_stem" is then
  37 used to stem a word, "sb_stemmer_length" returns the stemmed
  38 length of the last word processed, and "sb_stemmer_delete" is
  39 used to delete a stemmer.
  40
  41 Creating a stemmer is a relatively expensive operation - the expected
  42 usage pattern is that a new stemmer is created when needed, used
  43 to stem many words, and deleted after some time.
  44
  45 Stemmers are re-entrant, but not threadsafe.  In other words, if
  46 you wish to access the same stemmer object from multiple threads,
  47 you must ensure that all access is protected by a mutex or similar
  48 device.
  49
  50 libstemmer does not currently incorporate any mechanism for caching the results
  51 of stemming operations.  Such caching can greatly increase the performance of a
  52 stemmer under certain situations, so suitable patches will be considered for
  53 inclusion.
  54
  55 The standard libstemmer sources contain an algorithm for each of the supported
  56 languages.  The algorithm may be selected using the english name of the
  57 language, or using the 2 or 3 letter ISO 639 language codes.  In addition,
  58 the traditional "Porter" stemming algorithm for english is included for
  59 backwards compatibility purposes, but we recommend use of the "English"
  60 stemmer in preference for new projects.
  61
  62 (Some minor algorithms which are included only as curiosities in the snowball
  63 website, such as the Lovins stemmer and the Kraaij Pohlmann stemmer, are not
  64 included in the standard libstemmer sources.  These are not really supported by
  65 the snowball project, but it would be possible to compile a modified libstemmer
  66 library containing these if desired.)
  67
  68
  69 The stemwords example
  70 =====================
  71
  72 The stemwords example program allows you to run any of the stemmers
  73 compiled into the libstemmer library on a sample vocabulary.  For
  74 details on how to use it, run it with the "-h" command line option.
  75
  76
  77 Using the library in a larger system
  78 ====================================
  79
  80 If you are incorporating the library into the build system of a larger
  81 program, I recommend copying the unpacked tarball without modification into
  82 a subdirectory of the sources of your program.  Future versions of the
  83 library are intended to keep the same structure, so this will keep the
  84 work required to move to a new version of the library to a minimum.
  85
  86 As an additional convenience, the list of source and header files used
  87 in the library is detailed in mkinc.mak - a file which is in a suitable
  88 format for inclusion by a Makefile.  By including this file in your build
  89 system, you can link the snowball system into your program with a few
  90 extra rules.
  91