XREGAL 1.41
-----------
Xregal is the X11 interface to the Internet Movie Database when it is installed
locally on a Unix system.

Why xregal? The name is in appreciation of the Regal Cinema in Birmingham 
Gardens, near where I live.  The Regal is the only local independent suburban 
cinema in Newcastle, Australia that survived the video age and continues to 
operate. I lived next door to it for a couple of years and saw many fine 
movies there.



INSTALLATION
------------
Xregal makes use of Col Needham's movie database package.  It is essential
that you set up his package and ensure that it is working first before
trying to set up xregal.  If you want xregal to have name completion
abilities, then you will also need to install Philippe Queinnec's imoviedb
package.  Xregal-1.41 is designed to work with version 3.7 of moviedb, 
and version 2.4 of imoviedb. Xregal may work with other versions of these 
packages, but it has not been tested and no guarantees are made.

Both moviedb and imoviedb packages should be available at the same location 
from which you obtained xregal, or try:

    ftp://uiarchive.cso.uiuc.edu/pub/info/imdb/tools


Once you have set up the database you can install xregal by doing the following:

1. Compile the moviedb package by doing 'make compile'.

2. If you are going to use name completion, compile the imoviedb package.

3. Untar the source files into a subdirectory where the moviedb package is 
   installed.  e.g. if the moviedb package is located in /usr/src/moviedb-3.7
   then untar xregal into /usr/src/moviedb-3.7/xregal.

4. Make any necessary changes to the Imakefile.  The only changes you might
   want to make are:
      * set BINDIR to the directory where you want xregal installed 
       (the default location is /usr/local/bin)
      * set DBDIR to the directory where the movie database files are stored
      * set IMDBSITE to point to your local IMDB web site
      * uncomment the WantNameCompletion macro in order to compile xregal
        with name completion abilities

5. Run 'xmkmf' to produce the Makefile

6. Run 'make' to compile.

7. Run 'make install' to copy the executable to its final destination.

8. If you want to make any changes to the default settings, edit 'XRegal'
   and manually copy it to the directory where application resource
   files are stored, or set the appropriate resources in your .Xresource file.


USING XREGAL
------------
Using xregal is very simple.  

* You can either search for a person's name or a movie title. 

* When searching for a name or title it is much faster to specify
  an exact search.  

  NOTE: When doing a substring search on a person's name, it is often faster
        to search all the lists rather than selected lists. This is because 
        searching specific lists requires extra file lookups to see if the 
        person matches the category.

* Names can be specified either in the form "Firstname Lastname" or 
  "Lastname, Firstname".  

* Titles that begin with 'The' or 'A' can be specified in either form also. 
  e.g. "The Firm" and "Firm, The" are acceptable.

* Case is insignificant in searches.

* If name completion is enabled (via the command line parameter or X resource)
  then xregal will read in a database of names and titles.  
  When entering a persons name or a movie title into the search dialog, you can
  enter the first part of the name then press TAB to try and match the 
  remainder.  If there is only one match the remainder of the name will be 
  filled in.  If there is more than one match (but less than 200 matches) a 
  popup list will be displayed from which you can choose a name.  If there are
  more than 200 matches, an alert box will popup.

  Note 1: Name completion on a persons name only works on the surname, and
          name completion on a movie title requires you to ignore "The" or "A"
          at the start of a movie title.
  Note 2: The loading of the completion data can be sped up (at the cost of
          extra disk space) by running the cgencompl utility available in
          the imoviedb package.  The extra disk space required can be reduced
          by gzipping the files titles.completion and names.completion.
          section of this file for details.)
  Note 3: The time at which the name/title completion database is read in can 
          be altered with the nameCompletion resource.

* Search History: For each of the search dialogs (name, movie, character name) 
  pressing the Up and Down cursor keys will allow you to recall previous 
  search strings.

* Searching on a movie title will automatically search for TV programs of the
  same name.  If you know the title refers to a TV program you can speed
  the search by enclosing the name in " quotes.

* Where there are multiple movies with the same name, a particular movie
  can be identified by appending the year enclosed in brackets to the search 
  term. e.g. "Sabrina (1995)"

* Any text that is underlined is a hyperlink. Clicking on the hyperlink will
  initiate a search on the hyperlink text.

Keyboard accelerators:

 Key            Action
 ---            ------
 T              popup the 'Title search' dialog box
 N              popup the 'Name search' dialog box
 C              popup the 'Character name search' dialog box
 G              popup the 'Genre search' dialog box
 K              popup the 'Keyword search' dialog box
 S              popup the 'Save to file' dialog box
 F3             popup the 'Find' dialog box
 B              move back to previous display (if it exists)
 F              move forward to the next screen (if it exists)
 H              popup the history list
 Up             scroll up one line
 Down           scroll down one line
 Left           scroll left 80 pixels
 Right          scroll right 80 pixels
 PageUp         scroll up one page
 PageDown       scroll down one page
 -              scroll up one page
 Space          scroll down one page
 Ctrl-PageUp    move to top of display
 Ctrl-PageDown  move to bottom of display
 Q              exit xregal
 Alt-X          exit xregal

The main window can also be scrolled by clicking and dragging the middle
mouse button.



COMMAND LINE OPTIONS
--------------------

-movie moviename   Search for the named movie.  (If the movie title is more than
                   one word, enclose the title in " quotes.)

-person name       Search for the named person - all the various lists will be
                   searched for matches.  (If the person's name is more than
                   one word, enclose the name in " quotes.)

Each of the following options are also settable via a resource. See the XRegal
file for details.

-nopcbar           Disables the display of a percentage bar indicating progress
                   of a database lookup. 

-casttab N         The integer value N specifies how many pixels across the
                   page that the character names should be displayed in
                   cast lists.  This option may be useful if you are using a
                   font larger than the default font. The default value is 200.

-chartab N         The integer value N specifies how many pixels across the
                   page that the character names should be displayed in
                   filmographies.  If the value is 0, then the character name
                   is simply displayed in square brackets immediately after
                   the movie name. The default value is 0.

-techtab N         The integer value N specifies how many pixels across the
                   page that technical data should be displayed in
                   filmographies. The default value is 120.

-quotetab N        The integer value N specifies how many pixels across the
                   page that the text of quotations should be displayed.
                   The default value is 50.

-hangingIndent N   The integer value N specifies by how many pixels a hanging
                   paragraph should be indented.  Hanging paragraphs are used
                   for entries that usually occupy a single line.
                   The default value is 40.

-substringMax N    When doing a substring search, the search will be aborted
                   after N matching items have been found.  The default value
                   is 500. 

-historyMax N      Limits the number of history screens that will be rememberd
                   to N.  If N is 0, the history mecahnism will be disabled
                   completely. The default value is 25. 

-alpha             Display filmographies in alphabetic order, rather than
                   year order.

-completion off|on|whenNeeded
                  The value of "off" means that name completion will not be 
                  available. A value of "on" means that the name completion 
                  data files will be loaded when xregal starts.  A value of
                  "whenNeeded" means that the  name completion data files will 
                  be loaded when they are first needed. i.e. when the user 
                  first presses TAB. The default value is "whenNeeded".

-laserDisc off|on  Disable/enable the lookup and display of laserdisc 
                   information.  The default is 'on'.

-imdbSite          Specify the IMDB web site to be used when displaying the
                   URL of a page.  The default is NULL, which means that the
                   value of IMDBSITE specified at compile time will be used.



CUSTOMIZATION
-------------
There are a number of parameters such as colors, fonts and key bindings that 
may be altered by specifying X11 resources.  The details of these resources 
are contained in the file 'XRegal'.  Note that the xregal binary contains 
default resources and thus the application defaults file 'XRegal' is required 
only if you wish to change the defaults.



DESIGN PHILOSOPHY
-----------------
* Xregal does not require an application defaults file to run correctly.  All
  necessary default resources are encoded within the binary executable.
* Xregal does not require any commercial widget set (such as Motif).
* Xregal is designed to be usable even on a monochrome screen.  If you want
  a fancy color scheme, you can adjust colors using X resources. (One of my pet
  hates is fancy graphical programs that look disgusting on a monochrome
  screen, or worse, are unusable because of the color mappings.)



WIDGETS
-------
Xregal contains seven custom widgets - CheckBox, LinkText, LinkView, RadioBtn, 
PcBar, Mlabel and FChooser.  The source files for all except the LinkView and
FChooser widgets are actually the *.w files which then get converted to 
.c and .h files by the 'wbuild' widget builder (version 3.0) by Bert Bos.  
You do not need wbuild unless you make modifications to the .w files.  
The wbuild package is available from:

ftp://ftp.let.rug.nl/pub/FWF



LICENSE
-------
I'll try to keep this as plain as possible...

* You may use this program without charge.
* You may freely distribute this program providing that this README file
  is distributed with it.
* You may make modifications to this program.
* You may *not* distribute modified versions of this program and still call it
  'xregal' without prior permission from the author.
* You may not make a profit out of this program without prior permission
  from the author.
* If you like this program, please send a postcard to me at this address:
        Lachlan Wetherall
        18 Lester Pde
        North Lambton NSW 2299
        AUSTRALIA
  or just e-mail a friendly message to lachlan@compsys.com.au.

      ***************************************************************
      *  Please note Col Needham's package is covered under a       *
      *  different license, in particular, your attention is drawn  *
      *  to the fact that the package and associated data MUST NOT  *
      *  be distributed on CD-ROM.                                  *
      ***************************************************************



TO DO
-----
* Provide online help.
* Sort the output when multiple movies are found
* Provide options for specifying what data to include.
* Graphical ratings.
* Genre search
  - ability to specify multiple keywords
  - implement custom list widget with text entry box 
* Option to view movies by year/ratings etc.
* Option to search for collaborations.
* Be able to specify sorting order (alphabetic, by year, by rating etc.)
  while running xregal.
* Make all labels/messages/headings settable by resources to facilitate
  international use.
* Name completion
  - display the progress in loading the names array on the percentage bar
    rather than on stdout.
* Fix up name substring searches to enable searching on aliases?
* Put in hyperlinks from awards to the award key page.
* Implement an 'additions interface' to format data ready for mailing to the
  IMDB mail server?
* In the 'Save to file' dialog, allow other file types such as LaTeX, 
  postscript, HTML, SGML, RTF, Sanskrit ...

Note: This list was compiled back in the days before I had a full time job
and children.  It's unlikely these things will ever get done, unless you e-mail
me and specifically request it or if you make the changes yourself and send me
the source code.



BUGS
----
* When resizing the window, the top position of the display may be be changed
  due to the effects of word wrapping.

* Sometimes a hypertext link does not point to valid data.  More often than not
  this is not a bug, but caused by an error or omission in the original 
  database lists.

If you find any other bugs please check the xregal home page
(http://users.hunterlink.net.au/~dglw/xregal/xregal.html) to 
see if the bug has already been corrected.  Also try to check if the bug is
caused by an error in the actual data. If you find a new bug, send email to me 
at lachlan@compsys.com.au and I'll fix it up.  Where it's relevant, 
please include in the bug report what page of data (movie title or 
person's name) elicited the bug.

I would also appreciate people trying out the development versions of xregal 
available from the xregal home page and reporting any bugs back to me.

Anybody who submits a bug report or makes a suggestion which gets incorporated
into xregal will be added to the "Acknowledgements" section of this file.
If you don't want your name added, please make that clear when you send me 
e-mail.



LIMITATIONS
-----------
* Text does not autowrap in the following categories:
    - soundtracks
    - crazy credits
    - agents address
  This is because the text data in these categories is often line-oriented
  and assumes that there will be no wrapping.

* The output from a single query can be paginated up to a maximum of 25 pages.

* A substring search on a person's name in a selected list will not match 
  against aliases.  Other substring searches will match against aliases, 
  however the display will show only the alias name, not the canonical name.

* When looking up all the movies in a particular genre, A.K.A.'s are shown only
  if the category contains less than 200 movies.  For large lists checking
  for A.K.A.'s is too time consuming.

* Within a page, the maximum search string size is 255 characters.



ACKNOWLEDGMENTS
---------------
My thanks to:
- All who have contributed to the Internet Movie Database in any way.
- Bert Bos <bert@w3.org> for writing wbuild which makes widget writing so easy.
  I also have used a modified version of Bert's label widget from the
  Free Widget Foundation.
- The file chooser widget is a slight modification of the FChooser widget
  from the Free Widget Foundation collection. It was written by Brian Totty 
  <totty@cs.uiuc.edu> and George Ferguson <ferguson@cs.rochester.edu>.  
  See the start of the source files for further copyright information.
- Paul Kendall <paul@kcbbs.gen.nz> wrote the ArticleText widget in the
  Free Widget Foundation collection from which I borrowed many ideas in the
  writing of the LinkText widget.  (See http://www.let.rug.nl/FWF/)
- The following people have contributed suggestions, bug reports, fixes
  and additional features:

      Paolo Brutti <gi0570@rh0015.roma.tlsoft.it> 
        - added name completion code from imoviedb
      Edwin Cramer <ecramer@wirehub.nl>
      Dave Hill <ddhill@zk3.dec.com>
      Col Needham <cn@imdb.com>
      Philippe Queinnec <Philippe.Queinnec@enseeiht.fr>
         - name completion code in imoviedb
      Jon Reeves <jreeves@imdb.com>
      Claus Schotten <schotten@ert.rwth-aachen.de>
      Achim Laufenberg <Joachim.Laufenberg@home.ivm.de>


COPYRIGHT
---------
Xregal is copyright 1996-1999 by Lachlan Wetherall 

E-Mail: lachlan@compsys.com.au
WWW:    http://users.hunterlink.net.au/~dglw
