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 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 and George Ferguson . See the start of the source files for further copyright information. - Paul Kendall 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 - added name completion code from imoviedb Edwin Cramer Dave Hill Col Needham Philippe Queinnec - name completion code in imoviedb Jon Reeves Claus Schotten Achim Laufenberg COPYRIGHT --------- Xregal is copyright 1996-1999 by Lachlan Wetherall E-Mail: lachlan@compsys.com.au WWW: http://users.hunterlink.net.au/~dglw