indexpage.pl
============

indexpage.pl generates one or more index pages and the corresponding
thumbnails for displaying images from a digital camera or similar on
the web (as of right now, only .jpg images are recognized). If there
are more images available than will fit on one page with the specified
number of rows and columns, indexpage.pl will generate more than one
page, each with a navigator to easily reach the other pages. By
default, the pages will be called "index.html", "2.html", "3.html",
and so on.

There are lots of configuration options determining how the generated
pages should look (see below). Image descriptions are read from a
file, eliminating the need to ever edit the files after generating
them; they can always be regenerated for ease of maintaining.

indexpage.pl may be distributed according to the GNU GPL version 2 or
later. See the file COPYING for more information. If you make any
modifications to this, I'd like to see them. The latest version can
always be found at
http://www.lysator.liu.se/~unicorn/hacks/indexpage/.

Hans Persson <unicorn@lysator.liu.se>


Installation
------------

Copy indexpage.pl to where you want it. You might need to change the
first line of the script to indicate where your Perl interpreter is
located. 


Prerequisites
-------------

 * Perl

 * The Image::Size Perl module. If you don't have that installed, you
   can install it like this:

       perl -MCPAN -e "install Image::Size"

   (You might need to be root for this to work.)

   You can also run the script "installperlmodules.sh" to install all
   modules needed to run indexpage.pl. You might still need to be
   root. 

 * The ImageMagick package, or at least the "convert" program from it.
   ImageMagick can be found at
   ftp://ftp.simplesystems.org/pub/ImageMagick/


Usage
-----

    indexpage.pl [options]

When started, indexpage.pl will read settings first from the standard
config file, then from the user-specified config file (if any), and
finally from any command line options. If the same option is specified
in more than one place, the last definition is used.

Specifying files

The standard config file is ~/.indexpagerc. I tend to keep a config
file in each of my image directories to make it easy to regenerate the
pages with the same settings as last time.

    --configfile=file         If specified, settings will be read from
                              "file". Note that even if this option is
                              given, ~/.indexpagerc is read.

To create web pages, indexpage.pl needs a set of images to work with.
These can be located in any directory. 

    --indir=path              Use "path" to find the images. Defaults
                              to the current directory.

The default behaviour is that indexpage.pl copies the images to a
different directory.

    --outdir=path             Put the generated web pages and images
                              in "path". Defaults to the current
                              directory. 

In the directory specified with the outdir option, an "images"
directory will be created and all images in indir will be copied to
there. The web pages will be generated in the same directory as the
"images" subdirectory.

It is also possible to make indexpage.pl operate on the images in a
directory without making copies of them.

    --inplace
    --noinplace               Decide if images should be used in place
                              or if new ones should be created in the
                              output directory. If this is true,
                              outdir is set to the same as indir.
                              Defaults to --noinplace.

If the inplace option is given, no images will be copied, and no
"images" subdirectory will be created. If the inplace option is given,
the value of outdir will be set to indir regardless of if it is given
a value or not.

Normally, indexpage.pl creates a set of thumbnail images in a "thumbs"
subdirectory in outdir and then makes links from the thumbnails to the
original images. It is also possible to get links from the web pages
directly to the original images.

    --makethumbs
    --nomakethumbs            Decide whether thumbnail images should
                              be used or if the input images should be
                              put directly on the web pages. Defaults
                              to --makethumbs.

    --thumbsize=number        Use "number" as the maximum size for the
                              thumbnail images (for their widest
                              orientation). Defaults to 120.

Descriptions for the images are read from a descriptions file. By
default, "descriptions.txt" in the current directory is used.

    --descfile=file           Use "file" as descriptions for the
                              images. 

If no such file is found, one is created with the correct labels. You
just need to fill in suitable descriptions for the images and rerun
the script. The format of the descriptions file is one line per image,
like this:

    imagename       Descriptive text

Note that imagename should be given without the file name suffix
(".jpg"). The image name and the description should be separated by
spaces or tabs. It is also possible not to use a descriptions file at
all. Beware that if you change the value of the imagere option that
might affect the name of the images that will be used to look up
descriptions in the descriptions file.

    --desc
    --nodesc                  Decide if a descriptions file should be
                              used or not. The default is to use one.

Controlling the layout

There are various options that control the layout of the generated web
pages.

    --title=string            Use "string" as the title of the
                              generated web pages.

    --rows=number             Generate "number" rows of thumbnails on
                              each web page. Defaults to 4.

    --cols=number             Generate "number" columns of thumbnails
                              on each web page. Defaults to 3.

    --order=list              If present, put the images specified in
                              "list" (without the file name suffix) in
                              the specified order on the generated
                              pages. It is not necessary to list all
                              images, the ones not listed will appear
                              in an unspecified order. Note that
                              creative use on the imagere option might
                              affect what is considered the file name.
                              No default.

    --htmlhead=html           Specify what HTML code should be printed
                              at the beginning of each web page.
                              Defaults to:

                                  <html>
                                  <head>
                                  <title>%(title)s</title>
                                  </head>
                                  <body>
                                  <h1>%(title)s</h1>

                              You can set this to anything you like,
                              but it must be specified on one line. To
                              put line breaks in the output, write
                              "\n" in the input. "%(title)s" can be
                              used to put in the value of the title
                              option (or any other config variable). 

    --htmlfoot=html           Specify what HTML code should be printed
                              at the end of each web page. Defaults
                              to:

                                  </body>
                                  </html>

                              The same rules apply to changing this as
                              to the htmlhead option.

    --header=text             If present, print "text" before all
                              thumbnails on each web page. Variables
                              can be used in the same way as with the
                              htmlhead option. No default.

    --footer=text             If present, print "text" after all
                              thumbnails on each web page. Variables
                              can be used in the same way as with the
                              htmlhead option. No default.

Misc options

If your images come from a digital camera, they probably have boring
names line asdf1234-qwe.jpg or things like this, and the only thing
that is different for different files is the digits.

    --imagere=regexp          Use "regexp" to figure out what part of
                              the image file names that should be
                              used for image file names.

By changing the value of imagere, you can fine-tune how indexpage.pl
determines what part of the input file names to use as output file
names. The default value for imagere is ^(.*?)\..*$ (a regular
expression that matches everything from the beginning of the string
up, but not including, the first period, then a period, then
anything). The parentheses determine what is used as the output image
file name. Be default, everything up to the first dot in the file name
will be used. If you have file names like those from a digital camera
mentioned above, you can set imagere to something like
^[^\d]*(\d+)[^\d]*\..*$ to get only the digits in the above example as
the output file name (".jpg" will be attached automatically). 

Note that if you change the value of the imagere option, you might
have to change the labels used in the descriptions file.

    --convert=file            Specify where the convert program is
                              located, if it isn't in your $PATH.
                              Defaults to "convert".

It is possible to change the names of the files generated.

    --index
    --noindex                 Specify if the first file generated
                              should be called "index.html" or not.
                              Defaults to --index.

    --filenameprefix          Specify a string to begin each file name
                              with. No default.

    --version                 Print the version number of
                              indexpage.pl.

Hans Persson <unicorn@lysator.liu.se>
