README LUALA
============

Introduction
============

LUALA is an acronym for LUcene Application LAyer. It is an intermediate
level API for document indexing and searching. It uses the low-level
API of Lucene (see http://jakarta.apache.org/lucene).

Besides Lucene, LUALA uses a few other freely available packages. See
the section LICENSE for details.

LUALA includes three sample application. A command-line indexer, a
command-line searcher, and a GUI-searcher. These are suitable for
direct use.


DISCLAIMER
==========

LUALA is released under the GNU LESSER GENERAL PUBLIC LICENSE, Version 2.1,
see the file COPYING.LESSER.
The licenses of included packages differ, but are less restrictive than
the LGPL.

Hopefully, the acronym is complicated enough to prevent any name-clash
with existing projects.
There is however a town in Malaysia named Luala and there is a vase from
LSA-International called Luala. This project has nothing to do with both
entities.


LICENSE
=======

The proliferation of various open-source licenses makes it quite difficult
for application-assemblers to pick a suitable license. The packages used
to build LUALA and their corresponding licenses are:

Lucene:      COPYING.Apache (The Apache Software License, Version 1.1)
             http://jakarta.apache.org/lucene
PDFBox:      COPYING.PDFBox (a BSD-type license)
             http://www.pdfbox.org
Log4j:       COPYING.Apache (The Apache Software License, Version 1.1)
             http://jakarta.apache.org/log4j/
Java-Getopt: COPYING.LIB (GNU LIBRARY GENERAL PUBLIC LICENSE Version 2)
             http://www.urbanophile.com/arenn/


COMPILATION
===========

To compile (and use) LUALA, you need two packages. The LUALA source-code
in an archive named luala-src-version.tar.bz2, and the supporting
libraries in an archive named luala-extlib-version.tar.bz2. Note that the
version-numbers need not be equal, the extlib-archive is only updated as
needed. Just fetch the lib-archive with the highest available
version-number. You should unpack the extlib-archive within the
luala-basedirectory:

> tar -xvjf luala-src-version.tar.bz2 -C ~/src
> tar -xvjf luala-extlib-version.tar.bz2 -C ~/src/luala-version

You need ant to compile and build LUALA. Just run

> ant lib

to create the library jar. If you want to build and use the sample
applications, run

> ant deploy

This will create a standalone, all-in-one jar-file with all necessary
library-jars and the applications included. You will find the jar-file
together with some useful command-scripts in the deploy subdirectory.

Use

> ant -projecthelp

for an overview of additional targets (or have a look at the build.xml).


RUNNING
=======

Create an index with

> cmdindexer -s sourceDir -i indexDir [-u]

cmdindexer also accepts filenames from stdin, so you could also run

> find sourceDir -type f | cmdindexer -i indexDir

If this command looks strange to you, switch to a real OS ;-)
Use the -u option to update an existing index.

To query the index, run

> cmdsearcher -i indexDir [ -p path-prefix ] [-H] query

If you prefer the GUI-version, try

> guisearcher -i indexDir -b browser [ -p path-prefix ] start-page

All commands also accept the -h command-line option. This option will
print a short usage message and exit.



BUGS, CONTRIBUTIONS, NOTES
==========================

If you think you found a bug or want to contribute some code please drop 
me a note. Note that I check my mail only once or twice a week, so please
be patient.

(c) Bernhard Bablok, 2003-2004
mail@bablokb.de
http://www.bablokb.de