llgal - On-line gallery generator - How-To?

# llgal How-To?

This How-To is available on-line and in the tarball and distribution packages.

## Basics

### How do I use llgal?

Place some images and movies in a directory and simply run `llgal` inside it. It will generate an index file and some slides.

### How do I modify a gallery?

You may add or remove some images in the working directory, and re-run `llgal` with different options to update the gallery contents or layout. If an image has been modified, you may have to force the regeneration of thumbnails and scaled images with `-f`.

### How do I reduce the size of the slides?

If your images are large, you should try

      llgal --sy 480

to limit the height of the image to 480 pixels in slides. Note that a click on the slide will actually open the original full-size image. You may even ignore the original images completely by passing `--nf` so as to remove links from slides' scaled images to the original unscaled full images.

### How do I set the title and captions?

You may set the title on the command line through:

      llgal --title "My title"

To change captions, the easiest way is to ask `llgal` to generate captions first, with:

      llgal --gc

Then, you may edit the captions file (`.llgal/captions`) to update all captions. You then run `llgal` again, it will detect the existence of the captions file and use it.

      llgal

## Captions and special slides

### How do I generate captions from images?

When generating the captions file with `--gc`, `llgal` may automatically generate several fields for each image. Available fields are image comments, filename and image timestamp. `llgal` will try to generate each field and concat them to create the caption. To generate captions from the filename only, run:

      llgal --gc --cf

To generate captions from the image timestamp (extracted from Exif tags when existing) and filename:

      llgal --gc --cf --ct

To generate captions from the image comments (extract from JFIF or Exif), timestamp and filename:

      llgal --gc --cc --cf --ct

These commands will generate a captions file that you might then use when generating the gallery. You might also directly generate captions during the gallery generation through something like:

      llgal --cc --ct

Note that if a captions file exists, command line options about captions generation are omitted. Also note that `--cc` and `--ct` require the Image::ExifTool Perl module to be installed.

### How do I add a slide containing some text or link?

After generating the captions file with `--gc`, you might add a special slide containing only some text by inserting the following line in the file:

    TXT: the text that is shown in the slide ---- the caption under the slide

Regenerating the gallery will then add this slide. The following line add a special slide with a link instead of plain text:

    LNK: the url ---- the label of the link in the slide ---- the caption under the slide

If you do not want those slides containing a single link or text to appear like this, you may use `-L` so that they will be listed as a text line in the index. You may also use `LNKNOSLIDE:` entries to add links without slides.

### How do I add new entries to a captions file?

Re-running `llgal` with `--gc` will rescan the existing files and add the missing ones at the end of the captions file. You then re-run `llgal` to update the gallery regarding the new captions file.

### How do I keep the list of images involved in a gallery?

The captions file may also be used to keep track of the contents of a gallery. Even if you do not add some captions or title in the captions file, you may use it to list the exact set of images that you want to appear in the gallery.

## Managing slides

### How do I change the order of the slides?

The order of the slides might be changed with the `sort` option on command-line. For instance, `--sort=iname` sorts by name case insensitively, while `--sort=revdate` sorts by date, in reverse order. It is also possible to set the order by changing captions positions in the captions file.

### How do I select which files are included in a gallery?

By default, `llgal` does only include images and movies in the gallery. It is possible to force it to use all existing files in the directory (except `*.html` and `.*`) with:

      llgal -A

It is also possible to exclude some files with `--exclude regexp` where `regexp` is a Perl regexp. For instance, to exclude all `AVI` files starting with `MVI`:

      llgal --exclude 'MVI.*\.AVI'

File that were excluded might be reincluded by using the similar `--include` option. Finally, it is always possible to exclude files by generating a captions file and removing some entries. Note that the captions file is a good way to keep the list of images that are involved in the gallery, even if you do not want any caption.

## Layout

### How do I change the layout of the slides and index?

The main layout of generated webpages is based on HTML templates (`indextemplate.html` and `slidetemplate.html`) and a CSS style-sheet (`llgal.css`). It is possible to place modified versions of these files in the `.llgal` directory (or in `$HOME/.llgal/`) to change the layout.

### Why does llgal ignore the image dimension limits that I give?

Since converting images might be slow, `llgal` does not always regenerate thumbnails and scaled images. By default, it only does if the original images has been changed since last generation. To force regeneration, for instance if you changed the thumbnails (with `--tx` or `--ty`) or scaled images dimensions (with `--sx` or `--sy`), you may use `-f` (or `force_image_regeneration`).

### Does changing the maximal thumbnail dimensions really work?

By default, the width and height of thumbnails are both limited. Both dimension limits may be changed with `--tx` or `--ty`, but changing a single one does affect the other one. It means that the other should be changed too in most of the circumstances. Note that changing one of these options requires to force regeneration of thumbnails.

### How can I get the images in slides to adapt their size to the window?

`llgal` has been designed to create fixed-size slides. If, instead, you would like your images in slides to follow the size of the window, you may use the `slide_dimensions_from_css` option, either from a configuration file or with `--option` on the command line. `llgal` will then remove all absolute dimensions for images in HTML slides. Finally, you will be able to set the image width through the CSS slide sheet (`llgal.css`), for instance by adding `width: 100%` in `table.slide td.image-slide img`.

### How do I change the text that llgal generates in slides and index?

All text that appears in generated slides might be configured through configuration options. One day, there might be a full internationalization support through `gettext`.

### How can I go to the next slide when clicking on the current one?

By default, you need to click on `Next` to go to the next slide. If you passed `--sx` or `--sy`, clicking on the slide will lead you to the original image. If not, clicking does nothing. If you want this click to jump to the next slide, you just need to modify the slidetemplate and replace

           <!--THIS-SLIDE-->

with

           <a href="<!--NEXT-SLIDE-->"><!--THIS-SLIDE--></a>

and regenerate the gallery. Of course, if you keep using `--sx` or `--sy`, you will get into problems since there will be 2 hyperlinks on each slide.

### How do I set a thumbnail for a video or a subgallery?

All non-image slides and thumbnails are usually basic text. It is possible to force `llgal` to use a special thumbnail or scaled image by adding a special file in the local `.llgal` directory with prefix `mythumb_` or `myscaled_`. For instance, `mythumb_image24.jpg` will be used as a thumbnail for image `image24.jpg`. `mythumb_subdir3.jpg` will be used for sub-directory `subdir3`. And `myscaled_bar.avi.jpg` will be used as a scaled image for movie `bar.avi`. The extension for the thumbnail or scaled image may be any image extension that `llgal` recognizes.

### How do I get image EXIF tags in my slides?

Most images contains some meta-data called EXIF tags that may be useful to some people. `llgal` can display a table of some EXIF values under each image slide. The name of the tags correspond to what the `exiftool` program uses (see for instance `exiftool --list`).

      llgal --exif Aperture,FocalLength,ImageHeight,ImageWidth,FileModifyDate

Note that `--exif` requires the Image::ExifTool Perl module to be installed.

## Configuration

### How do I save/restore a configuration?

If you like using the same options for all your galleries and don't want to remember the option, you may ask `llgal` to generate a configuration file with:

      llgal --gencfg my_llgalrc

This file might be used later with

      llgal --config my_llgalrc

It may also be placed in the user llgal configuration file `$HOME/.llgal/llgalrc`. The configuration file contains a list of configuration lines. All command line options, and even much more, are available by this way. It is possible to pass any configuration option on the command line with `--option`. For instance, to set which file extensions `llgal` will match to find movies, use:

      llgal --option 'movie_extensions="mpe?g|avi|mov|ogm"'

## Multiple directories and subdirectories

### How do I include several subdirectories in a unique gallery?

If your photos are organized in several subdirectories of the working directory, you can use `-P` to take the photos from them instead of from the working directory.

      llgal -P subdir1 -P subdir2 -P subdir3

If you want these subdirectories to appear as sections, `llgal` can generate a horizontal line between each subdirectory and add a title in the index with `--Ps`. Additionally, `llgal` can display the title as regular text in the index instead of a text thumbnail with `-L`.

      llgal -P subdir1 -P subdir2 -P subdir3 --Ps -L

As usual, these horizontal lines and titles are generated as TXT and LINE entries are processed from the captions file. Thus, you may start by creating a captions file, edit it and then generate the gallery.

      llgal -P subdir1 -P subdir2 -P subdir3 --Ps --gc
      vi .llgal/captions
      llgal -L

### How do I include all subdirectories in a unique gallery?

Instead of passing `-P` for each subdirectory, you may ask `llgal` to include all images from all subdirectories.

      llgal --Pall

### How do I add a new subdirectory contents to a gallery?

You may a the list of files of a subdirectory to an existing gallery if its captions file if available, by regenerating it:

      llgal -P newsubdir --gc

The directory contents is added at the end of the captions file, which may be reordered by the user. The gallery may then be regenerated from the new captions file by re-running `llgal`.

### How do I create multiple subgalleries at once?

If your directory contains subdirectories, you might use `-S` to create slides linking to these subgalleries. With `-R`, the subgalleries will even be generated right after the main gallery. The list of subgalleries might be changed by modifying `DIR:` entries in the captions file.

### How do I modify a single gallery in a set of subgalleries?

Galleries that were created recursively (with `-R`) may be linked with their parents, children and brothers. If you plan to regenerate some galleries independently, you should take care of saving the configuration with `--gencfg` or generating a captions file. All linking information is stored inside these files. Regeneration is then easy (with `--config` in the first case).

### How do I create a text menu linking to multiple galleries?

Assuming you have a main directory containing multiple subdirectories where you already created sub-galleries, you may do:

      llgal -L -s

Using `-L` will create text links instead of thumbnails linking to sub-galleries, while `-s` will avoid any slide to be created.
As you may want slides in the sub-galleries, adding `-R` is not recommended here since `-s` would remove slides from both the main gallery and the sub-galleries. If you need `-R` anyway, you may for instance avoid this problem by dropping `-s` on the command and inserting `make_no_slides=1` in the main gallery configuration file (`.llgal/llgalrc`). Since the local configuration file is used for the local gallery and not for sub-galleries (even with `-R`), `make_no_slides=1` won't affect sub-galleries.

## Miscellaneous

### How do I add keyboard shortcuts to my gallery?

The HTML accesskey feature may be use to navigate in `llgal`'s galleries with keyboard shortcuts. But as this feature is very browser dependant and might conflict with some regular shortcuts in certain browsers, it is not enabled by default in `llgal`. Access keys can be configured by changing the templates and adding `accesskey=<letter>` to links. For instance, changing the `slidetemplate.html` code to the following one will define `p`, `n` and `i` as accesskeys to previous slide, next slide and return to the index. It means that `Alt+p`, `Alt+n` and `Alt+i` will be the actual shortcuts in Mozilla Firefox.

          <a href="<!--PREV-SLIDE-->" accesskey=p><!--PREV-SLIDE-LINK-TEXT--></a>
          &nbsp; &nbsp; &nbsp;
          <a href="<!--INDEX-FILE-->" accesskey=i><!--INDEX-LINK-TEXT--></a>
          &nbsp; &nbsp; &nbsp;
          <a href="<!--NEXT-SLIDE-->" accesskey=n><!--NEXT-SLIDE-LINK-TEXT--></a>

Note that the slide template might be modified by getting a copy with in the local or user-wide configuration directory using `--gt`.

### How do I prevent llgal from erasing my captions file?

`llgal --clean` erases all files that have not been modified regarding to their original template. The `captions` file does not have a template, so `llgal` will only erase it if it contains the following line:

    # REMOVE THIS LINE IF LLGAL SHOULD NOT REMOVE THIS FILE

When the user generates the `captions` file himself, he is not supposed to add this line, which means `llgal` won't erase the file. But, when the captions are generated with `llgal --gc`, this line will be added automatically. Hence, if the user modifies the `captions` file, he should start by removing this line first to protect his modifications from future erasing.
Note that `llgal --cleanall` erases ALL files, even if you kept the above line in the `captions` file.

### How do I let people add comments to my slides dynamically?

The `--php` option of `llgal` enables generation of PHP slides instead of HTML. By default, no PHP code is inserted. But, you may change the templates to add some PHP code to do whatever you want, including handle dynamic comments that people may add to your slides. `llgal` comes with some examples, including the directory `dynamic_comments_in_slides/` which gives a quick and dirty example to do so.

### Why is llgal so slow?

`llgal` uses `ImageMagick` (and especially `convert`) to generate thumbnails (and scaled images if `--sx` or `--sy` was passed). It can be pretty long if you have lots of large images. To avoid being slow everytime you re-run `llgal`, thumbnails and scaled images are only generated once (except when the original has been modified since or when `-f` is passed, see Why does llgal ignore the image dimension limits that I give?). There might be some way to improve the overall speed of thumbnails and scaled images generation by changing the corresponding command line with `scaled_create_command` and `thumbnail_create_command` in the configuration file. You may for instance use another conversion program which is more optimized than `ImageMagick` to process your specific images. See tweak_image_generation.txt in the examples in the documentation for details.

### Why does llgal not provide any feature to rotate or modify images?

`llgal` is only a gallery generator. Adding features to rotate images (for instance using Exif tags) or modify images (for instance to apply some filters) would open the door for thousands of options that `llgal` does not really require (and the command line interface is already pretty complex). We prefer keeping those features in other softwares that the user runs before using `llgal`. Also, there is no technical reason to include such filters in `llgal`. Applying them with another specialized software before generating the gallery is as easy, and such software will always provide more features than `llgal`.

### How do I scale my images to a smaller size and drop the originals?

`llgal` is not supposed to be used for this (see Why does llgal not provide any feature to rotate or modify images?). You should use an external tool earlier and then apply llgal on the scaled images. If you really want to use `llgal` to scale images down, you should use `--sx` and/or `--sy`. The scaled images will be placed in `.llgal/scaled_*`. To drop the originals and use the scaled images directly, you should first remove the originals from the main directory. Then move the scaled images from `.llgal` to the main directory and remove the `scaled_` suffix (`rename 's@^\.llgal/scaled_@@' .llgal/scaled_*` should do the trick). Finally, re-run the same `llgal` command line without `--sx` and/or `--sy`. You should get the same gallery as before, without the links from the slides to the original images.

$Id: howto.html,v 1.1 2006/05/07 00:46:01 bgoglin Exp $