* The first time you compile on a new machine, you probably want to read these
  notes... at least as far as "Problems..."

Compiling
=========

* Use -DASCIITRACE, -DWIDINBLOCk and -g the first time round (see Makefile).
  Then run the first tests (see test/README).  If that's all OK, you can do a
  make clean, and then make with -UASCIITRACE -UWIDINBLOCK and -Olots (on
  SunOS -O4 works just fine and gives a noticeable improvement over -O).

* You should only need to edit the top-level Makefile and "h/globals.h";
  there is no need to edit other Makefiles.  On some systems you might end up
  editing menu/Makefile to work around curses problems, e.g. on Ultrix, but
  this is fairly rare.

* lqtext [sic, no hyphen] is a curses(3) or curses(3X) front end that uses
  system() to fire up lqshow [and/or lqkwik in a future version].  It and
  lqshow use curses.  If you have SystemV Curses, use it by defining CURSESX
  in Makefile.  It's a big win.  On SunOS you can use /usr/5bin/cc, together
  with -I/usr/5include and -L/usr/5lib, if it's all there.  If you end up
  using the BSD curses package, there will be some minor messiness to do
  with moving and resizing windows in lq-text, and the line-drawing will use
  =, + and | instead of the 8-bit extended PC character set, if you have it,
  but that's all.  I find that lqtext tends not to work in an xterm on SunOS
  if I used /usr/5bin/cc - the line drawing all goes away, because the
  characters aren't there.

* when it's all made, make a directory somewhere where there's space, and
  copy Sample/* into it.  Edit the two files (README and CommonWords), and
  then set LQTExTDIR to the directory containing them:
	mkdir /usr/spool/index
	cp Sample/* /usr/spool/index

	LQTEXTDIR=/usr/spool/index
	export LQTEXTDIR
	# or in csh
	setenv LQTEXTDIR /usr/spool/index

  Then index some files, e.g.:
	find news/comp -type f -print | lqaddfile -t3 -f - -w 300000

* when you're happy with it, send mail to lee@sq.com with "lq-text port" in
  the Subject: line.  See src/newport for a template message...  In this way,
  I am able to help other peopile porting to the same machine.

* if you had problems compiling or running lq-text, read on...

Problems
========

* lq-text uses both Unix file I/O and C stdio, although it doesn't usually
  mix them on the same file descriptor; the only exception is in
  GetFilterType(), which tries to determine the type of a file, and uses
  open() and read(), resorting to popen() for compressed files.

* lqaddfile uses popen() to exec a filter for reading/indexing mail folders,
  usenet articles and C input files.  Text files are read directly.
  TODO: add code to check magic numbers.

* lq-text uses a clone of, or derivative of, dbm(3) - ndbm(3), sdbm(3L),
  bsdhash(3L) (BSD only), or db(3) (4.4 BSD).  This is a dynamic hashing
  package, a basic algorithm described by Knuth.  The idea is to use a
  hashing scheme that is reasonably fast at insertion and exraordinarily
  fast on retrieval - it can retrieve any piece of data in two file system
  accesses.  There are papers on the algorithms in the various
  subdirectories of lq-text/src if they're included in your distribution.
  Of all of these packages, sdbm is the most portable, db ad bsdhash are the
  fastest, and dbm is very much a last resort.
  The most important thing when doing a new port is to check that the dbm
  library you're using works correctly.  Lq-text relies heavily on this.
  You can use test/dbmtry to do this.  Try
	dbmtry 5000
	dbmtry 7000
  which may take a while, and should be silent (TODO: make it say OK!).
  If you got a core dump second time round and you are using ozmahash or a
  copy of bsdhash, db, dynahash or hash that you didn't get from me:
  * check endian.h, and there may also be a copy of that in lq-text/src/h,
    in which case the two must be identical!
  * in ndbm.c, make sure that ffactor is initialised to a large number - I
    use 256, but anything dramatically bigger than the default 4 will do.
    In the copy in the distribution I have done this.  It makes about a
    factor of two performance difference...
  If you got lots of messages about data being wrong, the chances are that
  your system has a bcopy(3) (BSD's version of memcpy(3)) that does not
  handle overlapping regions.  There's a test for this in test/bcopy.c, or,
  if not, there's a bcopy() in liblqtext that can be compiled with an ifdef
  to make it do tests.  Do NOT use -Dbcopy=memcpy, because (1) they take
  arguments in a different order (the first two are swapped), and (2)
  memcopy() does not handle overlapping regions of memory, and bcopy() does.
  Well, it's supposed to, anyway.

  If you got no errors, you're fine!

* The code does pointer arithmetic, but does not assume that
	sizeof(int) == sizeof(char *)
  It _does_ assume that you can use an unsigned long as an index into a file
  with lseek(2).  If you are ona 286 or a 386 with mixed model, make sure
  that sizeof(unsigned long) == 4 (write a program to do this if you are not
  sure).

* The low/level I/O may do extra calls to lseek(), depending on compile-time
  options.  On most systems lseek(2) is very fast, as it doesn't do very
  much.  At worst, this is a slight speed loss.

* Most of the bug reports for lq-test 1.10 were because the ndbm or "ozmahash"
  (later renamed "bsdhash") wasn't installed correctly.  It was quite tricky,
  so I have added code to the top-level Makefile to check it...  If you had
  any problems whatsoever with bsdhash, try using sdbm instead.
  The most common problem was:
  * lqaddfile dumps core the second time you index something
    This is almost certainly a byte order problem, due to not editing endian.h
    or to having two different definitions of endian.h, one in src/h and one
    in src/ozmahash/endian.h  You have been warned :-)

  * several people said that ndbm.h wasn't found.  It was in a subdirectory,
    either ozmahash.h or sdbm.h depending on the version in use.  That was
    my fault for not making the Makefile copy it.  The current version uses
    -I instead.

Anything else - send me mail at lee@sq.com with "lq-text problem" in the
Subject line.  I generally try and reply to mail the same day.
Do check src/h/Revision.h and tell me what version of lq-text you are using!

Lee
lee@sq.com  Liam Quin  The barefoot programmer...

