README file for MAMECAT
-----------------------

v0.42, 30-JAN-2001

Contents

 1) What is MAMECAT ?
 2) How to obtain the latest version
 3) Prerequisites and installing MAMECAT
 4) Preview images
 5) Command line options
 6) Options in $(HOME)/.mamecatrc, $(HOME)/.xmame/.mamecatrc or
    $(HOME)/xmame/.mamecatrc
 7) Catalog and ROM-status cache format
 8) ROM status
 9) Printing
10) Contacting the author(s)
11) Special notes for new versions of MAMECAT
12) License

1) What is MAMECAT ?

   MAMECAT stands for 'M.A.M.E. Catalog/Launcher' and basically this already
   says what it is :-).

   It consists of three programs:

   - qmamecat (X11/Qt based launcher application)
   - qmsetup (setup wizard, started by qmamecat on demand)
   - catgen (simple catalog generator, started by qmamecat on demand)

   Note that MAMECAT is available only for the UNIX-port of M.A.M.E. (aka
   X-Mame), so if you are a DOS/Win/Mac/whatever-MAME user, please use a
   different MAME launcher for one of those OSs. Have a look at the official
   MAME project homepage (http://www.mame.net/) which lists some of
   them.
   
2) How to obtain the latest version

   MAMECAT has its own homepage where new versions are made available for
   download, but please note that the location may change at any point in the
   future. In this case I will post a message to the xmame mailing-list to
   inform you...

   The current URL is http://www.mameworld.net/mamecat/ (english) or
   http://www.bingo-ev.de/~rh474/mamecat/ (german) !

3) Prerequisites and installing MAMECAT

   Prerequisites:

   for qmamecat & qmsetup:

   - Qt library (2.1.0 or above) - if you don't have it you can get it from
     Troll Tech (http://www.trolltech.com/)

   - the env. variable QTDIR should be setup correctly to compile & link
   
   for qmamecat, qmsetup & catgen:

   - C++ compiler/linker plus ar and ranlib utilities
   - GNU make utility
   - the env. variable HOME must be setup correctly to run qmamecat
   - xmame-0.34rc1.1 (or higher)

   Installation:

   Simply enter

   make

   in the top-level directory. If it shouldn't compile and link properly,
   cd into the presets directory, and type

   cp make.defaults make.`uname`

   (or cp make.defaults make.`uname`-`hostname` if you need local adjustments)

   and edit the newly created file to suite your needs. Go back to the top-
   level directory and try again.

   If you may want to recompile the man-page, add the correct path to groff to 
   the GROFF definition in the corresponding presets/make.`uname` file (or 
   make.defaults directly). But as a groff-compiled version of the man-page
   already exists in the doc directory, this should normally not be neccessary.

   After successful compile & link, enter (as root)

   make install

   and you should be fine. You should now be able to start MAMECAT by entering

   qmamecat (see note below !).

   NOTE: Before you start, I recommend you get xmame working correctly first !
   It will basically work, but as the catalog will not be correctly created
   and the ROM-status will not be determined, the result won't be very useful. 
   If you still decide to use qmamecat BEFORE xmame is correctly installed,
   use the "-r" option on the next start of qmamecat (after xmame IS working) !

   At the first start of qmamecat a setup wizard - qmsetup - will be launched 
   and you will be asked for the path to xmame; please enter (or browse) the 
   FULLY QUALIFIED PATH INCLUDING THE NAME OF THE EXECUTABLE.
   Qmamecat will then automatically create a startup catalog for you. Note
   that this requires (at least) catgen to be in your path (which should be the
   case when you use "make install") !

   The startup configuration is done with the defaults described in section 6, 
   except for <executable>, which you entered before. You may want to change 
   some of the options, for example to enable the preview-image support.

   For more information on how to enable preview images, please see next
   section.

4) Preview images

   If you wish to enable the preview images you will have to copy the images to
   the directory specified in .mamecatrc (option <previewdir>). 

   Additionally you will have to set the option <showpreview> to enable this
   function !

   Snaphots created by X-Mame - XPM (old) and PNG (new since xmame-0.35rc1.1),
   are natively supported, other image formats include GIF and BMP.

   Preview image filenames must be the same as their corresponding rom-images
   or <rom>-snap000 (up to <rom>-snap004); the extension should reflect the
   image format (at least one of the above format abbreviations must be used
   (in lower-case letters !) for qmamecat to find the image) !

   For example: the preview image file for 'galaga' would be a file named
   'galaga.xpm' or 'galaga-snap000.xpm' (up to 'galaga-snap004.xpm'); the 
   extension could be different, of course...

   Note that files without '-snap00x' are found first !

   If you store several images of a game with different image formats 
   (extensions), qmamecat will only display the one which it finds first. 
   Let's say you have 2 files for 'galaga', i.e. 'galaga.xpm' and 'galaga.gif',
   in this case qmamecat will only display 'galaga.xpm' ! 

   The complete current order is PNG -> XPM -> GIF -> BMP ! This does also 
   apply if you use the '-snap00x' naming convention.

   When the extension does not specify the 'real' image format, qmamecat will
   try to guess it (this is a nice feature of Qt's QPixmap class :-)... if it
   can't find the image file or validate the image format, the text 'Preview 
   not available' will be displayed instead.

   Since v0.28 zip-compressed previews are also supported ! The current 
   implementation accepts ONE big zip-file for ALL preview-images. This file has
   to be specified in the option <compressed_preview_file> and the option 
   <compressed_previews> has to be enabled (see section 6 for more details). 

   ZIP is currently the only supported (de)compression method !

   Note that all rules stated above do also apply if you use zip-compressed 
   previews.

5) Command line options

   The following command line options are currently available for qmamecat:

   -r            forces recreation of the ROM-status cache (should be
                 used if you install new ROMs or a new xmame version -
                 note that removing the ROM-status cache file has the
                 EXACT SAME effect !)
   -h or -?      shows a usage help and exits

   Additional switches derived from QApplication:
   
   [-display disp] [-geometry geom] [-fn fnt] [-font fnt] [-bg bgcol]
   [-background bgcol] [-fg fgcol] [-foreground fg_col] [-name name]
   [-title title] [-style=guistyle] [-ncols ncols] [-visual TrueColor]
   [-cmap] [-nograb] [-sync]

   See the man-page of QApplication(3qt) for a full description of these
   switches !

6) Options in $(HOME)/.mamecatrc, $(HOME)/.xmame/.mamecatrc or
   $(HOME)/xmame/.mamecatrc

   Qmamecat will search for $(HOME)/.mamecatrc, $(HOME)/.xmame/.mamecatrc
   and (as a last resort) for $(HOME)/xmame/.mamecatrc (in this order !).

   If it can't find any of these files, a minimum configuration will be
   requested from the user (it only needs the path to xmame for this) and 
   defaults will be used for the rest of the options.

   Also, if an option doesn't exist in the config file or its value is missing,
   the default will be used for this option (see table below).

   The individual options and their defaults are:

   option                   default        meaning/remarks
   -----------------------  -------------  -------------------------------------
   catalog                  ./mamecat.cat  catalog file to be used (if you want
                                           to modify/save it through mamecat,
                                           you must have write-permission - of
                                           course :-)
   tempdir                  .              directory for temporary files
   executable               xmame.x11      the X-Mame executable
   status_cache             ./mamecat.rsc  the ROM-status cache file 
   options                  -----          options passed to X-Mame (for *each*
                                           game - see section 7 for how to
                                           specify options passed to a *single*
                                           game)
   sort                     1              sort category:
                                           0 = don't sort
                                           1 = sort by name (of game)
                                           2 = sort by rom image name
                                           3 = sort by remarks
                                           4 = sort by rating
                                           5 = sort by rom status
                                           6 = sort by game specific options
   order                    1              sort order:
                                           0 = descending
                                           1 = ascending
   rating_min               0              min. rating to be displayed
   rating_max               6              max. rating to be displayed
   available_games_only     0              display only avalailable games ?
                                           0 = no
                                           1 = yes
   ignore_rom_avail         0              try to start games even if mamecat
                                           thinks they are unavailable ?
                                           0 = no
                                           1 = yes
                                           (only used by qmamecat, ignored by
                                           mamecat !)
   previewdir               -----          directory where preview images are
                                           stored (with a trailing '/')
   showpreview              0              show preview images ?
                                           0 = no
                                           1 = yes
   compressed_preview_file  -----          filename of the zip-compressed preview
                                           file (only 'zip' supported !)
   compressed_previews      0              use zip-compressed previews ?
                                           0 = no
                                           1 = yes
                                           (compressed_preview_file must be set 
                                           correctly, if enabled !!!)
   font_family              Helvetica      family of default-font
   font_size                14             point-size of default-font
   font_style               1              style of default-font
                                           0 = Normal
                                           1 = Bold
   gl_font_family           Courier        family of gamelist-font
   gl_font_size             12             point-size of gamelist-font
   gl_font_style            1              style of gamelist-font 
                                           0 = Normal
                                           1 = Bold
   mainwidget_x             20             mainwidget's x-position
   mainwidget_y             50             mainwidget's y-position
   mainwidget_w             600            mainwidget's width
   mainwidget_h             400            mainwidget's height
   pvw_x                    630            preview-window's x-position
   pvw_y                    50             preview-window's y-position
   gamename_pos             0              GAMENAME's column-position
   gamename_width           320            GAMENAME's column-width
   rom_pos                  1              ROM's column-position
   rom_width                60             ROM's column-width
   status_pos               2              STATUS' column-position
   status_width             50             STATUS' column-width
   remarks_pos              3              REMARKS' column-position
   remarks_width            60             REMARKS' column-width
   options_pos              4              OPTIONS' column-position
   options_width            100            OPTIONS' column-width
   rating_pos               5              RATING's column-position
   rating_width             50             RATING's column-width
   show_correct             1              show games with status "CO" ?
                                           0 = no
                                           1 = yes
   show_maywork             1              show games with status "MW" ?
                                           0 = no
                                           1 = yes
   show_incorrect           1              show games with status "IN" ?
                                           0 = no
                                           1 = yes
   show_notfound            1              show games with status "NF" ?
                                           0 = no
                                           1 = yes
   show_unknown             1              show games with status "NA" ?
                                           0 = no
                                           1 = yes
   version_major            0              major version number
   version_minor            0              minor version number
   version_beta             0              beta version number (0 = NO beta)
   remove_logs              1              remove log files on exit (1) or keep
                                           them (0) ?
   avail_color              #000000        gamelist color for available games
   avail_color_high         #FFFFFF        ---- " ---- (highlighted)
   unavail_color            #BEBEBE        gamelist color for unavailable games
   unavail_color_high       #BEBEBE        ---- " ---- (highlighted)
   specify_color_by         0              which color specification method is
                                           to be used ? 0 = specify colors by
                                           rom-availability, 1 = specify colors
                                           by rom-status
   color_correct            #009600        gamelist color for games with status
                                           "CO"
   color_correct_high       #009600        gamelist color for games with status
                                           "CO" (highlighted)
   color_maywork            #FFC800        gamelist color for games with status
                                           "MW"
   color_maywork_high       #FFC800        gamelist color for games with status
                                           "MW" (highlighted)
   color_incorrect          #FF0000        gamelist color for games with status
                                           "IN"
   color_incorrect_high     #FF0000        gamelist color for games with status
                                           "IN" (highlighted)
   color_notfound           #FF0000        gamelist color for games with status
                                           "NF"
   color_notfound_high      #FF0000        gamelist color for games with status
                                           "NF" (highlighted)
   color_unknown            #FF6400        gamelist color for games with status
                                           "NA"
   color_unknown_high       #FF6400        gamelist color for games with status
                                           "NA" (highlighted)

   Note: you can specifiy the color-settings in two ways - either in #RRGGBB
   format, specifying the red-green-blue value, or as a 'named' color (named 
   colors have to be defined in /usr/X11/lib/X11/rgb.txt - i.e. grey, black
   red, green etc.) !

   But best is to leave the config-file untouched and instead edit all setting
   from within qmamecat's options-dialog.

   Take mamecatrc.sample (in this directory) as a sample options file.

7) Catalog and ROM-status cache format

   Catalog format:

   Every entry (one for each game, one per line) has the following form:

   <rom><rating><remarks>[<gameopts>]

   <rom>           the rom-image name
   <rating>        expresses your personal opinion about the game (a decimal
                   value: 0 - 6); the way you interprete this is controlled by
                   some of the settings of the MAMECAT configuration (see 
                   section 6)
   <remarks>       free-form text for remarks (shouldn't exceed 80 characters)
   <gameopts>      this is an optional field; if set, it specifies game-specific
                   options (which are passed to X-Mame only for *this* game);
                   if you want to pass any options to *each* game, please use
                   the <options> setting in .mamecatrc instead (see section 6)

   The file mamecat.cat.sample (in this directory) contains a sample catalog.

   ROM-status cache format:

   Every entry (one for each game, one per line) has the following form:

   <rom> <rom_availability_flag> <rom_status>

   <rom>                    the rom-image name
   <rom_availability_flag>  1 or 0 (for "available" or "not available")
   <rom_status>             the numeric (internal) representation of the
                            rom-status

   NOTE: You should never edit this file manually !

8) ROM status

   Since v0.27 a 'ROM-status' is determined if you enable the option 
   <thorough_romcheck> (which will cause qmamecat to use the -verifyroms option
   of xmame to analyze the ROM-status thoroughly at startup and at every 
   'refresh' !).

   Since v0.39 <thorough_romcheck> is ALWAYS enabled and you cannot change it
   "externally". That is, <thorough_romcheck> is no longer an option, although
   it still exists in the options-struct...

   Note that this feature requires xmame 0.34rc1.1 (or above) to work properly,
   because it relies on the output of "-verifyroms" which has been changed a bit
   since this (xmame) version. If you use <thorough_romcheck> with an older
   xmame version, the analysis may not be correct ! See also section 3.

   The status-abbreviations and their meanings are:

   NA  'N'ot 'A'pplicable = unknown ROM-status (this will be displayed, if 
       <thorough_romcheck> is disabled or the ROM-status could not be 
       determined, for example because it is a game that does not have an
       explicit rom-set like "pong" !)
   CO  'CO'rrect = the ROM image is correct and should work fine
   MW  'M'ay 'W'ork = the ROM image is incorrect, but may work (most of the time
       only the checksum is incorrect)
   IN  'IN'correct = the ROM image is incorrect or corrupted and will definitely
       NOT work
   NF  'N'ot 'F'ound = there is no ROM-image for this game in your ROM-path
       (you should check your ROM-path, if you think it should be available)

9) Printing

   Since v0.30 a print function has been added. The generated output is
   postscript; if you don't have a postscript printer (like me :-), make
   sure you have a filter setup for your printer. I recommend 'apsfilter',
   which you can get from ftp.suse.com !

10) Contacting the author(s)

   Bug reports and questions specific to MAMECAT should be sent to
   rene.reucher@cpx-ssc.de directly, not to the xmame mailing-list.
   Feel free to send me any suggestions for enhancements and take a look at the
   CREDITS file to see who is responsible for which part of MAMECAT.

   Also, I would like to maintain a list of known working platforms/
   configurations, so please drop me a note even if you are successful. 
   Tell me under which circumstances (OS, OS-release etc.) you were successful,
   I will then add you to a list on the MAMECAT homepage, so that someone with
   a similar configuration would be able to contact you... I have only access to
   a Linux-box, so I can't test on any potential target-platform.

11) Special notes for new versions of MAMECAT

   This section is mainly for those who already used MAMECAT prior to "THIS"
   release. It offers some notes about changes that might affect an earlier 
   installation and/or changes in "code-behaviour" you should be aware of.

   v0.41

   - Qt 1.4x and Qt 2.0.x are no longer supported, you need Qt 2.1.0 (or above) 
     from now on to compile and run qmamecat !!! The main reasons for this step 
     are the new preview check dialog, which uses some Qt 2.xx features which are
     incompatible with Qt 1.4x and the new font determination code (which 
     requires Qt 2.1.0 at least). Sorry, if that bothers anybody.

   - the makefile-structure has been totally reworked. Please see section 3
     for more information.

   - we now also support FreeBSD besides Linux and SunOS (see doc/CREDITS for a
     list of OS-specific maintainers, others welcome !!!)

   - due to all these changes we had to end support for the the curses-version !

   - the new qmsetup tool should NOT be started manually, it won't work
     correctly in this case (exit immediatly if accidently started); it is
     launched by qmamecat ON DEMAND if needed.

12) License

   MAMECAT is distributed under the GNU General Public License (version 2 and
   above). For more information please take a look at the file COPYING (should
   be in this directory; if not, write to the Free Software Foundation, Inc.,
   59 Temple Place, Suite 330, Boston, MA 02111-1307, USA).

   The unzip-code (unzip.[ch], inflate.[ch] and types.h in src/unzip) has been
   taken from xmame's source. AFAIK, the original code is copyrighted by Mark 
   Adler - if i'm wrong or missing somebody, please let me know !!!

Have fun,

The MAMECAT-Team
