
MiG - A general purpose photo gallery management system.

Copyright (C) 2000 Daniel M. Lowe	<dan@tangledhelix.com>


LICENSE INFORMATION
-------------------

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.


REQUIREMENTS
------------

This package requires a web server which supports PHP (http://www.php.net).
Any recent version of PHP3 or any version of PHP4 should work.  The
development platform is Linux, so this code tends to assume a Unix-like
environment.  As such it may or may not work (and has not been tested) on
non-unix-like platforms.  This package is developed using PHP3 and does not
have any PHP4-specific code.

(Windows users, please see the file "docs/Windows.txt" for more information.)

The "mkGallery" utility (used to generate thumbnail images) requires Perl
(http://www.perl.org) and ImageMagick (http://www.imagemagick.org).
You can use MiG without Perl or ImageMagick - but in that case you may
have to create your own thumbnails and not use mkGallery.  See the file
docs/Utilities.txt.  Since thumbnails are optional, you don't even need to
generate them if you don't want to or it's not convenient for you.

The "jhead" utility which is called by mkGallery for EXIF header parsing is
a C source code file - you will need to compile it before using it.  See the
file "docs/Utilities.txt" for more information.



INSTALLATION AND BASICS
-----------------------

Installation is fairly straightforward.

1. Unpack this archive and enter the resulting directory.

     gzip -dc mig-x.xx.tar.gz | tar xf -
     cd mig-x.xx

   (Where "x.xx" is the version number, such as "0.94")

2. Run the install script "install.sh" and follow the directions.

     ./install.sh

3. Enter the installation directory (which you specified during the
   installation).

     cd /usr/local/apache/htdocs/mig

4. Review the file "mig.cfg.default".  If you want to make any changes,
   make them and then copy the file to "mig.cfg".  The reason to do this
   is simple: future installations / upgrades will copy over mig.cfg.default
   with whatever is packaged with that version of MiG.   The mig.cfg file
   will never be automatically over-written by the install script.

     vim mig.cfg.default
       [ or if you are a heathen, use some other text editor :-) ]
       [ make desired changes ]
     cp mig.cfg.default mig.cfg

   Or, if you are upgrading, it's a good idea to review mig.cfg.default to
   see if there is anything new that you will want to add to your mig.cfg.

5. Enter the albums directory.

     cd albums

6. Create any folders and subfolders you want for your own albums, and
   copy your images into them.

     mkdir Trips
     mkdir Trips/Alberta,_Canada
     mkdir Trips/Lake_Tahoe,_California

     mkdir House
     mkdir House/Living\ Room
     mkdir House/Dining\ Room

   You can of course, also do this with FTP, scp, or your favorite file
   handling method.

   A note about spaces in gallery names:  If there is a space embedded in
   the directory name, it is left as a space.  If there's an underscore (_)
   in a directory name, it is displayed to the viewer as a space.  So you
   can use whichever you like in your galleries.  I know some people don't
   like embedding spaces in file/directory names, but having it rendered
   as a space is much nicer looking in the browser.

   A note about files:  Basically, any PNG, JPG or GIF file will be shown.
   That is, any file with an extension of .gif .jpg .jpe .jpeg or .gif.
   Note that case is irrelevant so ".GIF" is the same as ".gif" or ".Gif".

   A note about file permissions: MiG makes no attempt to modify or check
   the file permissions in your album subdirectory.  It is left to you to
   make sure the web server has the ability to read these files.  On most
   systems this means making sure the directories are at least 0755 (which
   is drwxr-xr-x) and files are at least 0644 (-rw-r--r--).  However, many
   people run their systems in such a way that those modes are considered
   dangerous to them, and I don't make any assumptions.  Please validate
   the permissions on your album files to make sure MiG can read them.

   MiG does set file permissions on the files it actually installs (the
   PHP files themselves, mig.cfg.default, the templates, etc).  If these
   are unsatisfactory to you (they should be perfectly fine for everyone
   as far as I can see), please let me know, and of course you can reset
   their permissions as you see fit on your system.

   Thumbnails are basically seen by MiG as anything that matches the basic
   pattern "filename_th.EXT"... so myhouse_th.gif will be viewed as a
   thumbnail.  The basic rule of thumb is, don't use the string "_th"
   in your filenames if you can possibly help it.

   **  Note, as of 0.90 this behavior changed.  This is still true of the
   **  default settings, but you now have the ability to control the format
   **  of thumbnail filenames.  See docs/Utilities.txt.

   You can use spaces (or, as above, underscores) in filenames just like
   you can do with directory names.  Underscores in filenames will be
   shown as-is though, they are not re-mapped to be displayed as a space.

7. You probably want to create thumbnails.  You can use the mkGallery
   script found in the "util" subdirectory.  Note that it requires Perl
   and the ImageMagick suite (see the file docs/Utilities.txt).

   You don't have to use mkGallery - you can make your own thumbnails if
   you want.  Just have the filenames match the pattern shown above.  So...

     myHouse.jpg	= myHouse_th.jpg
     Livingroom.JPG	= Livingroom_th.JPG

   Case does matter for the "_th" - it must be lowercase!

   To create thumbnails, in a nutshell:

     cd /usr/local/apache/htdocs/gallery/Trips/Lake_Tahoe,_California
     ../../util/mkGallery -a -t

   See the file "docs/Utilities.txt" for more about mkGallery.  You can get
   a listing of available options by invoking "mkGallery -h".

   **  Note that not all thumbnails have to use _th as their "unique" part
   **  anymore.  See docs/Utilities.txt.  You can make them anything you
   **  want, and can even "prefix" them to the filename instead of suffixing
   **  them.

   For mkGallery to create thumbnails, "convert" from the ImageMagick suite
   must be in your $PATH.

   If you elect not to use thumbnails, a generic "image" icon will be
   used in place of a thumbnail image, so creating thumbnails is not
   mandatory (it just makes for a nicer presentation for people viewing
   your album).

   mkGallery will only bother with the PNG, GIF or JPEG files it finds
   in the current directory (.gif .jpg .jpe .jpeg and .png).

8. Go to http://www.yourserver.com/mig/ (or wherever you happened to
   install it) to view your gallery with your web browser.

   You may have to tell your web server that "index.php" (or index.php3)
   is a valid default page.  Apache users will need to add the filename
   to the "DirectoryIndex" directive (adding to the end of the line in
   your httpd.conf and running "apachectl graceful" as root is probably
   the way to do that).  Other changes to Apache might be required to
   support PHP.  How to get PHP to work in general is left as an exercise
   to the reader, but www.php.net and www.apache.org should have the
   information needed.


OPTIONAL CUSTOMIZATION
----------------------

1. HTML templates (and colors)

   You may optionally edit the HTML templates found in the "templates"
   subdirectory.  See the file docs/Templates.txt for more information.

2. Hidden folders and hidden files

   If you have some reason to hide particular files or folders from general
   view (i.e. it can be viewed but only with an exact URL, you don't want
   people wandering in there from the general public) you can list those
   items in a file called "mig.cf" in the relevant folder.  As an
   example, look at "albums/Example_Gallery/mig.cf" (if you installed the
   Example Gallery).

   To add hidden items, just add a <Hidden> element, like this:

     <Hidden>
     hidden_folder
     another_hidden_folder
     </Hidden>

   Users of Apache will find this configuration format pretty familiar.
   Tag elements like <Hidden> must be at the beginning of a line!

   See the file docs/mig_cf.txt for information about the format of mig.cf.

   (Note for users upgrading from MiG 0.83 or earlier - the format has
   changed, as you'd have noticed already.  The install script probably
   already updated your metafiles such as .hidden.txt but if not, you can
   do so by hand by running util/convert-metafiles).

3. Comments

   You can optionally add comments for any image you wish.  You don't have
   to add comments at all.  The comments are stored in "mig.cf" in the
   same directory as the image in question.

   Comments are shown in a box below the image in image views.  In
   thumbnail views, they are shown as the ALT tag text.

   As an example, let's say you had files "house.jpg", "car.gif" and
   "dog.jpg".  Let's say you wanted a comment on the house and the dog,
   but nothing in particular to say about the car.  You would add markup
   like this to mig.cf:

     <Comment "house.jpg">
     This is my house, which I bought in the fall of 1998.
     </Comment>

     <Comment "dog.jpg">
     This is the dog we had when I was growing up.  She was a lot of
     fun!  Sadly, she died when I was 12 years old (she had cancer).
     We had other dogs afterward, but none of them were as much fun.
     </Comment>

     <Comment "neil.jpg">
     My friend Neil, goofing off as usual.
     </Comment>

   (If you want to save yourself some typing you can use the "-c"
   option to util/mkGallery to create a blank comments template.
   See docs/Utilities.txt for more information.)

   You can have as many lines as you want for the description.  The key
   is that the description must be enclosed inside the
   <Comment>...</Comment> structure.  The tags such as <Comment> and
   </Comment> MUST be at the start of a new line.
   
   There are examples in albums/Example_Gallery/mig.cf (if you installed
   the example gallery).

   See the file docs/mig_cf.txt for information about the format of mig.cf.

   (Note for users upgrading from MiG 0.83 or earlier - the format has
   changed, as you'd have noticed already.  The install script probably
   already updated your metafiles such as .comments.txt but if not, you can
   do so by hand by running util/convert-metafiles).

4. EXIF header information

   You can build EXIF comment files (exif.inf) using mkGallery and the "-e"
   option.  See the file docs/Utilities.txt.  Note that you must compile the
   (included) "jhead" utility from Matthias Wandel before the -e option
   will function.  Compiling jhead is probably as easy as this:

      cd util ; make jhead-clean ; make jhead

   Since only JPEG files support EXIF headers, mkGallery will only look
   at JPEG files when building the EXIF files.  Much more than the
   comments themselves are stored in these exif.inf files, and future
   versions of MiG may parse more information from these files than it
   currently does.  Right now all MiG knows how to extract from the
   exif.inf file is embedded comments.

   (Note for users upgrading from MiG 0.83 or earlier - the filename has
   changed, as you'd have noticed already.  The install script probably
   already updated your metafiles such as .exif_comments.txt but if not,
   you can do so by hand by running util/convert-metafiles.  The only change
   for EXIF files is the filename, just rename to 'exif.inf').

5. Style sheets

   You can modify the file templates/style.css if you want to change the
   text/css style (which is what determines link coloring).  If you don't
   want to use the style.css file, remove the #include directive from
   the HTML templates which includes it in the template.  For more
   information see docs/Templates.txt.

6. Item sorting

   You can define your own sort order (rather than relying on alphabetical
   sorting) - see docs/mig_cf.txt.


BUG REPORTING
-------------

Report any bugs to mig-bugs@tangledhelix.com. 


EMAIL LISTS
-----------

There are two email lists for MiG users.  Visit the indicated URLs for more
information about each list.

  Announcements only	http://snoopy.net/mailman/listinfo/mig-announce

  General discussion	http://snoopy.net/mailman/listinfo/mig-users

