Ubuntu Manpage: llgal - On-line gallery generator

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-beginning 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-beginning 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 beginning 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>
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 extension, except for directories). 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_1.html, slide_2.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  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 beginning 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  to  used  in  <a  href=""> attributes.  May also contain additional
              attributes to be appended after href.
       <!--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.
       <!--EXIF-%tag%-->
              The value of the image EXIF tag %tag%.  The tag  name  %tag%  must  match  the  name  reported  by
              exiftool -s myimage.  Note that a single replacement may be performed per template line.
       <!--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_04.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 overridden 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
       overridden by using --codeset or the codeset configuration option.

NOTES

       Note that all numerical options may be reset 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.

AUTHOR

       Brice Goglin

                                                  NOVEMBER 2006                                         LLGAL(1)