1LAZYGAL(1) User commands LAZYGAL(1)
2
6 lazygal - static web gallery generator
7
9 lazygal [-h | -v | [options] albumdir]
10
12 This manual page explains the lazygal program. This program is a static
13 web gallery generator written in Python.
14 lazygal works so: you should have an original store of files - possibly
16 containing subdirectories (their names serving as headings if not using
17 the album metadata feature). This is the source file hierarchy. It will
18 never be modified by lazygal. Then, when launching:
19 $ lazygal -o /var/www/MyAlbum /home/user/SourceDir
21 lazygal will analyze the contents of the source hierarchy and will
23 (re)create the target hierarchy, with all the bells and whistles
24 defined by the templates. Only missing parts or parts that are not up
25 to date will be generated. There is a limitation to this mechanism
26 though: although updates in the source directory, in the metadata or in
27 the themes are detected, changes in command line options and
28 configuration files since last generation are not and the user should
29 manually delete files that need to be generated again.
30
32 These programs follow the usual GNU command line syntax, with long
33 options starting with two dashes (`-'). A summary of options is
34 included below. For a complete description, see the -h switch.
35 -v --version
37 Show program's version number and exit.
38 -h --help
40 Show summary of options.
41 --quiet
43 Don't output anything except for errors.
44 --debug
46 Output everything that lazygal is doing.
47 -o DEST_DIR --output-directory=DEST_DIR
49 Directory where web pages, slides and thumbs will be written
50 (default is current directory).
51 -t THEME --theme=THEME
53 Theme name (looked up in theme directory) or theme full path.
54 --default-style=DEFAULT_STYLE
56 Default style to apply to the theme. This is actually the filename
57 (no extension) of the CSS stylesheet of the theme that is not
58 marked as alternate, thus should get used as default or prefered by
59 the web browser.
60 --template-vars=TPL_VARS
62 Common variables to load all templates with, e.g.
63 --template-vars='footer=foo bar,color=baz'. For longer variable
64 contents, it is easier to use a configuration file (see
65 lazygal.conf(5)).
66 -f --force-gen-pages
68 Force rebuild of web pages, regardless of the modification times of
69 their dependencies. This is handy when changing a configuration
70 option affecting these (theme, directory flattening, etc.).
71 --clean-destination
73 Clean destination directory of files that should not be there.
74 --preserve=PATTERN
76 Specify a file pattern (or name) which should be ignored during
77 cleanup of the destination. May be specified more than once. Values
78 given here will be in addition to those specified in configuration
79 files.
80 --excludes=PATTERN
82 Specify a file pattern (or name) which should be ignored during
83 processing. May be specified more than once. Values given here will
84 be in addition to those specified in configuration files.
85 --check-all-dirs
87 Exhaustively go through all directories regardless of source
88 modification time.
89 -s IMAGE_SIZE --image-size=IMAGE_SIZE
91 Size of images, define as name=xxy, ..., eg.
92 small=800x600,medium=1024x768. The special dimensions 0x0 use
93 original size. Refer to the IMAGE RESIZE DESCRIPTION section for
94 more information on the available syntax.
95 -T THUMBNAIL_SIZE --thumbnail-size=THUMBNAIL_SIZE
97 Size of thumbnails, eg. 150x113. Refer to the IMAGE RESIZE
98 DESCRIPTION section for more information on the available syntax.
99 -q QUALITY --quality=QUALITY
101 Quality of generated JPEG images (default is 85).
102 -O --original
104 Include original photos in output.
105 --orig-base=RELATIVE_PATH
107 Do not copy original photos in output directory, instead link them
108 using RELATIVE_PATH as base for those links (discarded without -O).
109 --orig-symlink
111 Do not copy original photos in output directory, instead create
112 symlinks to their original locations. This is useful when you plan
113 transferring the whole directory which lazygal generated to some
114 other location, perhaps with rsync, and you wish to avoid creating
115 an extra copy of each photo.
116 Caution
118 This option is not available on Windows; if you try to use it
119 on that operating system, lazygal will immediately exit with an
120 exit status of 1.
121 --puburl=PUB_URL
123 Publication URL (only useful for feed generation).
124 -m --generate-metadata
126 Generate metadata description files where they don't exist in the
127 source tree instead of generating the web gallery. This disables
128 all other options.
129 -n THUMBS_PER_PAGE --thumbs-per-page=THUMBS_PER_PAGE
131 Maximum number of thumbs per index page. This enables index
132 pagination (0 is unlimited).
133 --filter-by-tag=TAG
135 If set, lazygal will only export the pictures that have one of
136 their (IPTC) tags matching TAG. It is also possible to use an
137 equivalent of AND and OR boolean tests to filter tags. For more
138 details, read below the section TAG FILTERING.
139 --pic-sort-by=ORDER
141 Sort order for images in a subgallery, among 'mtime', 'filename',
142 'numeric', or 'exif'. (default is 'exif' which is by EXIF date if
143 EXIF data is available, filename otherwise, sorting EXIF-less
144 images before). 'numeric' does a numeric sort on the numeric part
145 of the filename. Add ':reverse' to reverse the sort order (e.g.
146 --pic-sort-by=mtime:reverse).
147 --subgal-sort-by=ORDER
149 Sort order for subgalleries, among 'exif' (EXIF date of the latest
150 picture in sub-gallery), 'mtime', 'dirname', or 'numeric' (default
151 is 'dirname'). 'numeric' does a numeric sort on the numeric part of
152 the dirname. Add ':reverse' to reverse the sort order (e.g.
153 --subgal-sort-by=dirname:reverse).
154 --dir-flattening-depth=LEVEL
156 Level below which the directory tree is flattened. Default is no
157 flattening ('No').
158 This option makes the program include the web gallery index of
160 child galleries in their parent's gallery index, if their level is
161 greater than the supplied LEVEL. The level of the album root is 0.
162 Index pages with multiple galleries (which happens when this
164 section is used) show the pictures links in gallery sections.
165 The following examples show the produced indexes for a sample album
167 (2 sub-galleries, 1 sub-sub-gallery, 1 picture in each one of
168 those).
169 Example 1. --dir-flattening-depth=No (default)
171 index.html <- sub-gallery links
173 subgal1/index.html <- index with img1
174 subgal1/img1.html
175 subgal1/subsubgal1/index.html <- index with img2
176 subgal1/subsubgal1/img2.html
177 subgal2/index.html <- index with img3
178 subgal2/img3.html
179 Example 2. --dir-flattening-depth=0
182 index.html <- contains index for all pics
184 subgal1/img1.html
185 subgal1/subsubgal1/img2.html
186 subgal2/img3.html
187 Example 3. --dir-flattening-depth=1
190 index.html <- contains index for all pics
192 subgal1/index.html <- index with img1 and img2
193 subgal1/img1.html
194 subgal1/subsubgal1/img2.html
195 subgal2/index.html <- index with img3
196 subgal2/img3.html
197 -z --make-dir-zip
200 Make a zip archive of original pictures for each directory.
201 --webalbum-pic-bg=WEBALBUMPIC_BG
203 Webalbum picture background color. Default is transparent, and
204 implies the PNG format. Any other value, e.g. red, white, blue,
205 uses JPEG.
206 --webalbum-pic-type=WEBALBUMPIC_TYPE
208 What type of web album thumbnails to generate. By default, lazygal
209 generates the well-loved "messy" thumbnails with randomly selected
210 pictures from the album each rotated by a random amount and pasted
211 together. This default can also be forced by specifying 'messy' as
212 WEBALBUMPIC_TYPE.
213 On the other hand, specifying 'tidy' as the value of this option
215 forces lazygal to skip the rotations, resulting in more regularly
216 shaped thumbnails which can also be more densely packed. This can
217 be an advantage if not all users of your albums have huge screens
218 :-)
219 --keep-gps-data
221 Do not remove GPS data from EXIF tags. By default the location tags
222 are removed for privacy reasons. However, there are situations when
223 having the location data makes sense and is desired. This is mostly
224 meant to be used with holiday photos.
225
227 A theme maps to a directory that contains the following items:
228 theme/SHARED_*
230 Files to put in the web gallery directory shared, e.g. CSS,
231 Javascript, images or other resources common to all galleries.
232 theme/browse.thtml
234 The XHTML template for the theme browse page (displaying one
235 picture).
236 theme/dirindex.thtml or theme/dynindex.thtml
238 The XHTML template for the directory index page (pictures and
239 sub-galleries links).
240 Depending on which index file is present, the theme will be:
242 dirindex.thtml: fully static
244 one HTML page per picture, per size and one index per size, or
245 dynindex.thtml: dynamic
247 only one index per directory is to be generated.
248 theme/*.thtml must be valid XML. See
250 http://genshi.edgewall.org/wiki/Documentation/xml-templates.html for
251 syntax. Dependencies for statically included templates (i.e. with
252 filenames not computed from variables) are automatically computed: when
253 an included template is modified, the software will automatically
254 figure out which pages to re-generate. Missing template files will be
255 searched for in the default theme.
256 theme/SHARED_* files (common resources for the directory shared) are
258 renamed to strip the SHARED_ prefix and:
259 · Processed using the Genshi text template engine (see
261 http://genshi.edgewall.org/wiki/Documentation/text-templates.html
262 for syntax.) if their file extension starts with t,
263 · Copied to the web album destination otherwise.
265 Using the theme manifest theme/manifest.json file, it is possible to
267 include files from other directories to be copied into the web album
268 shared files.
269 Example 4. manifest.json
271 {
273 "shared": [
274 # copy as shared/lib.js
275 { "path": "../lib-2.1.js", "dest": "lib.js" },
276 # copy as shared/js/lib-2.1.js
278 { "path": "../lib-2.1.js", "dest": "js/" }
279 ]
280 }
281 Please refer to the examples supplied in /usr/share/lazygal/themes.
284
286 If a directory from the source album contains a file named
287 album_description, it is processed as a source of album metadata. The
288 format is borrowed from another album generating tool - Matew. Each
289 line is treated as one possible tag, unknown lines are simply ignored.
290 Example content of this file follows:
291 Example 5. album_description
293 Album name "My album"
295 Album description "Description, which can be very long."
296 Album image identifier relative/path/to/image.jpg
297 Otherwise, the user can provide metadata in the following files.
300 SOURCE_DIR/album-name
302 The title to use for this album directory.
303 SOURCE_DIR/album-description
305 The description for this album directory. HTML tags are used
306 verbatim from this file.
307 SOURCE_DIR/album-picture
309 The relative path to the image to use at the top of the album
310 picture stack.
311 SOURCE_DIR/PICTURE_FILENAME.comment
313 The description to use for this particular image. Please note that
314 HTML tags are taken as provided in this file for output in the
315 templates.
316 Lazygal also extracts information from many metadata tags in image
318 files. Regarding image description, Lazygal searches for comments in
319 this order:
320 1. pic.jpeg.comment file
322 2. Exif.Photo.UserComment
324 3. Exif.Image.ImageDescription
326 4. Iptc.Application2.ObjectName
328 5. JPEG comment
330
332 ~/.lazygal
333 User configuration directory.
334 ~/.lazygal/themes
336 User themes directory.
337
339 Multiple configuration files are processed by lazygal. The
340 configuration is initially set up with the defaults. The defaults can
341 be found in the lazygal source distribution in lazygal/defaults.json.
342 Then, the configuration files are processed in the following order,
344 each newly defined value overloading formerly defined values.
345 Finally, any command-line-provided parameter takes precedence on any
347 configuration file value.
348 ~/.lazygal/config
350 User configuration file. See lazygal.conf(5) for format.
351 SOURCE_DIR/.lazygal
353 Album root configuration file. See lazygal.conf(5) for format.
354 SOURCE_DIR/gal/.lazygal
356 Web gallery configuration file. Only the webgal and template-vars
357 sections are red in these files. The configuration applies to the
358 gallery representing the directory of the configuration file, and
359 all of its sub-directories, unless another configuration file in a
360 sub-directory overloads some of the defined configuration values.
361 See lazygal.conf(5) for format.
362
364 The size string follows the same syntax as ImageMagick's.
365 scale%
367 Height and width both scaled by specified percentage.
368 xscale%yscale%
370 Height and width individually scaled by specified percentages.
371 width
373 Width given, height automatically selected to preserve aspect
374 ratio.
375 xheight
377 Height given, width automatically selected to preserve aspect
378 ratio.
379 widthxheight
381 Maximum values of height and width given, aspect ratio preserved.
382 widthxheight^
384 Minimum values of width and height given, aspect ratio preserved.
385 widthxheight!
387 Width and height emphatically given, original aspect ratio ignored.
388 widthxheight>
390 Change as per the supplied dimensions but only if an image
391 dimension exceeds a specified dimension.
392 widthxheight<
394 Change dimensions only if both image dimensions exceed specified
395 dimensions.
396 pixels@
398 Resize image to have specified area in pixels. Aspect ratio is
399 preserved.
400
402 Tag filtering supports regular expression matching thanks to the 're'
403 module of Python. All the filter matchings can be indicated to lazygal
404 by successive uses of the 'filter-by-tag' option, or by giving a
405 coma-separated list of keywords.
406 We illustrate here how more elaorated tag filtering can be done.
408 We want to export only the images that have the tags 'lazygal' AND
410 'hiking'.
411 $ lazygal --filter-by-tag=lazygal --filter-by-tag=hiking
413 or:
416 $ lazygal --filter-by-tag=lazygal,hiking
418 We want to export the images that have the tags 'lazygal' OR 'hiking'.
421 $ lazygal --filter-by-tag="(lazygal|hiking)"
423 We want to export the images that have one of the tags 'hiking_2012',
426 'hiking_2013', 'hiking_France', etc.
427 $ lazygal --filter-by-tag="hiking_.*"
429 We want to export the images that have the tag 'lazygal', AND one of
432 the tags 'hiking_2012', 'hiking_2013', 'hiking_France', etc.
433 $ lazygal --filter-by-tag="lazygal,hiking_.*"
435
438 lazygal.conf(5).
439 More information is available on the program website:
441 https://sml.zincube.net/~niol/repositories.git/lazygal/about/.
442
444 This manual page was written for the Debian(TM) system (but may be used
445 by others). Permission is granted to copy, distribute and/or modify
446 this document under the terms of the GNU General Public License,
447 Version 2 any later version published by the Free Software Foundation.
448 On Debian systems, the complete text of the GNU General Public License
450 can be found in /usr/share/common-licenses/GPL.
451
453 Copyright © 2010
454lazygal August 2011 LAZYGAL(1)