NAME
llgal - On-line gallery generator
SYNOPSIS
llgal [-option1 -option2 ...]
DESCRIPTION
llgal is a quick and easy program for placing your images and movies
online with just one command-line. It generates a pretty good-looking
set of static HTML slides even with its default settings. To try it
out just run llgal in a directory with jpg, png, mpg, etc files and
check the output in a web browser. You can adjust the appearance of
the image gallery with the many options listed below or (if you know a
bit of HTML) by modifying the llgal.css files in the .llgal/
subdirectory that appeared in your image directory, or by defining
indextemplate.html or slidetemplate.html files.
llgal also checks for the existence of a $HOME/.llgal/ directory where
users can store their own templates, overriding the site-wide
/usr/share/llgal. (See FILES for details).
The HTML webpages are generated from the templates by replacing several
fields (See TEMPLATES). The layout might be configured through the
list of options that are given in LAYOUT.
llgal uses all images and videos it finds in the current directory.
See SELECTING FILES to include directories or other files and excludes
some filenames.
The index includes thumbnails that llgal generates from original
images. It is possible to provide custom thumbnails by placing them in
the .llgal/ directory with the mythumb_ prefix. Custom thumbnails for
movies have to be suffixed with an image-type extension. For instance,
to enforce the thumbnail for image image.jpg and movie movie.avi,
thumbnails may be named mythumb_image.jpg and mythumb_movie.avi.jpg.
The slide pages may include a scaled image in the --sx or --sy option
is passed. Similarly, it is also possible to define custom scaled
images with the myscaled_ prefix to appear in the slides.
Note that all command line options (except those from BEHAVIOR
OPTIONS), and even more, might be stored in a configuration file to
help generation of multiple galleries with the same layout. See
CONFIGURATION for details.
BEHAVIOR OPTIONS
By default, llgal generates a gallery. If one of the following option
is passed, it will process it and exit immediately.
--clean
Remove all files that llgal may have created earlier and that
user did not modify since.
--cleanall
Remove all files that llgal may have created earlier. This
includes thumbnails, scaled down slides, all HTML files,
captions file, film effect picture, indextemplate and
slidetemplate and the style-sheet file.
--gc Generate slide captions in .llgal/captions file that you may
edit. The format of this file is very simple. See CAPTIONS for
details. These captions may then be modified by the user. The
file will be automatically used next time llgal is invoked.
--gc might also be used to update the captions file when new
files were added to the working directory.
--gt [<dir>]
Copy template files to the directory. The special value local
might be used for the local .llgal/ directory, while user might
be used for the user template directory $HOME/.llgal/. Any
other directory is acceptable. llgal will create the target
directory if it does not exist. The argument is optional. Its
default value is local. See FILES for details about template
files.
-h, --help
Display brief help.
-V, --version
Display llgal version.
ADDITIONAL BEHAVIOR OPTIONS
llgal behavior may be modified with the following options, either when
generating a gallery or not.
--config <file>
Read the file file as a configuration. See CONFIGURATION for
details. Note that --config may be used several times on the
same command line. The corresponding configuration file option
is additional_configuration_file.
-d <dir>
Operate in directory <dir> when generating the HTML files,
thumbnails and scaled images. The default is the current
directory.
-f Force thumbnail regeneration. Also forces medium-slide
regeneration if --sx or --sy is given. Otherwise llgal will not
regenerate these files if they already exist, and you may end up
with stale copies. Definitely use -f between two runs where
you’ve changed the value of --tx, --ty, --sx or --sy. The
corresponding configuration file option is
force_image_regeneration.
--gencfg <file>
Output configuration in file for future reutilization through
--config. If local is passed as file, then the local
.llgal/llgalrc file is created in each gallery that is processed
(in case of recursion). See CONFIGURATION for details.
--option variable = value
Configure using a configuration file option. See CONFIGURATION
for details. Note that --option may be used several times on
the same command line.
-R Enable recursive mode. llgal will be run inside subdirectories.
This option might be used either to generate galleries in all
subdirectories, or their captions files, or to clean
recursively, etc. The corresponding configuration file option
is recursive.
When generating a gallery, this option implies -S that means
llgal will use all existing subdirectories in no captions file
is defined. If a captions file is defined, only the DIR:
entries will be entered recursively. See CAPTIONS for details
abour
Note that recursive behavior does only use the contents of the
captions file to choose which subgalleries to enter when
generating the gallery or the captions file. All other
behaviors, including recursive cleaning ( -R used together with
--clean or --cleanall), will not check whether a subdirectory is
in the captions file. All not-dot-begining subdirectories will
be cleaned.
-v, --verbose
Display notice messages. The corresponding configuration file
option is verbose.
SELECTING FILES
-A All files in the current directory will get a slides, except
.html or dot-begining files. Files are matched as images or
movies first, and then reverted as simple files instead. The
corresponding configuration file option is add_all_files. See
-S for details about adding slides for subdirectories.
--exclude <s>
Exclude files whose name matches <s>. The corresponding
configuration file option is exclude.
--include <s>
Include files whose name matches <s> and where previously
excluded. The corresponding configuration file option is
include.
-P <subdir>
Use photos in the subdirectory instead of the working directory.
May be used multiple times to group multiple subdirectories in
the same gallery. The path of the subdirectory must be given as
a relative path (relative to . or to the path given to -d). The
corresponding configuration file option is section_dir.
--Pall Use photos in all subdirectories all the working directory as if
-P was used for all of them. The corresponding configuration
file option is recursive_sections.
--Ps Add a horizontal line and the subdirectory name as a title at
the begining of each section. The corresponding configuration
file options are entitle_sections and separate_sections.
-S Each subdirectory will get a dedicated slide. If a captions
file exists, only the subdirectories that it defines will be
processed. If no captions file exists, llgal will process all
subdirectories but those whose name begins with a dot. The
corresponding configuration file option is add_subdirs.
Contrary to -R this option will not make llgal run recursively
in subdirectories. -S does only define the list of
subdirectories that appear in the current gallery.
LAYOUT OPTIONS
-a Write image dimensions and sizes under each thumbnail on the
index page, and under each slide if --sx or --sy was passed.
The corresponding configuration file options are show_dimensions
and show_size. This only works if the ImageMagick command
identify is present.
--ad Like -a but write only the image dimensions. The corresponding
configuration file option is show_dimensions.
--as Like -a but write only the image sizes. The corresponding
configuration file option is show_size.
--asu <s>
Allow to define the unit used to show file sizes. Default is
"kB". The corresponding configuration file option is
show_size_unit.
--cc [<s>]
Generates captions from image comment tag. If no argument is
given, llgal first tries the standard comment (for instance JFIF
or GIF), then tries Exif comments if the previous one is empty,
and then tries Exif image description. The corresponding
configuration file option is make_caption_from_image_comment.
An argument such as std or exif or exifdesc might be added to
force the use of only standard comment, only Exif comment, or
only Exif image description.
An argument such as exif,std will make llgal try Exif comment
first.
An argument such as std+exifdesc will use the combination of
standard comment and Exif description.
Passing --cc without argument is thus equivalent to passing --cc
std,exif,exifdesc.
--cf Generates captions from file names (strips suffix). The
corresponding configuration file option is
make_caption_from_filename.
--ct [strftime_format]
Add image timestamp tag to the generated captions, and change
its format if the optional argument is given (replaces the old
--ctf option). The corresponding configuration file option are
make_caption_from_image_timestamp and
timestamp_format_in_caption.
--codeset codeset
Change the encoding in the header of the generated HTML pages.
By default, the encoding is got from the locale configuration.
The corresponding configuration file option is codeset.
--exif [<tag1,tag2,...>]
Display a table of EXIF tags under each image slide. The
corresponding configuration file options are show_exif_tags and
show_all_exif_tags.
If an argument is given, it contains a comma-separated list of
tags. The tag names have to be passed as shown by exiftool
-list. If no argument is given, all available Exif tags are
displayed.
The tags are displayed using their description as given by
exiftool -s myimage.
--fe Show a film effect in the index of thumbnails. The aspect of
this effect may be configured by replacing the tile file that
llgal puts in .llgal. The corresponding configuration file
option is show_film_effect.
-i <file>
Name of the main thumbnail index file. The default is index, as
desirable for most web servers. The corresponding configuration
file option is index_filename.
The default extension is html and might be changed with --php or
the www_extension configuration option.
-k Use the image captions for the HTML slide titles. The default
behavior is to use the image names. The corresponding
configuration file option is make_slide_title_from_caption.
-L Do not create thumbnails for text and links (including video,
file and url), but list them as a text line between thumbnail
rows in the main gallery index. Might be used when the
directory only contains subgalleries and thus does not need any
thumbnail. The corresponding configuration file option is
list_links.
--lang locale
Change the locale used to translate the text that is
automatically generated in the HTML pages. The corresponding
configuration file option is language. Note that the LANGUAGE
environment variable might prevent this option from working if
set.
--li Replace link labels in slides (usually Index, Prev and Next)
with images (usually index.png, prev.png and next.png). The
corresponding configuration file options are index_link_image,
prev_slide_link_image and next_slide_link_image.
--lt Replace link labels in slides (usually Prev and Next) with a
thumbnail to preview previous/next slide. The corresponding
configuration file options are prev_slide_link_preview and
next_slide_link_preview.
If passed together with --li, thumbnail preview is used for
links to previous/next slide while the image is for the link to
the index is kept.
-n Use the image file names for the HTML slide files. Otherwise
the default behavior is to simply name your slides slide.html,
slide.html, and so on.
The corresponding configuration file option is
make_slide_filename_from_filename.
--nc Omit the image count from the captions. The corresponding
configuration file option is slide_counter_format.
--nf Omit the link from scaled images in slides to full unscaled
images. The corresponding configuration file option is
slide_link_to_full_image.
-p <n> The cellpadding value of the thumbnail index tables. The
default is 3. The corresponding configuration file option is
index_cellpadding.
--php Change the default extension of generated webpages from html to
php. The corresponding configuration file option is
www_extension.
Note that template names are not modified and keep their html
extension even if they contain some PHP code. Note that llgal
will only remove existing webpages corresponding to this
extension when generating a new gallery or cleaning.
--parent-gal
Add links to the parent directory. The corresponding
configuration file option is parent_gallery_link.
This option is used internally for recursive galleries, and thus
not documented in --help. These links are stored as a header
and a footer for the index. The text in the links might be
changed through the parent_gallery_link_text configuration
option.
--Rl Add links between subgalleries. The corresponding configuration
file option is link_subgalleries.
-s For the simplest setup, omit all HTML slides. Clicking the
thumbnails on the main page will just take users to the plain
image files. The corresponding configuration file option is
make_no_slides.
--sort [rev]<name|iname|size|time|none>
Change sort criteria when scanning files in the working
directory. Default is "name". Setting to the empty string
means none. iname is case insensitive sort by names. date
means time. rev might be added for reverse sort. The
corresponding configuration file option is sort_criteria.
--sx <n>
Instead of using the original image in the slides, insert a
scaled image whose width is less than <n> pixels. The
corresponding configuration file option is slide_width_max.
Useful if your digital camera spits out large images, like
1600x1200. Clicking on the scaled copies in the HTML slides
lets users see the full unscaled images. The default is 0
(width is unlimited). You must use -f to force regeneration of
scaled images if you want to change the value of --sx.
--sy <n>
Instead of using the original image in the slides, insert a
scaled image whose height is less than <n> pixels. The
corresponding configuration file option is slide_height_max.
Useful if your digital camera spits out large images, like
1600x1200. Clicking on the scaled copies in the HTML slides
lets users see the full unscaled images. The default is 0
(height is unlimited). You must use -f to force regeneration of
scaled images if you want to change the value of --sy.
--templates <dir>
Add a directory to the list of template locations. The
corresponding configuration file option is
additional_template_dir.
--title <s>
Substitutes the string <s> for <!--TITLE--> in the index. The
default is Index of Pictures. It overrides the configuration
file option index_title_default.
--tx <n>
Scale thumbnails so that their width is at most <n> pixels. The
default is 113. The corresponding configuration file option is
thumbnail_width_max. If 0 is used, the width is unlimited.
Changing this value does not affect the maximal height (see
--ty). You must use -f to force regeneration of thumbnails if
you want to change the value of --tx.
--ty <n>
Scale thumbnails so that their height is at most <n> pixels.
The default is 75. The corresponding configuration file option
is thumbnail_height_max. Changing this value does not affect
the maximal width (see --tx). You must use -f to force
regeneration of thumbnails if you want to change the value of
--ty.
-u Write image captions under each thumbnail on the index page. If
you have a captions file, then the captions are read from there.
The corresponding configuration file option is
show_caption_under_thumbnails.
--uc <url>
Assume the CSS file is available on <url> and thus do not use a
local one. If ending with a slash, the CSS filename will be
appended. The corresponding configuration file option is
css_location.
--ui <url>
Assume that the filmtile image and index/prev/next slide link
images are available on <url> and thus do not use local ones.
Their filename will be appended to the given location. Each
image location may be also changed independently (See
CONFIGURATION for the list of configuration options). The
corresponding configuration file options are filmtile_location,
index_link_image_location, prev_slide_link_image_location and
next_slide_link_image_location.
-w <n> Set the thumbnail rows to be <n> images wide in the main index
file. Default is 5. The corresponding configuration file
option is thumbnails_per_row.
--wx <n>
Set the thumbnail rows to be <n> pixels wide at maximum. The
number of thumbnails per row, given in -w is reduced if
necessary. The corresponding configuration file option is
pixels_per_row. Default is to honor -w without regard to the
resulting row width.
--www Make all generated files world-readable. The corresponding
configuration file option is www_access_rights.
CAPTIONS
When called with --gc llgal generates (or updates if already existing)
the captions file in the .llgal/ subdirectory.
When --gc is not passed, if the captions file exists, llgal will
automatically use it to generate slide captions in the gallery. If
captions does not exist, llgal generates captions on the fly and use
them in the gallery.
Generating the captions file with --gc before actually using it makes
it possible to modify them (especially to add comments) or change the
order of the slides in the gallery
IMG: <filename> ---- <caption>
defines an image (when omitted, IMG: is the default type).
MVI: <filename> ---- <linktext> ---- <caption>
defines a movie.
TXT: <text in slide> ---- <caption>
defines a text slide.
LNK: <url> ---- <linktext> ---- <caption>
defines a link slide.
LNKNOSLIDE: <url> ---- <linktext>
defines a direct link to the target, without any slide.
FIL: <url> ---- <linktext> ---- <caption>
defines a link to another file (typically neither an image nor a
movie)
DIR: <dir> ---- <linktext> ---- <caption>
defines a subdirectory slide.
BREAK
forces a line break in the row of thumbnails
LINE
forces a line break in the row of thumbnails and inserts a
horizontal line.
TITLE: <title>
defines the title of the gallery.
INDEXHEAD: <one header>
defines a header (multiple ones are possible).
INDEXFOOT: <one footer>
defines a footer (multiple ones are possible).
PARENT: <linktext>
defines the label of the link to the parent gallery.
PREV: <linktext> ---- <url>
defines the label of the link to the previous gallery located by
<url>.
NEXT: <linktext> ---- <url>
defines the label of the link to the next gallery located by
<url>.
REPLACE: <text> ---- <replacement>
adds a substitution to be applied to generated HTML pages.
Note that you can use whatever HTML syntax in the captions.
Line begining with a # are ignored.
When generating a captions file, the captions.header file is inserted
at the top of the file to detail the syntax.
CONFIGURATION
Before parsing command line options, llgal reads several configuration
files. It starts with /etc/llgal/llgalrc then reads
$HOME/.llgal/llgalrc and finally the .llgal/llgalrc file in the gallery
directory.
Additional configuration files may also be defined with the --config
option. These will be parsed during command-line parsing, when
--config is met.
In case of recursive generation (with -R ) in multiple subdirectories,
the system- and user-wide configuration files and those passed to
--config are taken in account for all galleries. However, only the
local .llgal/llgalrc file is used for each gallery. Especially, the
one in the root gallery directory is only taken in account when
generating the root gallery, not when generating those in
subdirectories. To use a same specific configuration file for the root
gallery and all subgalleries, the --config option may be used.
All these files may change llgal configuration in the same way command
line options do, and even more. All following options may also be used
on the command line through --option variable = value.
See also the manpage of llgalrc or /etc/llgal/llgalrc for details about
these options and their default values.
THUMBNAILS AND SCALED IMAGES GENERATION
By default, llgal uses convert to create thumbnails and scaled images
(the ones that appear in the slides when --sx or --sy was passed). The
command lines used to generate those images from your original images
are defined by the following configuration options:
scaled_create_command = convert -scale <MAXW>x<MAXH> -- <IN>
<OUT>
thumbnail_create_command = convert -scale <MAXW>x<MAXH> -- <IN>
<OUT>
You may change the value of these options to change the way the
generation is done. <IN> and <OUT> will be replaced by llgal at
runtime with the filename of the original and generated target images.
<MAXW> and <MAXH> will be replaced by the maximal width and length of
the generated images. Note that one of them might not be limited
(depending on other configuration variable), making it be replaced by
an empty string, eventually leading to empty parameters being passed to
your program. If your program does not like that, you might want to
create a wrapper shell script which will take care of accepting these.
Another solution would be to replace unlimited with limited by a huge
value in your configuration and adapt your program to deal with it.
TEMPLATES
When generation web pages, the following fields will be replaced from
the templates by the associated value (computed by llgal).
<!--TITLE-->
The title of the index.
<!--CSS-->
The CSS style-sheet.
<!--CREDITS-->
The credits line given by credits_text configuration option.
<!--VERSION-->
The version of the program used to generate the gallery.
<!--INDEX-FILE-->
The filename of the index.
<!--INDEX-LINK-TEXT-->
The label of the link to the index (might be an image).
LLGAL-CODESET
The character encoding, usually set to iso-8859-1 or utf-8.
LLGAL-OPTIONS
The options that were passed to llgal on the command line to
generate the gallery.
When generating the index from template indextemplate.html, the
following additional fields will also be replaced.
<!--HEADERS-->
The list of headers that are given in the captions file.
<!--FOOTERS-->
The list of footers that are given in the captions file.
When generating slides from template slidetemplate.html, the following
additional fields will also be replaced.
<!--SLIDE-TITLE-->
The title of the slide.
<!--THIS-SLIDE-STYLE-->
The style of the slide contents (is defined in the CSS style-
sheet).
<!--SLIDE-NUMBER-->
The index of the slide, with leading zeros.
<!--SLIDE-TOTAL-->
The amount of slides.
<!--SLIDE-COUNTER-->
The slide counter according to slide_counter_format as in the
caption.
<!--IMAGE-CAPTION-->
The caption of the slide.
<!--EXIF-TABLE-->
The table of EXIF tags.
<!--THIS-SLIDE-->
The actual contents of the slide (might be an image).
<!--PREV-SLIDE--> and <!--NEXT-SLIDE-->
The filename of the previous and next slides.
<!--NEXT-SLIDE-LINK-TEXT--> and <!--PREV-SLIDE-LINK-TEXT-->
The label of the link to previous and next slides (might be an
image).
Additionally, it is possible to define use custom fields in the
templates and define their replacement with some REPLACE entries in the
captions file. See CAPTIONS for details.
When modifying the templates, beware that the HTML syntax requires
double-quotes around filenames, URL, etc. These double-quotes will
never be automatically added when replacing these automatic variables.
So you must keep double-quotes around variables when needed, for
instance:
<a href="<!--NEXT-SLIDE-->"><!--NEXT-SLIDE-LINK-TEXT--></a>
will be changed into
<a href="slide_.html">Next slide</a>
LANGUAGE
The language that llgal uses to generate text in HTML pages is chosen
from the localization configuration. If the chosen language is
available in llgal translations, it will be used instead of the default
english.
As usual with gettext, it is possible to override the localisation
configuration by changing LANG, LC_MESSAGES or LANGUAGE environment
variables.
If the desired language is not available in llgal translations, or if
the user wishes to change the text values, he might create an
additional configuration file (or modify the system-wide one) to update
all configuration options of the Text section.
The locale configuration might be overriden with the --lang option or
language configuration option. But, the LANGUAGE environment variable
appears to prevent this from working if set.
CHARACTER ENCODING
If a filename contains non-ascii characters which are not safely
representable in a URL, llgal will escape them using the method RFC
2396 specifies. This may raise problems if the web server has a
different notion of character encoding than the machine llgal runs on.
See also http://www.w3.org/TR/html4/appendix/notes.html#h-B.2
Character encoding is chosen from the locale configuration and set in
the HTML headers. It may be overriden by using --codeset or the
codeset configuration option.
NOTES
Note that all numerical options may be resetted to their default value
by setting them a negative value.
FILES
/etc/llgal/llgalrc, $HOME/.llgal/llgalrc, .llgal/llgalrc
System-wide, per-user and local configuration files. See
CONFIGURATION for details.
/usr/share/llgal/captions.header
Captions syntax description file that is inserted at the top of
generated captions file.
/usr/share/llgal/llgal.css
The default style-sheet template.
/usr/share/llgal/tile.png
The tiled image used for the film effect.
/usr/share/llgal/index.png
The link image used for the index.
/usr/share/llgal/prev.png
The link image used for the previous slide.
/usr/share/llgal/next.png
The link image used for the next slide.
All files are required on the website. llgal will copy them to the
local .llgal/ file during gallery generation.
/usr/share/llgal/indextemplate.html
The default index template file.
/usr/share/llgal/slidetemplate.html
The default file used to generate slides.
These files are not required on the website. But, llgal will use them
to generate HTML webpages of the gallery by replacing several fields
with text or images. See TEMPLATES for details.
The user may change all these templates by storing files with the same
name in its user template directory $HOME/.llgal/ or in the local
.llgal/ directory. The former defines user-specific templates that
will be used each time the user generate a gallery. The later defines
gallery-specific templates that will be used for the local gallery. A
local template is used by default if it exists. A user template is
used if it exists and no local template exists. Finally, system-wide
templates are used if no local and user templates override them.
It is also possible to add custom template directories (with
--templates) that will be used to get templates before trying in the
user and in the system-wide template directories.
The option --gt might be used to get copies of template files in the
local or in the user template directory.
EXAMPLES
Run llgal in a directory with jpg, gif, png, mpg or avi files to see
what it does. Then play with the options described above and use -h if
you need a quick listing.
BUGS
There are always some. If you find any let me know.
SEE ALSO
llgalrc(5)
AUTHOR
Brice Goglin
NOVEMBER 2006