            Interactive and completion access to the
            Internet Movie Database names and titles

By Philippe Queinnec <queinnec@enseeiht.fr> or <queinnec@dgac.fr>
Hacked around April and May 1994, rehacked in March 95, July 1996 and Oct 1996.

This code is copyrighted Philippe Queinnec.

This code is part of the Internet Movie Database distribution, but may be
distributed independently. This code is under the same license as the
Internet Movie Database distribution. Due to excessive paranoia, this
license is also distributed with imoviedb, in the file LICENSE.

See file INSTALL to find how to compile it.
See also FAST LOADING below.


MAIN CHANGES
------------
 Since V2.3:
    - year-2000 bug.

 Since V2.2:
    - iso 8859-1 support (see ISO-8859-1 below)

 Since V2.1:
   - INSTALLATION HAS CHANGED.   <------ *****BEWARE*****
   - support for mmap (yet another speed up!)
   - support for zlib (--with-zlib)

 Since V2.0:
   - Add cgencompl, and use pre-generated data, to speed up loading.
     See FAST LOADING below.

 Since V1.x:
   - Memory requirements have been reduced by a factor between 3 and 5!
     Loading speed has not significantly changed, except when loading a lot
     of different bases with clist (clist -acr -acs -dir), where it's a
     little slower.
   - new options -keepyear, -from year, -to year.
   - manual pages.



WHAT IS imoviedb ?
------------------

Don't you think that finding the exact title of a movie is far too hard, or
far too slow? Should the year be included in the name or not? Is it 'remains
of the day' or 'the remains of the day'? Do you really know how to spell
'Balint, Eszter' or 'kieslowski, krzysztof' ?

Here are two programs that try to deal with this problem. Both use readline
to input strings and provide completion via a sorted array which holds names
grabbed from the databases.

ctitle is used to complete movie titles. It initially loads all the titles
found in the databases.
Type in a name, use <TAB> for completion (two <TAB> to get a list of
possible completions), and <ENTER> to run 'title -full -t <name>'.
For instance try `ctitle' and type: man who k<TAB><TAB>

clist provides completions for persons. Used with clist <base1> <base2>...
For instance: `clist -acr -acs' loads the names from the actors and
actresses databases (it uses the same options as list).
If no option are specified, it loads all the persons found in the databases.
Type in a name, use <TAB> for completion (two <TAB> to get a list of
possible completions), and <ENTER> to run 'list -full -name <name>'.
For instance, try `clist -dir' and type: hit<TAB><TAB>
then type: hitc<TAB>

clistall is similar to ctitle but calls listall instead of title.

cltrace is similar to list but calls ltrace instead of list.

cquery is a common interface to clist, ctitle, clistall and cltrace. As it
loads the name databases and the title databases, it requires a lot of
memory.

As a bonus with the completion, you also get all readline capabilities, that
is line editing (with emacs or vi keybindings) and history.

WHERE GOES THE OUTPUT: you have four ways to specify the output.
 - don't do anything: output is piped into more or less based on the
   compilation configuration.
 - use PAGER environment variable. It must be a valid command *or* command
   line. If PAGER is multi-word, sh is used to execute it. This means that
   PAGER = 'tee /tmp/toto |more' or 'cat >/dev/null' works.
 - use -o option: "clist -o foo" outputs into the file foo.
   "clist -o !foo" or "clist -o |foo" outputs into the command foo (as
   previously, foo may be multi-word). For instance:
   clist -o '|tee /dev/tty | title2tex >/tmp/foo.tex'
 - interactively: after entering the name, add '>/tmp/foo' or '>>/tmp/bar' or
   '|lpr' (without the quotes of course). You even have filename completion
   after >, >> or |.
   For instance, after clist -dir:
   Enter name (quit to quit): hitchcock, alfred |lpr -h
   Enter name (quit to quit): mankiewicz, tom >/tmp/foo
   Enter name (quit to quit): mankiewicz, tom >/tmp/foo
   Enter name (quit to quit): mankiewicz, joseph l. >>/tmp/foo


FAST LOADING
  To speed up cquery, clist and ctitle loading, the program
  cgencompl can generate special databases for the titles and names
  lists. cgencompl is installed in the etc directory. Run

      cgencompl -all

  to generate both databases. Loading will be a lot faster (and use 10%
  less memory). cgencompl generates two files titles.completion and
  names.completion in the dbs. These files are approximately as big as the
  corresponding key files (around 10Mb).

  Using cgencompl is highly adviced: cquery loading time has dropped from
  more than 14 seconds to 2 seconds on my SparcStation 5.

  Moreover, if your system supports a working mmap, you get yet another
  speed-up (less than one second on my SS5). The slowest your computer, the
  more you win with mmap.

  If you have the zlib library, you can compress the .completion files, but
  then, mmap cannot be used. Gzipped completion files are approximatively
  3.2Mb big.

TIMING: just so you believe me, here are the timings and memory usage for
cquery on a slow Sun4 ELC reading moviedb databases over NFS. All times are
for cquery.

  gzipped .key:        44.930u 8.580s 0:58.81 90.9% 0+1726k 457+214io 508pf+0w
  normal .key:         29.090u 6.880s 0:42.05 85.5% 0+2409k 1268+0io 1342pf+0w
  gzipped .completion: 15.180u 2.430s 0:18.03 97.6% 0+2463k 60+0io 68pf+0w
  normal .completion:   0.680u 6.180s 0:13.93 49.2% 0+1946k 1140+0io 1210pf+0w
  mmap .completion:     1.720u 1.190s 0:02.96 98.3% 0+544k 0+0io 0pf+0w

Guess which solution I prefer ?


REQUIREMENTS
------------
 - an ANSI compiler

 - the readline library, version 2.0 (or higher). readline is available on
   ftp://ftp.gnu.org/pub/gnu/readline (or mirrors).
   readline 2.0 uses a configure script (see also readline-2.0-patch, no
   longer necessary with 2.2 or higher)
   readline-1.1 is no longer a good choice, as it doesn't support 8-bits
   characters, and I haven't bothered to have mycomplete.c compile with it. If
   you really need it, just ask me.

 - moviedb 3.3 (or higher) already installed (versions < 3.3 don't support
   the new iso-8859-1 coding).

 - a display which accept iso-8859-1 encoding.

 - Some memory. At that time (October 1996):
    `ctitle' requires 2Mb,
    `clist -dir' requires 0.6Mb, `clist -acr' requires 3.5Mb and 'clist' (all
    databases) requires 6Mb.
    'cquery' requires 8.0Mb.
   With mmap, memory is allocated on demand, and I rarely go over 3Mo.


ISO-8859-1 support
------------------

Since March 1997, the databases are now using accented characters in
iso-8859-1 enconding. imoviedb tries to handle them as nicely as possible,
which means that they are ignored in completion handling, but are printed
when present. This works only with readline-2, as readline-1.1 always
strips the eighth bit. If you use a iso-8859-1 font or display, everything
should work fine. If you prefer that readline doesn't output eight-bit
characters, add the following in your ~/.inputrc :

$if imoviedb
# if off, strip eighth bit when reading.
set meta-flag off
set convert-meta on
set output-meta off
$endif

If you are using `less', imoviedb automatically inserts LESSCHARSET=latin1
in your environment, except if LESSCHARSET is already set.


WHERE IS THE NEW VERSION?
-------------------------

The newest version cannot be found anywhere any longer, but I can provide it
by e-mail to any enquiring people.

A working version (that is, a version tested by at least two persons) is in
the standard Internet Movie Database archives, for instance in
ftp://uiarchive.cso.uiuc.edu/pub/info/imdb/tools. See
http://www.imdb.com/interfaces for other sites.




ADVERTISING
-----------

Please have a look at moviedb2tex. There are two perl scripts which
translate output from list, title, ltrace, lguide or listall into LaTeX, in
order to get a pretty printing. It should be near imoviedb distribution.


THANKS
------
Thanks for various contributions or comments to:
Colin Needham <cn@imdb.com>
Paolo Brutti <gi0570@rh0015.roma.tlsoft.it>
Jon Reeves <reeves@imdb.com>
fjaccard@iprolink.ch (Francois Jaccard) 
Lachlan Wetherall <lwether@cs.newcastle.edu.au>
