Qdig - Quick Digital Image Gallery
==================================
README.txt

Qdig is an easy-to-use PHP script that presents your digital
image files as an online gallery or set of galleries dynamically
from a directory or tree of directories.

Qdig's home on the web is at http://qdig.sourceforge.net/

Qdig installation is simple -- just put the script in a directory
that contains some image files and/or subdirectories with image
files, then browse that directory's URL.  Qdig is a one-file program
and doesn't require a DBMS.

Qdig can generate thumbnails and smaller versions of large images
using either Image Magick or PHP's GD extensions.  Writing converted
(resampled) images to disk requires some simple additional setup
steps (create a directory and set permissions on it twice).  Shell
access is preferred, but not required, to perform these steps.

Gallery management is also easy.  Most users can completely manage
their galleries using their favorite FTP or SCP file management program.

Starting with version 1.2.0 you can edit image captions on-the-fly.
This feature uses admin.php, the Qdig Gallery Management Script.  The
admin script is also easy to install; typically you only need to edit
it and add your username and password.

Featureful, Adaptable, and Usable

Qdig has features to help you present your images the way you want them
presented.  You can easily add image captions; you can offer each image
in multiple sizes; you can change the color scheme; you can enable,
disable, and choose the placement of various gallery elements; you can
choose the size, quality level and placement of thumbnail images.  These
are just examples of the dozens of configuration settings, which are
briefly documented with comments in the script.

The script works stand-alone or you can include() it within another PHP
script and it will automatically adapt by suppressing the HTML header
and footer.  When this happens, the script will take on the style of the
calling page because the CSS style elements for a stand-alone gallery
are in the HTML header.

Qdig is designed with usability in mind.  Resampling images to similar
sizes gives your gallery a consistent look and conserves bandwidth.
Gallery visitors can be allowed to change some preferences to suit
themselves.  Qdig gallery pages take up minimal space in the browser
window.  Qdig tries to be efficient with valuable screen pixels,
so visitors can scroll less and view images more.


INSTALLATION, LICENSE, and CHANGELOG
====================================

See INSTALL.txt, LICENSE.txt, and CHANGELOG.txt


HOW QDIG WORKS
==============

Fortunately you don't need to know how the script works in order to
use it.  Just in case you're curious anyway, here's some information:

The script reads the directory and builds an alphanumerically-sorted
list of image files it finds. If an image filename is passed to the
script then that image is displayed, otherwise the first image in the
directory is automatically chosen for display.

When an image is displayed it's hyperlinked to the next image, so users
can lazily click on each image as it appears to view the entire gallery.
Optionally, the last image links (wraps) back to the first.  Another
option links any resampled image to the full sized version, similar
to some other gallery scripts.

`Previous Image' and `Next Image' links are available.  At each end of the
list, `Last Image' and `First Image' links appear.  A link to the full-
sized image can automatically appear if the displayed image is a resampled
version.  A Site Link to your site's home page may also be displayed.

Directories are similarly read from disk and presented to the visitor
as directory navigation links.  Only directories that contain at least
one image or subdirectory are considered gallery directories.  Your
current location in the tree is displayed, as well as links to the
parent directory, if any, and any subdirectories that are gallery
directories.  Directory navigation may be disabled.  You can also force
a subdirectory to be the topmost gallery directory (a chrooted gallery),
which is sometimes useful when you run Qdig from within another script.

Qdig should be easy to integrate into your web site or portal/content
management system. It generates standards-compliant HTML 4 output using
the following tags: <a>, <img>, <center>, <small>, <div>, <table>, <tr>,
<td>, <b>, and sometimes <br>. You should be able to easily include() it
within a portal such as PHP-Nuke, PostNuke, Geeklog and the many others.


QDIG DESIGN GOALS
=================

Ease-of-use
  Qdig should be very quick and simple to install and to use, at least
  for basic functionality.  Once Qdig is installed, galleries should be
  easy to manage, even for inexperienced computer users.

Security
  Qdig should be able to work with as little security risk as possible.
  The script works with PHP's `register_globals' flag turned off.
  Generating thumbnails, alternate-sized images and .txt files for
  captions requires write permissions, but only within the directory
  tree specified for the purpose of storing those files.

Standards-compliance
  The generated output and the script itself should comply to applicable
  standards (XHTML 1.0 Transitional and PEAR Coding Standards respectively).


$Id: README.txt,v 1.6 2004/05/29 02:49:17 haganfox Exp $
