Newsgroups: rec.arts.movies

MOVIE DATABASE SCRIPTS v2.3 PART I: Instructions
================================================

[Note: This package is now getting rather large. I am considering making
 future releases available via ftp only. If this will cause you any problems,
 please let me know.]

Welcome to the latest version of the database scripts. New features in this
release include:

 * a new improved 'mguide' script to generate a huge movie guide with entries
    grouped by title which now combines the movie ratings report data, the
     year of release and any alternative titles

 * support for the movies list in the 'lguide' and 'alist' script. The latter
    now allows you to find all the Oscar nominees/winners in a particular year.

 * a new script for users of my ratings report voting support scripts which
    sorts listed names by the no. of their films that you have seen.

Users of version 2.2 should see sections 17 and 18.

If you have been unable to use the scripts because of the amount of disk
space required, I have an alternate version adapted by Philippe Queinnec
which uses compressed database files - available via e-mail.

If you would like to receive updates in advance of their publication, send
me a mail message and I'll add you to the list of users.

Col

------------------------------------------------------------------------------
CONTENTS
========

PART I

1.  Instructions for New Users
     1.1  Creating the Database
     1.2  A Quick Guide to Searching
           1.2.1  list: Basic Options
           1.2.2  title: Basic Options
           1.2.3  More Advanced Options

2.  Instructions for Experienced Users
     2.1  Multiple Name Queries
     2.2  Multiple Title Queries
     2.3  Speeding up title
     2.4  Alternative Titles
     2.5  Easier title matching

3.  Movie Ratings Report
     3.1  Creating the ratings database
     3.2  Using the link to the report
     3.3  Title Formats

4.  Movies List
     4.1  Getting the list
     4.2  List options
     4.3  Title options

5.  Listall Script

6.  Mguide Script

7.  Lguide Script

8.  Ltrace Script
     8.1  Basic Options
     8.2  Year Options

9.  Lformat Script
     9.1  Database options
     9.2  Subset option
     9.3  Format options
     9.4  Output options
     9.5  Examples

10. Lindex Script
     10.1  Database Options
     10.2  Index Type Options
     10.3  Output Options
     10.4  Movie Ratings Report Options
     10.5  Year Options
     10.6  Miscellaneous Options
     10.7  Examples

11. Alist Script
     11.1  Database Options
     11.2  Search Options
     11.3  Output Options
     11.4  Year Options
     11.5  Examples

12. Configuring The Database
     12.1  Advanced gendb Options
           12.1.1 selective updating
           12.1.2 reducing the size of the databases
           12.1.3 the aka file
     12.2  Temporary files

13. Person Script
     13.1  Basic options
     13.2  Advanced options
     13.3  Multiple queries
     13.4  Year options

14. Mkballot Script

15. Akaprint Script

16. Ldebug Script
     16.1  Debugging Additions
     16.2  Debugging the movies list

17. Lseen Script
     17.1  Checking the votelog file
     17.2  Database Options
     17.3  Output Options
     17.4  Ratings Report Options
     17.5  Examples

18. Other Changes
     18.1  Install Script
     18.2  New Sort Order
     18.3  Mguide
     18.4  Lguide
     18.5  Alist

19. Notes

PART II

20. The Archive


------------------------------------------------------------------------------
1. INSTRUCTIONS FOR NEW USERS
=============================

There are now seven lists posted at regular intervals to r.a.movies (actors,
actresses, directors, dead, writers, composers and cinematographers).
The lists contain over 100,000 entries and cover more than 21,000 different
movies between them. I have written some Unix scripts to set-up an online movie 
database with tools to search for all the movies someone has been involved with
or all the people involved with particular movie. There are also scripts to 
extract other information from the database, including ratings of many movies 
via a link to the Movie Ratings Report. The programs are contained in a shell 
archive at the end of this message.

I have tried to structure these instructions so that you can start with just
the basic functionality and gradually work your way through to the more 
advanced features as you have time. Any suggestions on better ways to organize 
this file are welcome.

Note: If you run a script without any arguments, it will output a usage message
      indicating the options available. Also, example uses are listed in the 
      comments at the top of each script.

The following table gives details of list availability:

 List            | Last Post | Maintained by                        | Next Post
 ----------------|-----------|--------------------------------------|----------
 Composers       | 08/03/92  | Michel Hafner <hafner@ifi.unizh.ch>  | Nov wk 2
 Writers         | 09/18/92  | Andy Krieg <krieg@titan.med.ge.com>  | UNKNOWN
 Movies          | 09/25/92  | Michel Hafner <hafner@ifi.unizh.ch>  | FTP only
 Alt. Titles     | 09/25/92  | Michel Hafner <hafner@ifi.unizh.ch>  | FTP only
 Cinematographers| 09/25/92  | Michel Hafner <hafner@ifi.unizh.ch>  | December
 Actresses       | 10/05/92  | Andy Krieg <krieg@titan.med.ge.com>  | UNKNOWN
 Actors          | 10/09/92  | Col Needham <cn@otter.hpl.hp.com>    | Dec wk 1
 Directors       | 10/15/92  | Dave Knight <dknight@elm.sdd.trw.com>| November
 Dead            | 11/05/92  | Col Needham <cn@otter.hpl.hp.com>    | Jan wk 1
 ------------------------------------------------------------------------------

You do not need all seven lists to use the scripts. Copies of the lists
are available via anonymous FTP from boulder.colorado.edu [128.138.240.1] in
the directory pub/tv+movies/lists or from ftp.coe.montana.edu [192.31.215.240]
in pub/MOVIES.


1.1 Creating the databases
==========================

(1) Unpack the shell archive at the end of this message into a directory. If 
    you already have saved copies of the lists, unpack it in the same 
    directory, otherwise, create a new one. 

(2) Run the installation script simply by typing:

    linstall

    at the shell prompt. This will compile a few C programs that are used by
    the scripts to speed queries up.

(3) Place a copy of each list in a file as outlined below:

      List                  | File
      ----------------------|---------
      Actors List           | actors
      Actress List          | actress
      Directors List        | directs
      Dead List             | dead
      Writers List          | writers
      Composers List        | composers
      Cinematographers List | cine

    You should remove *all* headers and trailing lines from each file. All
    lines in the files should either be blank or of the form:

<name>                  <movie/tv>

    or:

                        <movie/tv>

(4) To create the databases, enter the following command at the shell prompt:

    gendb

    This will create seven database files (actors.dbs, actress.dbs, dead.dbs,
    writers.dbs, directs.dbs, composers.dbs and cine.dbs) corresponding to the 
    lists and a database of alternative titles (aka.dbs). You can browse these 
    files using your favourite editor. 

(5) Each time a new release of one of the lists is posted, strip off the 
    headers, save it to the appropriate file and re-run 'gendb'. 
    
(6) You can delete the original list files if you are short of disk space. See 
    section 12.1 (Advanced gendb Options) for details of how to make the update 
    process faster.


1.2 A Quick Guide to Searching
==============================

1.2.1 list: Basic options
-------------------------

To use the basic features of the 'list' script, use one of the following forms:

 *  list -a "<actor>"

    Lists all appearances by a particular actor or actress. For example,

    list -a "Biehn, Michael"
    list -a "Davis, Geena"
    list -a "Grant, Cary"

    The command is the same regardless of whether it is the actors, actress
    or dead list that you are searching.

 * list -d "<director>"

   List all movies directed by a particular director. For example,

   list -d "Hitchcock, Alfred"

 * list -w "<writer>"

   List all movies written by a particular writer. For example,

   list -w "Hecht, Ben"

 * list -c "<composer>"

   List all movies with music composed by a particular composer. For example,

   list -c "Herrmann, Bernard"

 * list -ph "<cinematographer>"

   List all movies photographed by a particular cinematographer. For example,

   list -ph "Toland, Gregg"

Please note that apart from case, an exact match is required in all the above 
examples. See section 1.2.3 (More Advanced Options) for details on searching 
for substrings. I recommend that you try the above commands a few times before 
moving on.


1.2.2 title: Basic Options
--------------------------

 * title -t "<title>"

   List all the cast, director, writers, composer and cinematographers of a 
   particular movie. The director is marked by a "(d)" after her/his name, 
   writers are marked with "(w)", composers by "(m)" and cinematographers by 
   "(ph)". For example,

     title -t "Terminator, The"

     title -t "Hunt for Red October, The"

   To search for a TV series, it has to be enclosed in single quotes. Example:

     title -t '"Twin Peaks"'


Once again apart from case, an exact match is required.


1.2.3 More Advanced Options
---------------------------

The following options are available on both 'list' and 'title' unless
otherwise stated.

 * -s  Allow partial match on names or titles. This option is 
       useful if you can't remember the precise spelling of a name. 
       Examples:

       list -s -d "Hitch"  searches for directors containing substring "Hitch"

       list -s -a "John"  searches for films with actors/actresses whose
                          names include the substring "John"

       title -s "Alien"   searches for people who worked on films whose titles
                          include "Alien"

       To see which entries have been matched, use "-r" in combination 
       with this option (see below).

 * -r  Raw mode. Output results of search in full and unsorted. This is 
       useful with -s when you want to know what entries have been 
       matched. Examples:

       list -r -s -d "Reiner"

       title -r -s -t "Star Trek"

 * -i  Pay attention to case in search. Examples:

       list -s -a "smith"
        -- search cast lists for appearances by people whose name contains
           the substring "smith"

       list -s -i -a "Smith"
        -- search cast lists for appearances by people whose name contains
           the substring "Smith". Note that this time only people whose name
           begins with "Smith" will be found because of the uppercase "S".

 * -m  Movies only. Removes TV-series information from results of a search.
       Example:

       list -m -d "Lynch, David"

       This option is not available on 'title'

 * -cat  Cat results. Uses 'cat' to display results instead of 'more'. Example:

       list -cat -a "Nicholson, Jack"

 * -noattr Do not display attribute values. The entries in the database are
	   stored in three fields - name, title and attributes. The attributes
	   field contains details about any award nominations/wins or, in the
	   case of the writers list, the type of contribution made to the
	   screenplay (novel, story etc.). This option causes the script not
	   to display the attributes in the results of a search. Example:

	   list -w "Chandler, Raymond" -noattr
      
Once you are familiar with how the scripts work, you can continue into the
section for experienced users below.

Also, see section 4.2 for details of how to sort the results of 'list' into 
chronological order.

-------------------------------------------------------------------------------
2. INSTRUCTIONS FOR EXPERIENCED USERS
=====================================

2.1 multiple name queries
=========================

There is no limit on the number of "-a" options in the same query. Examples:

  list -a "Hepburn, Katharine" -a "Tracy, Spencer"
   -- lists all movies in which Hepburn *and* Tracy co-starred

  list -a "Biehn, Michael" -a "Paxton, Bill" -a "Henriksen, Lance"
   -- lists all movies featuring all three of Biehn, Paxton & Henriksen

One "-d" option may also be included. Examples:

  list -d "Hitchcock, Alfred" -a "Grant, Cary"
   -- lists all Hitchcock movies featuring Cary Grant

  list -d "Hitchcock, Alfred" -a "Grant, Cary" -a "Bergman, Ingrid"
   -- lists all Hitchcock movies featuring both Grant & Bergman

Also, one of each of the other name searching options (-c/-w/-ph) may be 
included. 

All of the standard options (-m, -s, -cat, -r & -i) can be used as before with
one exception: The "-r" option can only be used when there is only one
search string. Example:

  list -r -a "Davis, Geena"
   -- this is still okay

  list -r -a "Davis, Geena" -a "Goldblum, Jeff"
   -- this is an invalid combination

Also, if you specify more than one name, the "-noattr" option is automatically
used.


2.2 multiple title queries
==========================

There is no limit on the number of "-t" options in the same query. When more
than one title is given, the script returns a list of people *common* to all
the movies. Example: to find out who was involved in *both* "Spellbound"
and "Notorious"

  title -t "Spellbound" -t "Notorious"

Bergman, Ingrid
Hecht, Ben (w)
Hitchcock, Alfred (d)

Note that when more than one title is specified, the director -> writers ->
composers -> cast ordering is lost. As with multiple name queries, all the
related options operate as before except that "-r" only works with one title.


2.3 speeding up title
=====================

Sometimes when using 'title' you might not be interested in searching some of
the databases. Several options are available to do this and they can speed
up the search considerably:

  -noacr    ignore actors database
  -noacs    ignore actresses database
  -nodead   ignore dead database
  -nocast   ignore cast databases (combines -noacr -noacs -nodead)
  -nodir    ignore directors database
  -nowrite  ignore writers database
  -nocomp   ignore composers database
  -nocine   ignore cinematographers database
  -nocrew   ignore crew databases (combines -nodir -nowrite -nocomp -nocine)

These options may be mixed in any combination.

Examples:

  title -t "Casablanca" -nocrew
    -- lists the cast of "Casablanca"

  title -t "Casablanca" -nocast
    -- lists the director, writers, composer & cinematographer

  title -t "Casablanca" -nocomp -nocine
    -- lists all information except composer and cinematographer

  title -t "Casablanca" -nocast -nocine -nowrite -nocomp
    -- lists just the director

2.4 alternative titles
======================

For a variety of reasons films are sometimes known by more than one title.
Alternative titles are represented on the lists by "(aka ...)", however they
are not stored in the database files created by 'gendb'. Instead, they are kept
separately in the alternative title database (aka.dbs). 

The -aka option can be used in combination with the title script to check for
an alternative title. For example, "Shoot to Kill" was released as 
"Deadly Pursuit" here in England:

  title -t "Deadly Pursuit"
    -- returns nothing

  title -t "Deadly Pursuit" -aka
    -- produces

       (aka Shoot to Kill)
       Spottiswoode, Roger (d)
       Alley, Kirstie
       Berenger, Tom
       Brown, Clancy
       Masur, Richard
       Poitier, Sidney

It is possible to customize the aka-database to suit particular languages.
Please contact me via e-mail for details.


2.5 Easier title matching
=========================

The titles on the lists need to uniquely identify a movie. In order to achieve
this, the maintainers have to add year-of-release information whenever a title
clash occurs, for example: "Fear (1946)" and "Fear (1988)". We also like to 
indicate when a movie has been made specifically for TV or video by tagging 
the titles with "(TV)" and "(V)" respectively. Since this information is part 
of the title field you need to specify it in order to get a match using the 
'title' script. The "-s" option on 'title' allows partial matches but often 
the results are a little too general, for example:

   title -t "Fear" -s -r 

returns about 200 entries covering movies such as "Cape Fear", "Journey Into
Fear" etc. The "-p" option will cause the script to match on the main
part of the title field only - year information and "(TV)" tags will be 
ignored. Note: it is still best to use "-r" with this option so that you
can see exactly which titles have been matched. Examples:

   title -t "Fear" -p -r

   title -t "Cape Fear" -p -r

-------------------------------------------------------------------------------
3. MOVIE RATINGS REPORT
=======================

Note: If you are not interested in the ratings report, the scripts will still
      work OK and you can skip this section.

3.1 Creating the ratings database
=================================

(1) Save the latest version of the Movie Ratings Report in a file called
    'ratings'. Note: there is no need to strip the headers from this file.

(2) To create the ratings database enter:

    gendb -mrr 

    at the shell prompt. This will create a database called 'ratings.dbs'.

Each time a new version of the report is published, repeat the above steps. 
The scripts only require the 'ratings.dbs' file so you can delete 'ratings' 
if you wish.

3.2 Using the link to the report
================================

There are three options to support the ratings report:

 -mrr  Movie Ratings Report. Takes each title produced by the search and adds 
       the ratings information. Examples:

       list -mrr -a "Biehn, Michael" 

       Produces:

      0000012210     152   6.8  Abyss, The
      0000012220     314   7.4  Aliens
                                China Rose (TV)
                                Coach
                                Deadly Intentions (TV)
                                Fan, The (1981)
                                Fire in the Sky, A (TV)
      0001121100     158   5.4  Grease
                                In a Shallow Grave
                                K2
      .0.022210.      35   5.8  Lords of Discipline, The
      03.13.0...      13   3.8  Navy Seals
                                Rampage (1988)
      000002200.      51   5.4  Seventh Sign, The
      0.00002310     269   7.6  Terminator, The
                                Zuma Beach (TV)

      NOTES
      -----
      A blank area before a title means that it is not yet on the Movie
      Ratings Report or alternatively, there is a slight difference in the
      title format between the list and the MRR. I have been working with
      the other list maintainers and Chuck to make our titles as consistent
      as possible. 

      Use of -mrr automatically switches on the -m (movies only) option, as 
      the MRR does not contain TV-series ratings.

      Further examples (without results):

      list -mrr -a "Keaton, Diane"

      list -mrr -a "Grant, Cary"

      list -mrr -d "Allen, Woody"


 -smrr Works exactly like -mrr except the results are sorted in descending 
       order by average rating (i.e. most highly rated film first).

       list -smrr -a "Biehn, Michael" 

       Produces:

      0.00002310     269   7.6  Terminator, The
      0000012220     314   7.4  Aliens
      0000012210     152   6.8  Abyss, The
      .0.022210.      35   5.8  Lords of Discipline, The
      0001121100     158   5.4  Grease
      000002200.      51   5.4  Seventh Sign, The
      03.13.0...      13   3.8  Navy Seals
                                China Rose (TV)
                                Coach
                                Deadly Intentions (TV)
                                Fan, The (1981)
                                Fire in the Sky, A (TV)
                                In a Shallow Grave
                                K2
                                Rampage (1988)
                                Zuma Beach (TV)

 -vmrr Works exactly like -mrr except the results are sorted in descending 
       order by number of votes (i.e. most voted for film first).

       list -vmrr -a "Biehn, Michael" 

       Produces:

      0000012220     314   7.4  Aliens
      0.00002310     269   7.6  Terminator, The
      0001121100     158   5.4  Grease
      0000012210     152   6.8  Abyss, The
      000002200.      51   5.4  Seventh Sign, The
      .0.022210.      35   5.8  Lords of Discipline, The
      03.13.0...      13   3.8  Navy Seals
                                China Rose (TV)
                                Coach
                                Deadly Intentions (TV)
                                Fan, The (1981)
                                Fire in the Sky, A (TV)
                                In a Shallow Grave
                                K2
                                Rampage (1988)
                                Zuma Beach (TV)

For details on the format of the Movie Ratings data and how to take part in 
the poll, see the section at the end of Chuck's weekly report.


3.3 Title Formats
=================

There are slight differences in title formats between the movie ratings report 
and the lists. This can cause some titles not to match properly. A new file 
(corrects.mrr) is now included in the scripts package. It consists of commands 
to convert titles from the ratings report into the list format. The 'gendb' 
script automatically applies the conversion whenever you update the ratings 
database.

-------------------------------------------------------------------------------
4. MOVIES LIST
==============

Michel Hafner has been working on a movies list which will be used to contain
information related to titles, for example the year of release and attributes 
such as best picture nominations/wins. The list currently contains the year 
information for around 18,000 of the 21,000 movies on the lists. Most of the
scripts can now sort their results into chronological order.

4.1 Getting the list
--------------------

At the moment the the list is only available from the ftp servers (see section 
1 for details). A compressed version is stored in the file movies.dbs.Z. To 
install the database you need to get this file from one of the servers, place 
it in the scripts directory and then type:

    uncompress movies.dbs.Z

to create the text file 'movies.dbs'. To ensure that the database is correctly 
sorted, please run:

    gendb -movie

The format of the database is:

    <title>|<year>|<attributes>

The attributes field is mainly empty at the moment, but will be expanded 
significantly in future releases. Michel will post a note to r.a.movies every
time a new version is uploaded. 

Just like the other lists, we welcome any additions/corrections to this list.
They should be in the same form as that of the database (see above) and mailed 
directly to Michel <hafner@ifi.unizh.ch>. See section 16.2 for more information.

[Note: Please make sure you strip out any headers or introductory text from
	the movies list before proceeding]

4.2 list options
----------------

There are two options to the 'list' script that enable it to use the list:

   -yr  Adds the year of release information to the results list and sorts
	in chronological order. Note: movies that are not yet in the titles
	database will be listed last. For details of how to increase the 
	coverage of your favourite star/director etc. on the titles list, see 
	section 16.2

  -yru  Adds the year of release information, but leaves the results list in
	alphabetical order.

Examples:

   list -a "Hurt, William" -yr

   list -d "Hitchcock, Alfred" -yr

   list -d "Lynch, David" -yru -m


4.3 title options
-----------------

   -yr  Displays the information from the movies list (year + attributes)
	for each title specified by "-t". Note: this does not currently work
	with partial matches ("-s").

Example:

   list -t "Rebecca" -yr


-------------------------------------------------------------------------------
5. LISTALL SCRIPT
=================

'listall' takes a movie title as an argument and for each cast member of 
that movie, lists all the other movies they have appeared in. The director's
other credits are also listed (name marked with "(d)" ) and similarly for
writers (name marked with "(w)"), composers (name marked with "(m)") and
cinematographers (name marked with "(ph)").

Example:

  listall "Abyss, The"

-------------------------------------------------------------------------------
6. MGUIDE SCRIPT
================

This script produces a 'title' style report on every movie covered by the 
lists (roughly 21,000 movies). The report is placed in a file called 
'movieguide' in the scripts directory. Note that the guide is extremely
large and I strongly recommend that you do not print it out - the lists are
changing all the time and the guide would be out of date within a couple of
weeks. It is very useful as an electronic reference though, particularly
if you have a number of 'title' queries you wish to process: simply load
the guide into your favourite editor and search for the titles you're 
interested in. On my system the guide takes just a few minutes to generate.

Options
-------

  -yr  adds year of release information

 -aka  lists any alternative titles

 -mrr  adds movie ratings report information

Example:

   mguide -yru -aka -mrr
    -- generates a movie guide combining all the information in the databases

Note: titles must match exactly across all the lists in order for the script
to correctly group all the people together. If you spot any mistakes please
let the apporiate list maintainer(s) know. 

-------------------------------------------------------------------------------
7. LGUIDE SCRIPT
================

This script works like 'mguide' except that it only looks for a subset of
titles which are in a specified file. I find this script really useful for
generating a little movie guide to accompany the TV schedules for the local 
movie channels. To use the script simply type the titles into a file, one on 
each line and enter:

 lguide -f <filename>

Options:

  -yr  adds year of release information

 -aka  lists any alternative titles

 -mrr  adds movie ratings report information

 -cat  use 'cat' to display results instead of 'more'


-------------------------------------------------------------------------------
8. LTRACE SCRIPT
================

This script displays all the information about each of the movies that someone
has worked on. The options are similar to those for 'list'.

8.1 Basic Options
=================

 ltrace -a <name>
  -- actor/actress search

 ltrace -d <director>
  -- director search

 ltrace -w <writer>
  -- writer search

 ltrace -c <composer>
  -- composer search

 ltrace -ph <cinematographer>
  -- cinematographer search

For example,

 ltrace -a "Grant, Cary"

finds the list of Cary Grant movies, then for each one calls 'title' to
get details of the co-stars, director, writers, cinematographer and composer.

8.2 Year Options
================

   -yr  Displays information from the movies list (year + attributes) for
	each movie the person has worked on. The results are sorted in 
	chronological order to give a filmography starting with their first
	(listed) movie. Titles not yet in the movies database will 
	appear last.

  -yru  Displays information from the movies list (year + attributes) for
	each movie the person has worked on, but leaves the filmography in
	alphabetical order.

    -m  Movies only, doesn't trace TV-series information.

Examples:

   ltrace -a "Hurt, William" -yr

   ltrace -d "Hitchcock, Alfred" -yr

-------------------------------------------------------------------------------
9. LFORMAT SCRIPT
=================

This script provides a number of features for formatting whole lists or
subsets of lists, combining the lists with the movies list or the movie 
ratings report. It replaces both the 'sublist' and 'yrformat' scripts in
the previous version. 

9.1 Database options
====================

These options specify which of the seven lists you would like to format and can
be combined in any order:

 -acr     actors list
 -acs     actresses list
 -dead    dead list
 -cast    combination of -acr -acs & -dead
 -dir     directors list
 -write   writers list
 -comp    composers list
 -cine    cinematographers list


9.2 Subset option
=================

 -f <file>  The default operation is to format all the entries from the 
	    selected databases. This option allows you to put a list of names
	    in a file (one per line) and the script will only operate on
	    the entries for those people.


9.3 Format Options
==================

 -yr    Adds the year of release information and sorts each person's entries
	into chronological order.

 -yru   Adds the year of release information, but leaves entries in
	alphabetical order.

 -mrr   Adds the information from the movie ratings report to each title.

 -smrr  Adds the information from the movie ratings report to each title and
	sorts each person's entries by average rating.

 -vmrr  Adds the information from the movie ratings report to each title and
	sorts each person's entries by number of votes.

If no format option is given, the script formats the results in the style of
the published lists.


9.4 Output Options
==================

      -r  raw mode, don't format results
      -m  movies only, ignores TV-series
    -cat  use 'cat' instead of 'more' to page results
  -match  use with the movie ratings options, only outputs titles that match
 	   the ratings database.


9.5 Examples
============

   lformat -acr
     -- regenerates published form of actors list

   lformat -cast -f names
     -- formats subset of cast lists consisting of people listed in the 
	 'names' file
   
   lformat -dead -yr
     -- formats entire dead list & adds year information

   lformat -acs -mrr
     -- formats entire actress list and adds ratings report information

-------------------------------------------------------------------------------
10. LINDEX SCRIPT
=================

This is an indexing script for the lists. You can use this to generate a list 
of all the names or titles on individual lists or combinations of lists. The 
options available can be divided into three classes:

10.1 Database options
=====================

These options specify which of the seven lists you would like to search and can
be combined in any order:

 -acr     actors list
 -acs     actresses list
 -dead    dead list
 -cast    combination of -acr -acs & -dead
 -dir     directors list
 -write   writers list
 -comp    composers list
 -cine    cinematographers list

Note, if you do not specify any database options then the default is to search 
all the lists.

10.2 Index Type options
=======================

 -name    generate an index of the names on the selected list(s)
 -title   generate an index of the titles on the selected list(s)

10.3 Output Options
===================

These options specify how the results will be displayed:

 -s <substring> restrict search to names/titles containing <substring>
 -m list movies only, no TV-series
 -i become case sensitive with -s
 -cat use 'cat' to display results instead of 'more'

10.4 Movie Ratings Report Options
=================================

The ratings report options may be used in conjunction with the -title option:

  -mrr  add ratings report data
 -smrr  add ratings report data and sort by average ratings
 -vmrr  add ratings report data and sort by number of votes 

10.5 Year Options
=================

The year options may also be used in conjunction with the -title option:

          -yr  adds the year of release and sorts in chronological order.

         -yru  adds the year of release, but leaves in alphabetical order.

 -yrfrom <yr>  Use with -yr{u} to restrict index to titles released during 
	       or after <yr>

   -yrto <yr>  Use with -yr{u} to restrict index to titles released before <yr>

   -yreq <yr>  Use with -yr{u} to restrict index to titles released in <yr>
	
10.6 Miscellaneous Options
==========================

There are two options for indexing the aka database:

  -aka     generate list of all the titles and their alternatives in the aka 
	     database

  -invaka  as "-aka" but inverts the ordering

10.7 Examples
=============

 lindex -dead -name
   -- generate list of all the names on the dead list

 lindex -acr -s "Michael" -name
  -- generate list of actors containing the substring "Michael"

 lindex -title -s "Alien"
  -- generate list of all movie/tv titles containing "Alien" 

 lindex -aka
  -- generate list of all titles in aka database

 lindex -title -yr -yreq 1945
  -- list all titles in database released in 1945

 lindex -title -dead -yr -yrfrom 1920 -yrto 1925
  -- list all titles on dead list released between 1920 and 1925

 lindex -title -cast -yr -yrfrom 1990
  -- list all titles on the casts lists released from 1990 onwards

-------------------------------------------------------------------------------
11. ALIST SCRIPT
================

This script searches the attribute fields of all the databases. Examples
of the kind of queries you can construct include:

 * search for details of all best actor academy award winners

 * search for all golden globe nominees

 * search for all movies narrated by a particular person

 * search for all plays by a particular writer that have been filmed

I have tried to keep the option structure as close as possible to the ones 
used by the other scripts, so hopefully the script should be easy to use.
The options fall into three main classes:

11.1 Database options
=====================

These options specify which of the seven lists you would like to search and can
be combined in any order:

 -acr     actors list
 -acs     actresses list
 -dead    dead list
 -cast    combination of -acr -acs & -dead
 -dir     directors list
 -write   writers list
 -comp    composers list
 -cine    cinematographers list

Note, if you do not specify any database options then the default is to search 
all the lists.

11.2 Search options
===================

These options specify the information to be searched for:

 -aa               academy award winners
 -aan              academy award nominees
 -gg               golden globe winners
 -ggn              golden globe nominees
 -attr <pattern>   values matching <pattern>
 -n <name>         restrict search to entries for a specific person
 -t <title>        restrict search to entries for a specific movie

The academy award options can be combined together to give a list of all winners
and nominees. The same is true for the golden globe options.

The awards options also match supporting roles too. If for example, you just
want a list of best actor winners, you need to use the -attr option:

  alist -acr -attr '(AA)'


If you don't supply any search options then the default is to search for any
entries with non-empty attribute fields.

11.3 Output options
===================

These options specify how the results will be displayed:

 -r    raw mode, do not format output
 -s    substring, allow partial matches with -n and -t
 -i    become case sensitive in searches
 -m    movies only, don't display TV series information
 -cat  use 'cat' to display the results instead of 'more'

11.4 Year options
=================

 -yr  adds year of release to titles and group results by year

-yru  adds year of release but leaves results unsorted

11.5 Examples
=============

alist -aa
 -- search all databases for academy award winners

alist -cast -ggn
 -- search cast lists for golden globe nominees

alist -acr -n "De Niro, Robert" -aa -aan
 -- search for details of De Niro's academy award wins/nominations

alist -t "Driving Miss Daisy" -aa -aan
 -- search for details of DMD's acadamy award wins/nominations

alist -dead -n "Welles, Orson" -attr "(narrator)" 
 -- search for all movies/tv series narrated by Orson Welles

alist -acr 
 -- list all entries on the actors list with non-empty attribute fields

alist -aa -dir -yr
 -- lists all best director oscar winners by year

-------------------------------------------------------------------------------
12. CONFIGURING THE DATABASE
============================

12.1 Advanced 'gendb' Options
=============================

12.1.1 Selective Updates
------------------------

To save time when updating the databases, I have provided a set of options
for gendb to allow selective updating.

The options are:

 -acr    update actors database 
 -acs    update actress database
 -dead   update dead database
 -cast   update all cast databases (comibination of -acr -acs -dead)
 -dir    update directors database
 -write  update writers database
 -comp   update composers database
 -cine   update cinematographers database
 -mrr    update ratings database
 -movie  sort the movies database

The options can be used in any combination and in any order. If you do not
specify any options, the script will update all the databases for which
there is a list file in the directory. Once you have updated the appropriate
databases you may delete the corresponding list files if you wish.

12.1.2 Reducing the size of the database
----------------------------------------

If you are short of disk space and are not interested in the TV-series
information, the "-m" option (movies only) will cause 'gendb' to only
store movie information. At the moment this reduces the size of the databases 
by a total of 200K.

12.1.3 The aka file
-------------------

The aka file will be published occasionally in rec.arts.movies and will also
be available on the ftp server. It covers roughly 1,000 alternative titles
for movies in the database. To make the information available to scripts,
place a copy in a file called 'akafile' in the scripts directory and run

   'gendb -aka'

this will add any titles that aren't already in the aka database (aka.dbs).

Reminder: to get the scripts to look for information under an alternative 
title, use the "-aka" option on the 'title' script. 


12.2 Temporary Files
====================

Many of the scripts generate temporary files during execution to store 
intermediate results. In previous releases such files were always created
in the current directory. This meant that if you share the scripts with more
than one user on your system, you had to give them write permission on 
scripts directory. In this version, the directory where the temporary files
are created can be specified by the environment variable $MOVIESTMPDIR. If it
is undefined, the scripts treat the default value of this variable as $TMPDIR.
Finally, if $TMPDIR is undefined, the current directory is used as before. 

If you don't understand the last paragraph or you are the only person that
uses the scripts on your system - the external behaviour of the scripts is not 
affected, so there's no need to worry.

Thanks to Philippe Queinnec for this change.

-------------------------------------------------------------------------------
13. PERSON SCRIPT
=================

This script is similar to the 'title' script except that it searches the 
databases for entries by a particular person or set of people. It is also 
similar to the 'list' script, but because it checks all the databases, it is a 
lot more powerful in cases where a person has had more than one career (e.g.
writer/director, actor/director etc.)

The options available are very similar to those on 'title':

13.1 Basic Options
==================

 * person -n "<name>"

   Lists all the films that a particular person has been involved with. 
   The list is sorted in the following order: directing credits (marked
   with "(d)"), writing (w), music (m) and cinematography (ph). For example,

     person -n "Welles, Orson"

     person -n "Carpenter, John"

 * -s  

   Allow partial match on names. This option is useful if you can't 
   remember the precise spelling of a name. 

   To see which entries have been matched, use "-r" in combination 
   with this option (see below).

 * -r  

   Raw mode. Output results of search in full and unsorted. This is 
   useful with -s when you want to know what entries have been matched.

 * -i  

   Pay attention to case in search.

 * -cat  

   Cat results. Uses 'cat' to display results instead of 'more'.

 * -noattr 

   Do not display attribute values. 


13.2 Advanced Options
=====================

Sometimes when using 'person' you might not be interested in searching some of
the databases. Several options are available to do this and they can speed
up the search considerably:

  -noacr    ignore actors database
  -noacs    ignore actresses database
  -nodead   ignore dead database
  -nocast   ignore cast databases (combines -noacr -noacs -nodead)
  -nodir    ignore directors database
  -nowrite  ignore writers database
  -nocomp   ignore composers database
  -nocine   ignore cinematographers database
  -nocrew   ignore crew databases (combines -nodir -nowrite -nocomp -nocine)

These options may be mixed in any combination.


13.3 Multiple Queries
=====================

Multiple name queries can be used (as with 'title') and the script will 
return the list of movies common to all the people specified. Examples:

  person -n "Welles, Orson" -n "Cotten, Joseph"
   -- returns list of movies that Welles & Cotten were both involved with

  person -n "Wilder, Billy" -n "Diamond, I.A.L." -nocast -nocine -nocomp
   -- returns list of Wilder/Diamond movies from directors & writers list

13.4 Year Options
=================

  -yr  Adds year information to results list and sorts in chronological order.

 -yru  Adds year information, but sorts in alphabetical order

Example:

   person -n "Welles, Orson" -yr

-------------------------------------------------------------------------------
14. MKBALLOT SCRIPT
===================

This script generates a movie rating ballot for all the movies a 
particular person has been involved with. The format of the command is:

  mkballot [-a -d -w -c -ph] <name>

The options conform to the standards used in the other scripts:

 -a actor/actress

 -d director

 -w writer

 -c composer

 -ph cinematographer

The resulting ballot is placed in a file called 'ballot'. You can now edit
this file, remove entries for movies you haven't seen and add the ratings
for those you have. The file can then be mailed to the vote tabulator.
For further details on taking part in the movie ratings poll see Chuck's
regular weekly postings. I have also written a set of vote management scripts
which can help you to keep track of movies you've voted for and automatically
remove them from the ballots. Contact me via e-mail for details.

Examples:

  mkballot -a "Bogart, Humphrey"
   -- generate a ballot for all Bogie's movies

  mkballot -d "Hitchcock, Alfred"
   -- generate a ballot for all Hitchcock's movies

-------------------------------------------------------------------------------
15. AKAPRINT SCRIPT
===================

This script takes the output from many of the other scripts and adds any 
alternative titles from the aka database. The script takes it's data from
the standard input so it should be used in a Unix pipeline. Examples:

   list -a "Signoret, Simone" | akaprint

   listall "Jules and Jim" | akaprint

Thanks to Philippe Queinnec for this script.

-------------------------------------------------------------------------------
16. LDEBUG SCRIPT
=================

The idea behind this script is that it will help keep the lists more accurate 
by making it easier for you to detect errors and omissions which you can then 
forward to the maintainers. At the moment there are two modes of operation:
one to check a batch of additions prior to submitting them and the other to look
for omissions on the movies list.

16.1 Debugging Additions
========================

In this mode of operation, the script looks at a batch of additions in a file
and returns a list of all the names that do not appear on the list they are
intended for, and all the titles that are not on the movies list. The items
reported will either be genuinely new to the lists or they will be errors
such as minor spelling mistakes or format differences etc.

All the list managers would greatly appreciate it if you could run any additions
you intend to submit through this script. It will save us a huge amount of
time debugging entries and also make the lists more accurate.

To use the script in this mode, you need to specify the list for which the
additions are intended:

   -acr    actors
   -acs    actress
  -dead    dead
   -dir    directors
 -write    writers
  -comp    composers
  -cine    cinematographers

and the name of the file where the additions are stored:

  -adds <file>

The additions should be in the standard database form, i.e.

  <name>|<title>|<attributes>

Example:
--------

  ldebug -dead -adds dead.adds


16.2 Debugging the movies list
==============================

In this mode, the script operates in a similar fashion to 'list' - it takes a 
name and searches the appropriate database, but it just returns a list of
titles that have missing year information. The results take the form of 
additions to the movies list, all you have to do is replace the ????'s
with the years that you know and mail the file to Michel for inclusion in 
the next release. It is the "-noyear" option which triggers this check.
The standard database options apply (-acr, -acs etc.) and the name you wish
to debug is specified using the "-name" option.  Example:

   ldebug -acs -name "Hepburn, Katharine" -noyear > corrections

produces the following in the file 'corrections'

Break of Hearts|????|
Christopher Strong|????|
Grace Quigley|????|
Little Minister, The|????|
Mrs. Delafield Wants to Marry (TV)|????|
Stage Door Canteen|????|
Trojan Women, The|????|
Without Love|????|

You can then edit this file as described above and mail it to Michel. We 
appreciate any time you can devote to do this. If everybody did just a few
entries a month, it would take no time at all to make the titles datbase
complete!

To stop the script generating missing entries for TV-series, use the "-m"
option:

   ldebug -acs -name "Stone, Sharon" -noyear -m

The "-noyear" option only returns the titles from the person's entries on the
list that are also in the current movies list. There are many reasons why
a title on a list may not be in the movies list, including:

  * it is a movie new to the lists and Michel hasn't had time to add it yet

  * the title has been incorrectly spelled on the titles list

  * the title has been incorrectly spelled on the relevant list 

  * the title needs year information on the list and the maintainer hasn't
     had time to add it yet.

To see the full list of titles without year information regardless of whether
they appear on the movies list, use the "-full" option. 

In general, you shouldn't need to use the "-full" option, but if you are 
desperate to see all your favourite people's movies covered completely in the 
titles list, you might find it useful. You can check which entries are already
in the movies list in a different form and then mail the appropriate 
list maintainer to point out the errors. However, remember that the "-full"
results also include the plain "-noyear" results so you need to fix those 
first.

-------------------------------------------------------------------------------
17. LSEEN SCRIPT
================

This script is for use in conjunction with my movie ratings report voting 
support scripts. It's mainly for statistics freaks, but I thought it of
enough general interest to include in the package. The script sorts listed 
names by the number of their films that you have seen (based on data from
the votelog file).

If you don't use the voting support scripts, they are available via anonymous
FTP from penguin.gatech.edu in the directory pub/movie/process.

17.1 Checking the votelog file
==============================

Title formats on the movie ratings report do change from time to time as 
errors are discovered. In order to make 'lseen' more accurate, I have 
written a simple script to check that titles in the votelog file match
those on the report. To perform the check type:

   votechk

A list of titles that you have voted for that are not listed on the report
is generated. You may then correct the votelog file as appropriate. Note 
that titles that are not eligible to appear on the report (less than 5 votes)
will also be listed.

17.2 Database options
=====================

These options specify which of the seven lists you would like to use and can
be combined in any order:

 -acr     actors list
 -acs     actresses list
 -dead    dead list
 -cast    combination of -acr -acs & -dead
 -dir     directors list
 -write   writers list
 -comp    composers list
 -cine    cinematographers list

17.3 Output Options
===================

 -cat  use cat to display results instead of more

  -nv  no voice, ignores entries in cast database where the person only supplied
        a voice in the movie

17.4 Ratings Report Options
===========================

  -mrr  show movie ratings report info for each title you have seen

 -smrr  as -mrr, but sort by average ratings

 -vmrr  as -mrr, but sort by total number of votes

17.5 Examples
=============

 lseen -dir 
  -- count directors

 lseen -cast -mrr
  -- count actors & actresses and display ratings report information

-------------------------------------------------------------------------------
18. OTHER CHANGES
=================

This section describes changes for users of version 2.2.

18.1 Install Script
===================

The 'install' script has been renamed to 'linstall' to avoid problems on some
systems. 

18.2 New Sort Order
===================

To support the new options listed in the next section, I have had to change the
sort order of all the database files. To switch to the new order, run:

   linstall -update

A new option has been added to 'gendb' to sort the movies list. The version 
of the list on the server should already be in the correct order, but if you
appear to be having problems, run:

   gendb -movie

18.3 Mguide
===========

  -yr  adds year of release information

 -aka  lists any alternative titles

 -mrr  adds movie ratings report information

These options may be used together.

Example:

   mguide -yru -aka -mrr
    -- generates a movie guide combining all the information in the databases

18.4 Lguide
===========

   -f <file> specifies file of titles you are interested in

       -yru  adds year of release information

       -aka  lists any alternative titles

       -mrr  adds movie ratings report information

       -cat  use 'cat' to display results instead of 'more'

18.5 Alist
==========

 -yr  adds year of release to titles and group results by year

-yru  adds year of release but leaves results unsorted

-------------------------------------------------------------------------------
19. NOTES
=========

(1) I welcome feedback on the scripts. If you have any problems or would like
    to see a particular feature added, please let me know by e-mail.

(2) I will be adding some new features in the near future. If you would like
    to receive updates by e-mail, send me a mail message. 

(3) The scripts are not completely idiot-proof. It is possible to 
    specify certain invalid option combinations. 

(4) Options to the scripts can be specified in any order.

(5) I have been working with the other list keepers to ensure titles are
    consistent between lists (year info, capitalization, spelling etc.),
    however, there are bound to be a few discrepencies here and there.
    This may lead to some titles/people not being located in a search,
    even though the information is essentially in the database. Please let
    me know if you come across any instances of this.

(6) If you are interested in taking part in Chuck Musciano's Movie Ratings
    poll, I have a set of vote management scripts. They can generate a ballot 
    for the whole report and make voting in the weekly ballots easier by
    keeping track of which movies you have already voted for. Available by
    e-mail from me or via anonymous FTP from penguin.gatech.edu in the 
    directory pub/movie/process.

Cheers,

Col

-----------------------------------------------------------------
"Now you listen to me, I'm an advertising man not a red herring"
  -- Cary Grant, North by Northwest
-----------------------------------------------------------------
Col Needham                |  Phone: +44 272 799910 x 28704
HP Labs                    |  cn@hplb.hpl.hp.com
Bristol                    |  cn@hplabs.hpl.hp.com
U.K.                       |  100022.1126@compuserve.com
-----------------------------------------------------------------

THE SHELL ARCHIVE IS NOW IN A SEPARATE FILE TO FOLLOW