Author: Stefan Spaeth
Description: Describes the options available for createPhotoWebPages.pl

# createPhotoWebPages.pl - Options

back to main page

Quite a number of options are available for createPhotoWebPages.pl. They control the way the script processes images and HTML pages. The actual appearance of the HTML pages is mainly determined by the configuration file entries.

The options can be partitioned into four groups:

- General Options
- Program Options
- Sort Options
- Rename Options

## Execution of createPhotoWebPages.pl

The script is executed as follows:
`createPhotoWebPages.pl [Options] Configurationfilename [Pathnames]`
"Configurationfilename" is the name of the configuration file. The "path names" are only required when using the "-scan"-Option and are considered a user error in all other cases.

The options are described in more detail in the following sections. Note that there is a long descriptive format as well as a single letter abbreviation available for each option.

## General Options

These are all options which may be given at any time (altough they might not do anything in some situations).

- -verbose
  -v
  By default only important messages and error messages are printed to the console. Informational messages and warnings are only forced to be printed to the console if the verbose option is applied. Note, however, that all messages are anyway logged in a log file. The log file gets the same name as the configuration file, with suffix ".log" as a file extension. It is created in the directory where the script is executed.
- -help
  -h
  This option displays a help page. The script is stopped without further action after displaying the help page.
- -force
  -f
  This option enables or forces the "override/overwrite" mode for images and associated HTML pages that do already exist. In normal operation, images and associated HTML pages are only created if they do not yet exist. If image and HTML files do already exist they are not overwritten by default. The same is true for a potentially existing "CSS-Stylesheet" file.
  Note that the thumbnail HTML pages, as well as the log file or configuration file are overwritten in any case.
  The override mode is automatically activated for certain actions, like image rotation, or file name changes.
  The "-force" option should be used if all images and HTML pages should be created from scratch. This may for example be necessary for HTML pages whenever textual comments for an image have been changed in the configuration file and need to be updated in the associated HTML file. In the case of images the force option is normally only required if the content of the image has changed or if the size of the generated images should be changed.
  In most cases it is recommended to combine the "-force" option with either or both of the "-images" and "-html" option.
- -write
  -w
  This option forces the overwriting of the configuration file. In regular operation this file is only recreated if the options "-scan" and/or "-rename" are used. The configuration file is overwritten without any further notice.

## Program Options

These are the main operating options which define the working mode of the script. Several of these options may be combined. If none of these options is given then the script automatically assumes the option combination "-images -html".

- -scan
  -s
  This option denotes the scan or image search mode. It is used to scan directories and examine files in order to identify existing images and to create a new configuration selection file based on those images. By default, this option alone does not lead to the creation of any images or HTML files. However, the combination with the options "-images" and/or "-html" would start image and/or HTML file creation as well. If the "-rename" option is also given then the original image file names may also be modified or changed completely (if desired).
  The sort option "-order" may only be combined with the "-scan" option.
- -rename
  -r
  The "-rename" option assists in the renaming of image file names. It also ensures that already existing derived image or HTML files are updated accordingly. Existing files are either renamed or re-created (e.g. to update file links). The basic operation comprises of the adaptation of the original image file name to the text given in the "IMAGE_NAME" configuration file entry. This is done using a number of configurable rules which are described in a separate rule document.
  Two additional combinable options (which are described below in the section rename options) assist in the addition of file name prefixes and in the conversion of the file extension from upper case to the more common Unix convention lower case.
- -html
  -t
  This option is used whenever the explicit (re-)generation of HTML pages is desired. If the "-images" option is omitted at the same time then no images are generated (even if they do not exist). If the generation of HTML files should be enforced then the "-force" option must be activated at the same time.
  This option must be activated during image scan mode ("-scan" option) if HTML files should be generated.
- -images
  -image
  -i
  This option is used whenever the explicit re-generation of images is desired. If the "-html" option is omitted at the same time then no HTML files are generated (even if they do not exist). If the generation of image files should be enforced then the "-force" option must be activated at the same time.
  This option must be activated during image scan mode ("-scan" option) if image files should be generated.

The following options may only be used in combination with certain main options.

## Sort Options

The sort options may only be used in conjunction with the image scan mode ("-scan" option). If no sort option is given then the order of the images in the configuration file reflects the order in which the image files are found in the course of the scan operation.

- -order name
  -order date
  -o name
  -o date
  Two sorting variants can be chosen. The "name" variant sorts lexically according to image file name or file path, whereas "date" sorts according to image recording date.
  The "name" does always work as expected, whereas the "date" variant relies on available date information.
  The "date" variant actually requires images in JPEG format to work properly. If available, the EXIF information of the JPEG image file is evaluated. If available, the EXIF "Date/Time" entry is used to sort the image files. In some cases this EXIF entry may not be available or deleted (e.g. by an image processing tool). In those cases, the "date" variant delivers incorrect sorting (all incomplete files carry the default date information "00/00/00"). The "date" variant should therefore only be used when appropriate.

Note:
After images have been downloaded from a digital camera they can normally be easily processed with the "name" variant. The alphanumeric names of the images do already reflect the date/time information in their file name (many cameras even allow to influence the naming style).
The "date" variant is mostly interesting if images from different cameras or image series should be brought into a date/time context. It is, however, a prerequisite that the "Date/Time" EXIF entry exists and contains useful information.
The usage of the "date" variant also implies the usage of the "jhead" utility program.

## Rename Options

All rename options do only work in connection with the rename mode ("-rename" option). The prefix option ("-prefix") may also be used in combination with the image scan mode ("-scan" option).

- -prefix
  -p
  This option is extremely helpful and ensures that image files may still be sorted lexically even after applying readable names. The option simply adds a two letter prefix (with additional underscore character) in front of each image file name. The prefix is created as follows:
  `aa_, ab_, ac_, ..., az_, ba_, ..., zy_, zz_, aa_`
  As you can easily see, this limits the number of unique file names to 26x26=676. However, in normal applications this limitation is less severe, as images are typically distributed in multiple directories.
  In all later rename runs ("-rename" option) the prefix is always preserved as is (even if the rest of the file name itself gets a completely different name). (see also IMG_NAME_NO_ALPHA_PREFIX entry).
  It is possible to combine the "-rename" option with the "-prefix" option without entering the scan mode. In that case a new prefix is generated for each image file name. The order in which the prefix is applied is given by the order in which the images are listed in the configuration selection file. Note that this combination of option should be applied with care. The existing order is destroyed and cannot be restored.
- -extension
  -ext
  -e
  This option allows to quickly convert file extensions written in upper case letters into file extensions written in lower case letters (e.g. ".jpg" instead of ".JPG"). The upper case letters (which are less desireable in a Unix system) tend to appear in DOS/Windows systems or may be created inside some digital cameras).

back to top, back to main page