
                            aviManager - Manual
                            -------------------

                     Markus Riester <mriester@gmx.de>

                                   0.9.2


-------------------------------------------------------------------------------


Copyright Notice
----------------

     Copyright (C) 2002-2007 M.Riester

     This manual is licensed under the terms of the GNU FDL (Free
     Documentation License).  It has been written in the hope that it will
     be useful to the community but it comes with no warranty; use it at
     your own risk.

     /doc/README - TEXT VERSION, /doc/html/index.html - HTML VERSION


-------------------------------------------------------------------------------


Contents
--------

     1.        Introduction
     1.1.      Copyright
     1.2.      About the Script
     1.3.      System Requirements
     1.4.      Warnings
     1.5.      Known Bugs & Limitations
     1.6.      About Versions

     2.        Installation

     3.        Customizing

     4.        Problems

     5.        Hints
     5.1.      Searching
     5.2.      Voting
     5.3.      Find Movie
     5.4.      Add Movie
     5.5.      Burning Movies to CDROM/DVD
     5.6.      Different formats for movie lists
     5.7.      Update Votes

     6.        Importing Data

     7.        FAQ

     8.        Revision History

     9.        Credits


-------------------------------------------------------------------------------


1. Introduction
---------------


1.1. Copyright
--------------

     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or (at
     your option) any later version.

     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
     USA.

     Send bug-reports, comments to <mriester@gmx.de>

     Icons are taken from KDE (http://www.kde.org) and GNOME
     (http://www.gnome.org).

     Bar (and code for displaying it) is taken from Web-APP
     (http://www.web-app.org/cgi-bin/index.cgi)

     Default theme for the 0.9pre-series is taken from plone
     (http://www.plone.org)


1.2. About the Script
---------------------

     This script helps you to manage your (large) movie (DVD,DivX)
     collection.  It ships with an intelligent voting system for many
     users.  aviManager attempts to find the best movie to watch.  You will
     be surprised how good it works.  There is also a nice imdb grabber for
     fast movie adding.

     Main features (if you find a free movie database with more features,
     let me know ;-) ):

        * IMDb Grabber (including DVD-Cover, plot, ...)

        * Search IMDb Database and add movies with one click

        * Voting System: user can vote movies, add movie to a wishlist (-4
          = I don't wanna see this movie, 5 = I want to see this movie very
          soon) and can say how often he has seen the movie.

        * Great search (optional fuzzy search for typos, Regular
          Expressions) and ranking possibilites

        * low system requirements (you don't have to setup something like
          MySQL-which is great, but not necessary for a small database like
          this).

        * subtitle upload

        * different owners

        * export moviedatabase to readerfriendly format (templates
          available for HTML,LateX,Ascii)

        * statistics

        * Multilanguage support (English, Danish, French, German, Greek,
          Hungarian, Polish, Swedish, Spanish, Russian and Norwegian
          available)

        * single user mode: for people who don't want this voting stuff for
          many users and who just need a little movie database.  You can
          safely switch between modes, if you find friends who are willing
          to vote.

        * users can add comments to every movie

        * last seen list

        * lent list: set status to lent and aviManager will remind you who
          borrowed which movie

        * Movie of the moment (or minute, hour, day, ...)

        * Requests: Put movies you want to have on this list


1.3. System Requirements
------------------------

        * A working copy of Perl 5 (tested with 5.6.1 and 5.8).

        * A basic understanding of both Perl and CGI.

     This program has been tested on the following plattforms: Linux 2.4
     under Debian Woody and Red Hat 7.x, NetBSD 1.6.  Linux 2.6 under
     Debian Sarge, Mac OSX and Windows There are known Problems with Red
     Hat 8 (you have to downgrade to Apache 1.x or try to change in
     aviman.pl, first line "#!/usr/bin/perl -w" to "#!/usr/bin/perl -X")
     and Solaris (turn off file locking).


1.4. Warnings
-------------

     aviManager needs a lot of CPU time.  It is very comfortable and
     generates everything on the fly.  This could be a problem if you don't
     have your own webserver.  IT IS POSSIBLE THAT YOUR WEBHOSTER DOES NOT
     LIKE AVIMANAGER AND WILL FORCE YOU TO REMOVE AVIMANAGER OR EVEN CLOSES
     YOUR ACCOUNT.  READ GPL.  USE AVIMANAGER AT YOUR OWN RISK.  YOU HAVE
     BEEN WARNED.  SEE WARNING BELOW FOR ANOTHER GOOD REASON NOT TO PUT
     AVIMANAGER ON A PUBLIC SERVER!

     It is not legal to use the IMDb grabber.  See
     http://www.imdb.com/help/show_leaf?usedatasoftware for details.  The
     IMDb grabber in aviManager is only an example implementation.  Use
     this as a template for websites where this way of information
     gathering is legal.  We are working on getting the IMDb data out of
     their flat files, which would be 100% legal for personal AND
     non-commercial usage.  DON'T PROVIDE ANY IMDB DATA TO THE PUBLIC.


1.5. Known Bugs & Limitations
-----------------------------

     There is one nasty bug in the actors index.  Links to actors will
     sometimes not return all actors.  Maybe this is fixed in pre6?

     There are a few limitations:

        * You cannot add duplicates (if you have different versions of this
          movie).  If you need this feature, use the comment-field until
          this is possible.

        * You cannot add non imdb-movies.  If you have some, use Add movie
          offline and a fake IMDB ID until this is possible

        * You cannot set user permissions for different features (for
          example add movies, but delete/change only his, ...).  No good
          solution at the moment.  Trust your friends or give them only an
          [VIP] account.


1.6. About Versions
-------------------

     Versions 0.x.x are always well tested and contain no known bugs.
     Other versions are developer versions (CVS-snapshots) that seem to be
     stable on our machines but contain new (not thoroughly tested)
     features.


-------------------------------------------------------------------------------


2. Installation
---------------

     Please open the file UPGRADE instead if you upgrade from a previous
     version of aviManager!.

     Version 0.9pre9 comes with an install script.  You can use this if you
     install aviman on your local machine or if you have ssh access to your
     server (once again, don't install aviManager on a public server!).

     Run the script with

     perl install.pl

     The script tries to guess your system.  If everything looks ok, start
     installation with

     perl install.pl -i

     If not, specify the paths and the apache user with the corresponding
     command line arguments (see output of the script).

     For people who can't use the installer, here the detailed installation
     instructions.  Steps marked with [X] are necessary even with the
     installer (AFTER you run the script).

     1.   [X] Make sure that you have installed Apache, Perl and following
          Perl Modules: LWP Module, CGI:Session, HTML::Template and
          Config::IniFiles

          Most Linux distributions package LWP under the filename
          libwww-perl (Debian: apt-get install libwww-perl
          libhtml-template-perl libcgi-session-perl
          libconfig-inifiles-perl)

     2.   Unzip the distribution.  Upload all files in cgi-bin in ASCII
          mode to a directory on your server that can run cgi.  For
          example, I recommend creating a directory called aviman off your
          cgi-bin.

          Make sure these files are transferred in ASCII mode!!

          Upload the files in avimanager/pages to a directory outside
          cgi-bin.

          On your server, you should now have two directories with
          following structure

                  cgi-bin/aviman/
                  cgi-bin/aviman/Aviman/
                  cgi-bin/aviman/Aviman/CGI
                  cgi-bin/aviman/data
                  cgi-bin/aviman/data/db
                  cgi-bin/aviman/data/db/backup
                  cgi-bin/aviman/data/db/comment
                  cgi-bin/aviman/data/db/plots
                  cgi-bin/aviman/data/movielist
                  cgi-bin/aviman/data/tmp
                  cgi-bin/aviman/data/votes
                  cgi-bin/aviman/language
               
                  aviman/pages/
                  aviman/pages/images
                  aviman/pages/images/cover
                  aviman/pages/images/headshots
                  aviman/pages/media/
                  aviman/pages/subtitles
                  aviman/pages/themes
                  aviman/pages/themes/default
                  aviman/pages/themes/default/images
                  aviman/pages/themes/default/templates

     3.   [X] Double-check that the Path to perl in aviman.pl and all other
          *.pl files is correct.

                       #!/usr/bin/perl

     4.   Set permissions:

             * chmod 755 (-rwxr-xr-x) on the *.pl files and aviman.cfg file
               in cgi-bin/aviman/

             * 777 (drwxrwxrwx) on the cgi-bin/aviman/data directory and
               its subdirectories

             * 777 (drwxrwxrwx) on the pages/images directory and its
               subdirectories

     5.   [X] Open aviman.cfg with your favorite editor and answer the
          configuration questions.  The most confusing step here for many
          new users is the owners feature.  If you want to manage your
          movie collection with your roommate for example, you have to add
          your username and your roommates username here.

          `@owners = ("me", "roommate");'

          Yes, this is a hack and there is not yet an interface for adding
          or removing owners.  Removing owners is probably not yet possible
          without some textfile hacking, so you should only delete the
          accounts (that means, they can't login anymore)!

     6.   Open Aviman/CGI/aviman_cgi.ini with your favorite editor and set
          paths and urls

     7.   [X] Go to: http://yourserver.com/cgi-bin/aviman/aviman.pl or
          wherever you set up aviman.pl, Login as user: admin, password:
          admin, and you should see the search screen.

          Now try following features:

          1.   Add a new super user account [SU] (e.g.  "me" and "roommate"
               in the example above).

          2.   Logout and login as "me"

          3.   Add a movie.

          4.   Search for a movie.

          5.   Vote for a movie

          6.   add comments

          7.   upload file (if you have activated subtitle upload in
               aviman.cfg)

          8.   delete user "admin"

          If everything goes ok, you should be all done!

     8.   [X] Optional but highly recommended: Install String::Approx
          (http://search.cpan.org/search?dist=String-Approx)

          Debian: apt-get install libstring-approx-perl

     9.   [X] If you have problems, please use our help-forum
          (http://sourceforge.net/forum/forum.php?forum_id=183397) at
          sourceforge.

     10.  [X] If you miss some fields (Quality, md5sums, ...), it is now
          the best moment to add them, because it is much more difficult
          with an existing database.  Please read comments in aviman.cfg,
          Preference Questions and read the FAQ in this manual.


-------------------------------------------------------------------------------


3. Customizing
--------------

     aviManager is highly configurable!  See aviman.cfg for details.  For
     example, you can easily add fields (like the often requested Quality
     Field).  TODO: explain field adding better, present cool optional
     features


-------------------------------------------------------------------------------


4. Problems
-----------

     See also FAQ!

        * 500 Server Errors.

          If you get one check the following:

             * Did you upload/ftp the file up in ASCII mode?

             * Is the path to Perl correct?  (#!/usr/bin/perl)

             * Are there any syntax errors you made when editing
               aviman.cfg?

             * Are the files set to the right permissions?

             * Look in your apache error log file (ask your provider where
               you can download them/ tail -f /var/log/apache/error.log)

             * Are all Perl Modules installed and in the @INC path?  Be
               aware that this path may be not the same for all users.  You
               can change the @INC path in aviman.pl, in the BEGIN section.

BEGIN{
push @INC, ('.', '/sw/lib/perl5/5.8.6/darwin-thread-multi-2level',
'/sw/lib/perl5/5.8.6', '/sw/lib/perl5/darwin-thread-multi-2level',
'/sw/lib/perl5', '/sw/lib/perl5/darwin');
}

          500 server errors are 99% of the time caused by: File uploaded in
          BINARY mode, or path to perl is wrong.

        * Error including libraries.  Make sure they exist, permissions are
          set properly, and paths are set correctly.

          See item 500 Server Errors above.  Try on your local machine:

               	$ perl aviman.cfg

        * Can't login (0.9pre2 and later) Well 0.9pre3 should tell you if
          something went wrong with installation.  if not check:

             * Can you login once and then Login-page reloads?  Then the
               sessions are not saved.  Double check if sessions path in
               aviman_cgi.ini is correct and Apache has write access to
               this directory.

             * You can't login.  Make sure that your password is correct
               (.htusers is readable and path in aviman_cgi.ini is correct

          Please report other problems.

        * Bad colors in "Find Movie" results.  Choose a default color (RGB)
          and a color difference for R, G and/or B.  R,G and B must be
          small enough (dark enough) to add 8 times this color difference.
          For example

                  $default_color = "#b0aabb"
                  %color_difference = (R => 8, G => 0, B => 0)

          so R is b0 (156) -> 156 + 8 * 8 < 256 (ff)

        * Search is too slow.  Probably, you have forgotten to install
          String::Approx
          (http://search.cpan.org/search?dist=String-Approx).  Please
          install version 3.x or the latest 2.x version, those don't need a
          C-compiler.

          You can turn off fuzzy search in aviman.cfg:

                  $use_no_fuzzy_for_actors_db = 1;
                  $use_no_fuzzy_for_movie_db = 1;


-------------------------------------------------------------------------------


5. Hints
--------

     Many things are obvious, but aviManager has some great "hidden"
     features:


5.1. Searching
--------------

        * Regular Expressions in search.  Keywords between two slashes
          (/keyword/) are treated as regular expressions.  The last slash
          is not required (/keyword works,too) Examples:

        * Problem: If you search for "foobar", fuzzy search finds too much.
          Solution: use simple regex /foobar instead

                    	foobar gets foobaa, fooba, ...
                    	/foobar gets only foobar

        * List all movies start with letter X (search is not case
          sensitive) type /^x and select movielist in combobox so that
          Xander Berkeley will be ignored

        * List all movies from 1966

               /\t1966

          (\t is tab and standard sepearator in movies.txt, /1966 will list
          also movies with 1966 in imdb number)

        * List all movies better than imdb-rating 9 (10.0 will be ignored)

               /\t9\..*


5.2. Voting
-----------

     Fast Voting (just 3 clicks per movie) with this features:

        * aviManager sets "seen" to 1 if you vote (rating) for a movie and
          current value for seen is 0.

        * Next/Prev not yet voted for links in detailpage.


5.3. Find Movie
---------------

        * aviManager displays movies (not in single_user_mode) in find
          results with different back- ground colors.  The darker, the more
          other people want to see this movie.  Great with many users.

        * Maybe you want to turn "Check wishlist" off if you watch a movie
          with friends that have not yet voted.  Then, only your seen and
          (imdb-)rating will count, not your wishes.


5.4. Add Movie
--------------

     There are four methods of adding movies:

        * Search IMDb: Simply type the movie title in the search field of
          this box.  If there are more than one results, click on the movie
          you want to add and avimanager grabs the data immediately

        * Add by directory name: If you have an DivX movie which follows
          "The DivX Releasing Standards 2002", you can simply add this
          movie by cnp the directoryname in this box.  This feature is
          still beta, please send me directory names where this does not
          work!!!

        * Add by IMDb number: cnp the IMDb number in the corresponding
          field in the "Add Movie" Box

        * Add Movie (Offline): This allows you to add movies without the
          IMDB-grabber


5.5. Burning Movies to CDROM/DVD
--------------------------------

     When you add a movie, aviManager sets status to "not burned".  If you
     have burned some movies on a DVD, you can go to the "not burned" page
     (first link in the admin box), select them and add a description for
     that DVD.  You can create hierarchies with slashes, e.g.  a
     description DVD/2005/001 will create a tree DVD->2005->001 in the "All
     Media" page.


5.6. Different formats for movie lists
--------------------------------------

     If you have many movies, you don't want this colourful default movie
     list with plot and cover.  Set $use_wn_format = 0; in aviman.cfg and
     you get a table with need much less space.


5.7. Update Votes
-----------------

     With the cgi-script update_votes.pl, you can update imdb votes and
     rating.  Goto
     http://your.server.com/cgi-bin/aviman/update_votes.pl?plot=1 to grab
     all votes, ratings and plots.


-------------------------------------------------------------------------------


6. Importing Data
-----------------

     AviManager stores data in a file called movie.db.  Please open this
     file now if you want to import data.  You need to get your old
     database into this format (see aviman.cfg, Preference Question 7 for
     details).  You probably have no IMDb numbers, so you must get them.
     Please contact me, and I will help you...

     Ok, now you think you have a valid movies.db?  Please check this with
     the script show_db.pl (in tools/cgi)!

     Now you get an html-table with the database.  If everything looks
     good, it is time to get the IMDb data like plots, cover, actors,
     genre, year and runtime.  The script update_votes.pl can do this.  To
     test it with 5 movies, start the script with following parameters:
     `http://www.yourserver.com/cgi-bin/aviman/update_votes.pl?start_number=1&count=5&actors=1&cover=1&plot=1&genre=1&year=1&runtime=1'.
     Start aviman.pl and go to one of these movies.  Everthing ok?  Then
     start the script without start_number and count!

     Please help to improve this HOWTO/Importing!


-------------------------------------------------------------------------------


7. FAQ
------

     Feel free to email me if your question is not mentioned here

        * Q:Is it possible to add field 'foobar'?

          A:Yes, version 0.5 comes with a new database structure that makes
          this possible.  Read comments in aviman.cfg.

          [ If you have an existing database, you have to convert
          movies.txt with the script convert_db.pl or change every movie
          manually ]

          Examples:

          1.   A normal STRING field (like Name, Comment, ...), for example
               Ripper: open aviman.cfg and add following line in database
               definition %db:

               `Ripper => [11, 'STRING', 0, 0, 0, 30, 75, 0, '', ''],'

               Last column is a regex (for INTEGER fields etc.)

          2.   An SELECT field (like Status), for example Type: add an hash
               somewhere BEFORE database definition

               `%type =
               ('1'=>'DivX','2'=>'DVD','3'=>'SVCD','4'=>'MPEG','5'=>'VHS');'

               and add line in %db:

               `Type => [12, 'SELECT', 0, 1, 1, 20, 25, 1, '1', \%type],'

        * Q:Field 'foobar' is too short/big, where can I change it?

          A:Like everything else, in aviman.cfg.  Open it with your
          favorite editor, goto preference questions, question 5.  There
          you can see the datafield definition.  Column six is form length
          and column seven is maximum field length.  See comments in
          aviman.cfg.

        * Q:I can't login.  Whats f***ed up?

          A:See chapter "Problems" for details

        * Q:I don't want/can't use .htaccess.  Do I really need it?
          (obsolet)

          A:Yes, if you want more than one user (hey, this is our main
          feature).  AviManager uses .htaccess to know, who's the current
          user.  If you need just a little database for your seventeen
          movies, set $single_user_mode = 1.  Then you have only one user
          ($single_user_name) and all multiuser features will be hidden
          (version 0.5pre4 or higher).  But if you know a secure
          alternative for .htaccess (Session ID, cookies), let me know ...

        * Q:There is no movie of the moment!

          A:You have less than 50 movies

        * Q:I don't like this stupid copyright at the bottom of every page.
          Can I remove it?

          A:Yes.

        * Q:I like aviManager and want to help!  What can I do?

          A:Cool!  Unfortunatly, the aviManager source code is not very
          beautiful and needs a lot of work, so programming jobs are no fun
          I think.  But there are a lot of other jobs to do, for example:

          1.   Translations

          2.   A nice, classical aviman-logo for the new theme.  the plain
               AVIMANAGER at the top looks not very good

          3.   Header for new versions: Write me an email with your
               favorite actor and if I like her/him, be creative ;-)

          4.   Documentation: I'm not a native english speaker and I am the
               author of this software...Two reasons why this documation is
               not as good as it should be.  The source-code of this
               document is available from cvs.  Type:

               `cvs
               -d:pserver:anonymous@cvs.avimanager.sourceforge.net:/cvsroot/avimanager
               login'

               When prompted for a password for anonymous, simply press the
               Enter key.  Then type

               `cvs -z3
               -d:pserver:anonymous@cvs.avimanager.sourceforge.net:/cvsroot/avimanager
               co manual'

               Edit it and send it to mriester@gmx.de!

          5.   Templates (HTML, LaTeX) for movielists

        * No MySQL?  This sucks!  Maybe, yes.  The first reason is: the
          time I wrote this, there was no SQLite database.  I wanted to
          keep the system requirements as low as possible.  The second: the
          time I wrote this, I had no idea about Perl and SQL ;).


-------------------------------------------------------------------------------


8. Revision History
-------------------

     The aviManager-Evolution:

        * 04.03.2007: _0.9 aka "KELLY"_

          Installer script.  Better support for multiple owners.  XHTML
          1.0.  Login with sessions instead of .htaccess.  New translations
          (greek, russian, polish, danish).  Many minor bugfixes.  The most
          stable aviManager ever!

        * 10.01.2003: _0.8 aka "BERGMAN II"_

          Many cool features like IMDb search, lent list and sorting.  New
          translations (french, norwegian, spanish) and performance and
          usability enhancements.

        * 01.11.2002: _0.7 aka "BERGMAN"_

          New clean directory structure, bugfixes, documentation and again
          a lot of polishing

        * 01.09.2002: _0.6 aka "HEPBURN"_

          New, clean standard design, welcome page, templates for export
          movielist ...  in one word: polished

        * 04.08.2002: _0.5 aka "MONROE"_

          Multilanguage support, new great database structure, update
          votes, grab imdb plot and title, comments and many minor
          enhacements

        * 01.07.2002: _0.4 aka "WORLDCHAMPION"_

          fast actors-format, statistics, new search, ...  a must!

        * 01.06.2002: _0.3 aka "SCHEISSEMANN"_

          owner, subtitles ...

        * 02.03.2002: _0.2_

          more features, faster (actors still slow)

        * 24.02.2002: _0.1_

          basic features, BAD performance, many bugs

     see CHANGELOG


-------------------------------------------------------------------------------


9. Credits
----------

     A big "thank you" goes to thrawn and ronin for their bugreports,
     graphics and patches, all people who sent bugreports, hints and
     feature requests and of course www.imdb.com for their great database!

     _Translations_

        * Juan Jose Gutierrez de Quevedo: Spanish

        * Robert: Norwegian

        * Ashar Voultoiz: French

        * Juho Vahakangas: Finnish

        * Matte: Swedish

        * Lorro: Hungarian

        * Petar Benke: Serbian

        * Flavio Cardone: Polish

        * Reloaded: Danish

        * Terzi Athanasia: Greek


-------------------------------------------------------------------------------


     aviManager - Manual

     Markus Riester <mriester@gmx.de>


     0.9.0

