LLGAL(1)

📦 version 0.13.19, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

Okay so llgal is a General Commands Manual page, and it is long, so buckle up 🎀

💖 NAME 💖

llgal — On-line gallery generator 🦋

🌸 SYNOPSIS 🌸

llgal [-option1 -option2 ...]

🦋 DESCRIPTION 🦋

So llgal is this quick and easy program that puts your images and movies online with just one command-line. Periodt. It generates a pretty good-looking set of static HTML slides even with its default settings — no cap. 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. Lowkey powerful 💅

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 exclude 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 if 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 options is passed, it will process it and exit immediately. No chill, it just dips 🏃♀️

  • --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. It's giving nuclear option fr fr 💀
  • --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, which means llgal will use all existing subdirectories if no captions file is defined. If a captions file is defined, only the DIR: entries will be entered recursively. See CAPTIONS for details.

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 options 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 get shown off using their description, exactly as exiftool -s myimage hands it over. Like, we're not paraphrasing the metadata bestie, we're quoting it. 💅

  • --fe — slaps a film effect onto the thumbnail index. The whole vibe of that effect is yours to customize — just swap out the tile file that llgal drops into .llgal. ✨ The config-file twin here is show_film_effect.
  • -i <file> — names the main thumbnail index file. Default is index, which is lowkey perfect for most web servers. 🫶 The config-file twin is index_filename.

The default extension is html, and you can switch that up with --php or the www_extension configuration option.

  • -k — uses the image captions as the HTML slide titles. Default behavior? Uses the image names instead. The config-file twin is make_slide_title_from_caption. 🌸
  • -L — no thumbnails for text and links (that's video, file and url too, bestie), just lists them as a text line tucked between thumbnail rows in the main gallery index. Genuinely useful when the directory is nothing but subgalleries and truly does not need a single thumbnail. The config-file twin is list_links. 💜
  • --lang locale — changes the locale used to translate the auto-generated text in your HTML pages. The config-file twin is language.
Heads up 🚨 — the LANGUAGE environment variable can absolutely block this option from working if it's set.
  • --li — swaps link labels in slides (you know, the usual Index, Prev and Next) for actual images (the usual index.png, prev.png and next.png). The config-file twins are index_link_image, prev_slide_link_image and next_slide_link_image. 🎀
  • --lt — swaps link labels in slides (the usual Prev and Next) for a thumbnail preview of the previous/next slide. The config-file twins are prev_slide_link_preview and next_slide_link_preview.

And if you pass it together with --li, the thumbnail preview takes over for the previous/next slide links, while the image stays put for the link to the index. Teamwork, honestly. 👑

  • -n — uses the image file names for the HTML slide files. Otherwise, default behavior just names your slides slide_1.html, slide_2.html, and so on, forever. The config-file twin is make_slide_filename_from_filename.
  • --nc — omits the image count from the captions. The config-file twin is slide_counter_format. ✨
  • --nf — omits the link from scaled images in slides to the full unscaled images. The config-file twin is slide_link_to_full_image.
  • -p <n> — sets the cellpadding value of the thumbnail index tables. Default is 3. The config-file twin is index_cellpadding.
  • --php — flips the default extension of generated webpages from html to php. The config-file twin is www_extension.
Okay so, two notes, both important 💀 — template names do not get modified, and they keep their html extension even if they contain some PHP code. And llgal will only remove existing webpages matching this extension when it's generating a new gallery or cleaning up.
  • --parent-gal — adds links to the parent directory. The config-file twin is parent_gallery_link.

This one is used internally for recursive galleries, so it's not documented in --help (iykyk 🙈). These links get stored as a header and a footer for the index. The text in the links can be changed through the parent_gallery_link_text configuration option.

  • --Rl — adds links between subgalleries. The config-file twin is link_subgalleries. 🦋
  • -s — the simplest setup ever: omit all HTML slides. Clicking the thumbnails on the main page just takes users straight to the plain image files. The config-file twin is make_no_slides.
  • --sort [rev]<name|iname|size|time|none> — changes the sort criteria when scanning files in the working directory. Default is "name". Setting it to the empty string means none. iname is case-insensitive sort by names. date means time. And rev can be added on for reverse sort. The config-file twin is sort_criteria.
  • --sx <n> — instead of using the original image in the slides, inserts a scaled image whose width is less than <n> pixels. The config-file twin is slide_width_max. Super 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. Default is 0 (width is unlimited).
Real talk: you must use -f to force regeneration of scaled images if you want to change the value of --sx. No -f, no new scaled images. Periodt. 💅
  • --sy <n> — same deal but for height: instead of using the original image in the slides, inserts a scaled image whose height is less than <n> pixels. The config-file twin is slide_height_max. Again, perfect if your digital camera spits out large images, like 1600x1200. Clicking the scaled copies in the HTML slides lets users see the full unscaled images. Default is 0 (height is unlimited).
And again: you must use -f to force regeneration of scaled images if you want to change the value of --sy. 🌈
  • --templates <dir> — adds a directory to the list of template locations. The config-file twin is additional_template_dir. ✨
  • --title <s> — substitutes the string <s> for <!--TITLE--> in the index. Default is Index of Pictures. It overrides the configuration file option index_title_default. 👑
  • --tx <n> — scales thumbnails so their width is at most <n> pixels. Default is 113. The config-file twin is thumbnail_width_max. If 0 is used, the width is unlimited. Changing this value does not affect the maximal height (peep --ty). And yes bestie, you must use -f to force regeneration of thumbnails if you want to change the value of --tx. 😭
  • --ty <n> — scales thumbnails so their height is at most <n> pixels. Default is 75. The config-file twin is thumbnail_height_max. Changing this value does not affect the maximal width (peep --tx). And same rule, fr fr: you must use -f to force regeneration of thumbnails if you want to change the value of --ty.
  • -u — writes image captions under each thumbnail on the index page. If you've got a captions file, the captions get read from there. The config-file twin is show_caption_under_thumbnails. 🍓
  • --uc <url> — assumes the CSS file lives on <url> and therefore does not use a local one. If it ends with a slash, the CSS filename gets appended. The config-file twin is css_location.
  • --ui <url> — assumes the filmtile image and the index/prev/next slide link images all live on <url>, so it doesn't use local ones. Their filename gets appended to the given location. Each image location can also be changed independently — check out CONFIGURATION for the list of configuration options. The config-file twins are filmtile_location, index_link_image_location, prev_slide_link_image_location and next_slide_link_image_location. 🎀
  • -w <n> — sets the thumbnail rows to be <n> images wide in the main index file. Default is 5. The config-file twin is thumbnails_per_row.
  • --wx <n> — sets the thumbnail rows to be <n> pixels wide at maximum. The number of thumbnails per row given in -w gets reduced if necessary. The config-file twin is pixels_per_row. Default is to honor -w without any regard for the resulting row width. 🦋
  • --www — makes all generated files world-readable. The config-file twin is www_access_rights. 💖

🌸 CAPTIONS 🌸

Okay so this is where it gets good. When you call llgal with --gc, it generates the captions file in the .llgal/ subdirectory — or updates it if it's already there. 🫶

When --gc is not passed, and the captions file exists, llgal will automatically use it to generate slide captions in the gallery. And if the captions file doesn't exist? llgal generates captions on the fly and uses those in the gallery instead. Either way, you're covered bestie. ✨

Generating the captions file with --gc before you actually use it means you get to modify them — especially to add comments — or change the order of the slides in the gallery. Lowkey the move. 💅

Here's every line type you can drop in there:

  • 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 you want in the captions. 🎀 And any line beginning with a # is ignored — that's your comment slot, bestie.

When generating a captions file, the captions.header file gets inserted at the top of the file to detail the syntax. 💖

⚙️ CONFIGURATION ⚙️

Okay bestie, before llgal even looks at your command line options, it's already been reading configuration files. The order is: it starts with /etc/llgal/llgalrc, then reads $HOME/.llgal/llgalrc, and finally the .llgal/llgalrc file sitting in the gallery directory itself. 💅

You can also define extra configuration files with the --config option. Those get parsed during command-line parsing, right when --config is encountered. No cap.

Now here's the recursive tea. If you're doing recursive generation (with -R) across multiple subdirectories, then the system-wide and user-wide config files, plus anything you passed to --config, apply to all the galleries. However — and this is the important bit — only the local .llgal/llgalrc file is used for each individual gallery. So specifically, the one in the root gallery directory is only taken into account when generating the root gallery, not when generating the ones in subdirectories. If you want one specific config file to cover the root gallery and all the subgalleries, use the --config option. 🫶

All of these files can change llgal configuration the same way command line options do — and honestly even more. Every option listed below can also be used on the command line through --option 'variable = value'.

Also go check the manpage of llgalrc or /etc/llgal/llgalrc for the 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 scaled ones are the ones that show up in the slides when --sx or --sy was passed). The command lines it uses to generate those images from your originals are defined by these configuration options:

scaled_create_command = convert --scale <MAXW>x<MAXH> -- <IN> <OUT>
thumbnail_create_command = convert --scale <MAXW>x<MAXH> -- <IN> <OUT>

You can change the value of these options to change how the generation happens. At runtime, llgal replaces <IN> and <OUT> with the filename of the original image and the generated target image.

<MAXW> and <MAXH> get replaced with the maximal width and length of the generated images. Heads up though: one of them might not be limited at all (depends on other configuration variables), which means it gets replaced by an empty string — and that can end up passing empty parameters to your program. 😭 If your program does not vibe with that, you might want to write a wrapper shell script that handles accepting those. Another solution is to replace unlimited with limited by using a huge value in your configuration, and adapt your program to deal with it. ✨

📝 TEMPLATES 📝

When generating web pages, the following fields get 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, these following additional fields also get 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, these additional fields also get 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).

On top of all that, you can define your own custom fields in the templates and define their replacement with some REPLACE entries in the captions file. Go look at CAPTIONS for the details. 💖

When you're modifying the templates, beware that 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 llgal uses to generate text in HTML pages is chosen from the localization configuration. If the chosen language is available in llgal translations, it gets used instead of the default english. Slay.

As is usual with gettext, you can override the localisation configuration by changing the LANG, LC_MESSAGES or LANGUAGE environment variables.

If the language you want isn't available in llgal translations, or if the user wants to change the text values, they 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 the language configuration option. But — plot twist — the LANGUAGE environment variable appears to prevent this from working if it's set. 💀

🔤 CHARACTER ENCODING 🔤

If a filename contains non-ascii characters that aren't 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 📌

Quick thing bestie: 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. (Iconic honesty fr fr.)

👀 SEE ALSO 👀

llgalrc(5)

👑 AUTHOR 👑

Brice Goglin

And that's the whole page bestie!! 💖 This was LLGAL(1), dated NOVEMBER 2006 — yeah, it's been serving since 2006 and it's still that girl. Go make a gallery, you got this. 🫶✨

📦 where this page comes from