Debian Codegraph @

doc/howto.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4 <head>
5 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
6 <title>llgal - On-line gallery generator - How-To?</title>
7 <link rel="stylesheet" type="text/css" href="main.css"/>
8 </head>
9 <body>
10
11 <h1 class="title">llgal How-To?</h1>
12
13 <p><em>
14 This How-To is available <a href="http://bgoglin.free.fr/llgal/">on-line</a>
15 and in the tarball and distribution packages.
16 </em></p>
17
18 <div class="howto">
19
20
21
22 <h2 class="section">Basics</h2>
23
24
25
26 <h3 class="question"><a id="basic_use">How do I use llgal?</a></h3>
27
28 Place some images and movies in a directory and simply run
29 <tt>llgal</tt> inside it.
30 It will generate an index file and some slides.
31
32
33
34 <h3 class="question"><a id="basic_modify">How do I modify a gallery?</a></h3>
35
36 You may add or remove some images in the working directory, and re-run
37 <tt>llgal</tt> with different options to update the gallery contents
38 or layout.
39
40 If an image has been modified, you may have to force the regeneration
41 of thumbnails and scaled images with <tt>-f</tt>.
42
43
44
45 <h3 class="question"><a id="basic_reduce_slide">How do I reduce the size of the slides?</a></h3>
46
47 If your images are large, you should try
48 <pre>
49 llgal --sy 480
50 </pre>
51 to limit the height of the image to 480 pixels in slides.
52
53 Note that a click on the slide will actually open the
54 original full-size image.
55
56 You may even ignore the original images completely by passing
57 <tt>--nf</tt> so as to remove links from slides' scaled images
58 to the original unscaled full images.
59
60
61
62 <h3 class="question"><a id="basic_title_captions">How do I set the title and captions?</a></h3>
63
64 You may set the title on the command line through:
65 <pre>
66 llgal --title "My title"
67 </pre>
68
69 To change captions, the easiest way is to ask <tt>llgal</tt>
70 to generate captions first, with:
71 <pre>
72 llgal --gc
73 </pre>
74 Then, you may edit the captions file (<tt>.llgal/captions</tt>)
75 to update all captions.
76 You then run <tt>llgal</tt> again, it will detect the existence
77 of the captions file and use it.
78 <pre>
79 llgal
80 </pre>
81
82
83
84 <h2 class="section">Captions and special slides</h2>
85
86
87
88 <h3 class="question"><a id="captions_generate">How do I generate captions from images?</a></h3>
89
90 When generating the captions file with <tt>--gc</tt>, <tt>llgal</tt>
91 may automatically generate several fields for each image.
92 Available fields are <b>image comments</b>, <b>filename</b> and
93 <b>image timestamp</b>.
94 <tt>llgal</tt> will try to generate each field and concat them
95 to create the caption.
96
97 To generate captions from the filename only, run:
98 <pre>
99 llgal --gc --cf
100 </pre>
101
102 To generate captions from the image timestamp (extracted from
103 Exif tags when existing) and filename:
104 <pre>
105 llgal --gc --cf --ct
106 </pre>
107
108 To generate captions from the image comments (extract from
109 JFIF or Exif), timestamp and filename:
110 <pre>
111 llgal --gc --cc --cf --ct
112 </pre>
113
114 These commands will generate a captions file that you might then
115 use when generating the gallery.
116 You might also directly generate captions during the gallery
117 generation through something like:
118 <pre>
119 llgal --cc --ct
120 </pre>
121
122 Note that if a captions file exists, command line options about
123 captions generation are omitted.
124
125 Also note that <tt>--cc</tt> and <tt>--ct</tt> require the
126 Image::ExifTool Perl module to be installed.
127
128
129
130 <h3 class="question"><a id="captions_text_link">How do I add a slide containing some text or link?</a></h3>
131
132 After generating the captions file with <tt>--gc</tt>, you might add
133 a special slide containing only some text by inserting the following
134 line in the file:
135 <pre>
136 TXT: the text that is shown in the slide ---- the caption under the slide
137 </pre>
138
139 Regenerating the gallery will then add this slide.
140
141 The following line add a special slide with a link instead of plain text:
142 <pre>
143 LNK: the url ---- the label of the link in the slide ---- the caption under the slide
144 </pre>
145
146 If you do not want those slides containing a single link or text to appear like this,
147 you may use <tt>-L</tt> so that they will be listed as a text line in the index.
148
149 You may also use <tt>LNKNOSLIDE:</tt> entries to add links without slides.
150
151
152
153 <h3 class="question"><a id="captions_add">How do I add new entries to a captions file?</a></h3>
154
155 Re-running <tt>llgal</tt> with <tt>--gc</tt> will rescan the existing files and
156 add the missing ones at the end of the captions file.
157 You then re-run <tt>llgal</tt> to update the gallery regarding the new captions file.
158
159
160
161 <h3 class="question"><a id="captions_keep">How do I keep the list of images involved in a gallery?</a></h3>
162
163 The captions file may also be used to keep track of the contents of a gallery.
164 Even if you do not add some captions or title in the captions file, you may use
165 it to list the exact set of images that you want to appear in the gallery.
166
167
168
169 <h2 class="section">Managing slides</h2>
170
171
172
173 <h3 class="question"><a id="slides_order">How do I change the order of the slides?</a></h3>
174
175 The order of the slides might be changed with the <tt>sort</tt> option
176 on command-line.
177 For instance, <tt>--sort=iname</tt> sorts by name case insensitively,
178 while <tt>--sort=revdate</tt> sorts by date, in reverse order.
179
180 It is also possible to set the order by changing captions positions
181 in the captions file.
182
183
184
185 <h3 class="question"><a id="slides_select">How do I select which files are included in a gallery?</a></h3>
186
187 By default, <tt>llgal</tt> does only include images and movies in the
188 gallery.
189 It is possible to force it to use all existing files in the directory
190 (except <tt>*.html</tt> and <tt>.*</tt>) with:
191 <pre>
192 llgal -A
193 </pre>
194
195 It is also possible to exclude some files with <tt>--exclude regexp</tt>
196 where <tt>regexp</tt> is a Perl regexp. For instance, to exclude all
197 <tt>AVI</tt> files starting with <tt>MVI</tt>:
198 <pre>
199 llgal --exclude 'MVI.*\.AVI'
200 </pre>
201
202 File that were excluded might be reincluded by using the similar
203 <tt>--include</tt> option.
204
205 Finally, it is always possible to exclude files by generating a captions
206 file and removing some entries.
207
208 Note that the captions file is a good way to keep the list of images that
209 are involved in the gallery, even if you do not want any caption.
210
211
212
213 <h2 class="section">Layout</h2>
214
215
216
217 <h3 class="question"><a id="layout_slide_index">How do I change the layout of the slides and index?</a></h3>
218
219 The main layout of generated webpages is based on HTML templates
220 (<tt>indextemplate.html</tt> and <tt>slidetemplate.html</tt>)
221 and a CSS style-sheet (<tt>llgal.css</tt>).
222
223 It is possible to place modified versions of these files in the <tt>.llgal</tt>
224 directory (or in <tt>$HOME/.llgal/</tt>) to change the layout.
225
226
227
228 <h3 class="question"><a id="layout_image_size">Why does llgal ignore the image dimension limits that I give?</a></h3>
229
230 Since <a href="#misc_slow">converting images might be slow</a>, <tt>llgal</tt> does
231 not always regenerate thumbnails and scaled images. By default, it only does if the
232 original images has been changed since last generation.
233
234 To force regeneration, for instance if you changed the thumbnails (with <tt>--tx</tt>
235 or <tt>--ty</tt>) or scaled images dimensions (with <tt>--sx</tt> or <tt>--sy</tt>),
236 you may use <tt>-f</tt> (or <tt>force_image_regeneration</tt>).
237
238
239
240 <h3 class="question"><a id="layout_thumbnail_size">Does changing the maximal thumbnail dimensions really work?</a></h3>
241
242 By default, the width and height of thumbnails are both limited. Both dimension
243 limits may be changed with <tt>--tx</tt> or <tt>--ty</tt>, but changing a single
244 one does affect the other one. It means that the other should be changed too in
245 most of the circumstances.
246
247 Note that changing one of these options requires to
248 <a href="#layout_image_size">force regeneration of thumbnails</a>.
249
250
251
252 <h3 class="question"><a id="layout_slide_dimensions_from_css">How can I get the images in slides to adapt their size to the window?</a></h3>
253
254 <tt>llgal</tt> has been designed to create fixed-size slides. If, instead, you would like your
255 images in slides to follow the size of the window, you may use the <tt>slide_dimensions_from_css</tt>
256 option, either from a configuration file or with <tt>--option</tt> on the command line.
257
258 <tt>llgal</tt> will then remove all absolute dimensions for images in HTML slides.
259 Finally, you will be able to set the image width through the CSS slide sheet (<tt>llgal.css</tt>),
260 for instance by adding <tt>width: 100%</tt> in <tt>table.slide td.image-slide img</tt>.
261
262
263
264 <h3 class="question"><a id="layout_text">How do I change the text that llgal generates in slides and index?</a></h3>
265
266 All text that appears in generated slides might be configured through configuration
267 options.
268
269 One day, there might be a full internationalization support through <tt>gettext</tt>.
270
271
272
273 <h3 class="question"><a id="layout_click_to_next_slide">How can I go to the next slide when clicking on the current one?</a></h3>
274
275 By default, you need to click on <tt>Next</tt> to go to the next slide.
276 If you passed <tt>--sx</tt> or <tt>--sy</tt>, clicking on the slide will lead you to the
277 original image. If not, clicking does nothing.
278 If you want this click to jump to the next slide, you just need to modify the slidetemplate
279 and replace
280 <pre>
281 &lt;!--THIS-SLIDE--&gt;
282 </pre>
283 with
284 <pre>
285 &lt;a href="&lt;!--NEXT-SLIDE--&gt;"&gt;&lt;!--THIS-SLIDE--&gt;&lt;/a&gt;
286 </pre>
287 and regenerate the gallery.
288
289 Of course, if you keep using <tt>--sx</tt> or <tt>--sy</tt>, you will get into problems
290 since there will be 2 hyperlinks on each slide.
291
292
293
294 <h3 class="question"><a id="layout_thumnail_video_subdir">How do I set a thumbnail for a video or a subgallery?</a></h3>
295
296 All non-image slides and thumbnails are usually basic text.
297 It is possible to force <tt>llgal</tt> to use a special thumbnail or scaled image
298 by adding a special file in the local <tt>.llgal</tt> directory with prefix
299 <tt>mythumb_</tt> or <tt>myscaled_</tt>.
300
301 For instance, <tt>mythumb_image24.jpg</tt> will be used as a thumbnail for image
302 <tt>image24.jpg</tt>.
303 <tt>mythumb_subdir3.jpg</tt> will be used for sub-directory <tt>subdir3</tt>.
304 And <tt>myscaled_bar.avi.jpg</tt> will be used as a scaled image for movie <tt>bar.avi</tt>.
305 The extension for the thumbnail or scaled image may be any image extension
306 that <tt>llgal</tt> recognizes.
307
308
309
310 <h3 class="question"><a id="layout_exif">How do I get image EXIF tags in my slides?</a></h3>
311
312 Most images contains some meta-data called EXIF tags that may be useful to some people.
313 <tt>llgal</tt> can display a table of some EXIF values under each image slide.
314 The name of the tags correspond to what the <tt>exiftool</tt> program uses
315 (see for instance <tt>exiftool --list</tt>).
316
317 <pre>
318 llgal --exif Aperture,FocalLength,ImageHeight,ImageWidth,FileModifyDate
319 </pre>
320
321 Note that <tt>--exif</tt> requires the Image::ExifTool Perl module to be installed.
322
323
324
325 <h2 class="section">Configuration</h2>
326
327
328
329 <h3 class="question"><a id="config_save_restore">How do I save/restore a configuration?</a></h3>
330
331 If you like using the same options for all your galleries and don't
332 want to remember the option, you may ask <tt>llgal</tt> to generate
333 a configuration file with:
334 <pre>
335 llgal --gencfg my_llgalrc
336 </pre>
337
338 This file might be used later with
339 <pre>
340 llgal --config my_llgalrc
341 </pre>
342
343 It may also be placed in the user llgal configuration file
344 <tt>$HOME/.llgal/llgalrc</tt>.
345
346 The configuration file contains a list of configuration lines.
347 All command line options, and even much more, are available by
348 this way.
349
350 It is possible to pass any configuration option on the
351 command line with <tt>--option</tt>.
352 For instance, to set which file extensions <tt>llgal</tt> will
353 match to find movies, use:
354 <pre>
355 llgal --option 'movie_extensions="mpe?g|avi|mov|ogm"'
356 </pre>
357
358
359
360 <h2 class="section">Multiple directories and subdirectories</h2>
361
362
363
364 <h3 class="question"><a id="subdirs_include">How do I include several subdirectories in a unique gallery?</a></h3>
365
366 If your photos are organized in several subdirectories of the working directory,
367 you can use <tt>-P</tt> to take the photos from them instead of from the working
368 directory.
369
370 <pre>
371 llgal -P subdir1 -P subdir2 -P subdir3
372 </pre>
373
374 If you want these subdirectories to appear as sections, <tt>llgal</tt> can generate
375 a horizontal line between each subdirectory and add a title in the index with <tt>--Ps</tt>.
376 Additionally, <tt>llgal</tt> can display the title as regular text in the index instead
377 of a text thumbnail with <tt>-L</tt>.
378
379 <pre>
380 llgal -P subdir1 -P subdir2 -P subdir3 --Ps -L
381 </pre>
382
383 As usual, these horizontal lines and titles are generated as TXT and LINE entries
384 are processed from the captions file. Thus, you may start by creating a captions file,
385 edit it and then generate the gallery.
386
387 <pre>
388 llgal -P subdir1 -P subdir2 -P subdir3 --Ps --gc
389 vi .llgal/captions
390 llgal -L
391 </pre>
392
393
394
395 <h3 class="question"><a id="subdirs_include_all">How do I include all subdirectories in a unique gallery?</a></h3>
396
397 Instead of passing <tt>-P</tt> for each subdirectory, you may ask
398 <tt>llgal</tt> to include all images from all subdirectories.
399
400 <pre>
401 llgal --Pall
402 </pre>
403
404
405
406 <h3 class="question"><a id="subdirs_add">How do I add a new subdirectory contents to a gallery?</a></h3>
407
408 You may a the list of files of a subdirectory to an existing gallery if its
409 captions file if available, by regenerating it:
410
411 <pre>
412 llgal -P newsubdir --gc
413 </pre>
414
415 The directory contents is added at the end of the captions file, which may
416 be reordered by the user.
417 The gallery may then be regenerated from the new captions file by re-running
418 <tt>llgal</tt>.
419
420
421
422 <h3 class="question"><a id="subdirs_recursive">How do I create multiple subgalleries at once?</a></h3>
423
424 If your directory contains subdirectories, you might use <tt>-S</tt>
425 to create slides linking to these subgalleries.
426
427 With <tt>-R</tt>, the subgalleries will even be generated right after
428 the main gallery.
429
430 The list of subgalleries might be changed by modifying <tt>DIR:</tt>
431 entries in the captions file.
432
433
434
435 <h3 class="question"><a id="subdirs_modify_single">How do I modify a single gallery in a set of subgalleries?</a></h3>
436
437 Galleries that were created recursively (with <tt>-R</tt>) may be
438 linked with their parents, children and brothers.
439
440 If you plan to regenerate some galleries independently, you should
441 take care of saving the configuration with <tt>--gencfg</tt> or
442 generating a captions file.
443 All linking information is stored inside these files.
444
445 Regeneration is then easy (with <tt>--config</tt> in the first case).
446
447
448
449 <h3 class="question"><a id="subdirs_text_menu">How do I create a text menu linking to multiple galleries?</a></h3>
450
451 Assuming you have a main directory containing multiple subdirectories where you
452 <b>already</b> created sub-galleries, you may do:
453
454 <pre>
455 llgal -L -s
456 </pre>
457
458 Using <tt>-L</tt> will create text links instead of thumbnails linking to sub-galleries,
459 while <tt>-s</tt> will avoid any slide to be created.
460 <br />
461 As you may want slides in the sub-galleries, adding <tt>-R</tt> is not recommended here
462 since <tt>-s</tt> would remove slides from both the main gallery and the sub-galleries.
463 If you need <tt>-R</tt> anyway, you may for instance avoid this problem by dropping
464 <tt>-s</tt> on the command and inserting <tt>make_no_slides=1</tt> in the main gallery
465 configuration file (<tt>.llgal/llgalrc</tt>).
466 Since the local configuration file is used for the local gallery and not for
467 sub-galleries (even with <tt>-R</tt>), <tt>make_no_slides=1</tt> won't
468 affect sub-galleries.
469
470
471
472 <h2 class="section">Miscellaneous</h2>
473
474
475
476 <h3 class="question"><a id="misc_accesskey">How do I add keyboard shortcuts to my gallery?</a></h3>
477
478 The HTML accesskey feature may be use to navigate in <tt>llgal</tt>'s
479 galleries with keyboard shortcuts. But as this feature is very browser
480 dependant and might conflict with some regular shortcuts in certain
481 browsers, it is not enabled by default in <tt>llgal</tt>.
482
483 Access keys can be configured by changing the templates and adding
484 <tt>accesskey=&lt;letter&gt;</tt> to links.
485 For instance, changing the <tt>slidetemplate.html</tt> code to the
486 following one will define <tt>p</tt>, <tt>n</tt> and <tt>i</tt> as
487 accesskeys to previous slide, next slide and return to the index.
488 It means that <tt>Alt+p</tt>, <tt>Alt+n</tt> and <tt>Alt+i</tt> will
489 be the actual shortcuts in Mozilla Firefox.
490
491 <pre>
492 &lt;a href="&lt;!--PREV-SLIDE--&gt;" accesskey=p&gt;&lt;!--PREV-SLIDE-LINK-TEXT--&gt;&lt;/a&gt;
493 &amp;nbsp; &amp;nbsp; &amp;nbsp;
494 &lt;a href="&lt;!--INDEX-FILE--&gt;" accesskey=i&gt;&lt;!--INDEX-LINK-TEXT--&gt;&lt;/a&gt;
495 &amp;nbsp; &amp;nbsp; &amp;nbsp;
496 &lt;a href="&lt;!--NEXT-SLIDE--&gt;" accesskey=n&gt;&lt;!--NEXT-SLIDE-LINK-TEXT--&gt;&lt;/a&gt;
497 </pre>
498
499 Note that the slide template might be modified by getting a copy with
500 in the local or user-wide configuration directory using <tt>--gt</tt>.
501
502
503
504 <h3 class="question"><a id="misc_erase_captions">How do I prevent llgal from erasing my captions file?</a></h3>
505
506 <tt>llgal --clean</tt> erases all files that have not been modified regarding to their
507 original template. The <tt>captions</tt> file does not have a template, so <tt>llgal</tt>
508 will only erase it if it contains the following line:
509 <pre>
510 # REMOVE THIS LINE IF LLGAL SHOULD NOT REMOVE THIS FILE
511 </pre>
512
513 When the user generates the <tt>captions</tt> file himself, he is not supposed
514 to add this line, which means <tt>llgal</tt> won't erase the file.
515 But, when the captions are generated with <tt>llgal --gc</tt>, this line will be added
516 automatically. Hence, if the user modifies the <tt>captions</tt> file, he should start
517 by removing this line first to protect his modifications from future erasing.
518 <br />
519 Note that <tt>llgal --cleanall</tt> erases ALL files, even if you kept the above line
520 in the <tt>captions</tt> file.
521
522
523
524 <h3 class="question"><a id="misc_dynamic_comments">How do I let people add comments to my slides dynamically?</a></h3>
525
526 The <tt>--php</tt> option of <tt>llgal</tt> enables generation of PHP slides
527 instead of HTML. By default, no PHP code is inserted. But, you may change the
528 templates to add some PHP code to do whatever you want, including handle
529 dynamic comments that people may add to your slides.
530 <tt>llgal</tt> comes with some examples, including the directory
531 <tt>dynamic_comments_in_slides/</tt> which gives a quick and dirty example to do so.
532
533
534
535 <h3 class="question"><a id="misc_slow">Why is llgal so slow?</a></h3>
536
537 <tt>llgal</tt> uses <tt>ImageMagick</tt> (and especially <tt>convert</tt>) to generate
538 thumbnails (and scaled images if <tt>--sx</tt> or <tt>--sy</tt> was passed). It can be
539 pretty long if you have lots of large images.
540 To avoid being slow everytime you re-run <tt>llgal</tt>, thumbnails and scaled images
541 are only generated once
542 (except when the original has been modified since or when <tt>-f</tt> is passed, see
543 <a href="#layout_image_size"><em>Why does llgal ignore the image dimension limits that I give?</em></a>).
544
545 There might be some way to improve the overall speed of thumbnails and scaled images
546 generation by changing the corresponding command line with <tt>scaled_create_command</tt>
547 and <tt>thumbnail_create_command</tt> in the configuration file. You may for instance use
548 another conversion program which is more optimized than <tt>ImageMagick</tt> to process
549 your specific images.
550 See tweak_image_generation.txt in the examples in the documentation for details.
551
552
553
554 <h3 class="question"><a id="misc_rotate">Why does llgal not provide any feature to rotate or modify images?</a></h3>
555
556 <tt>llgal</tt> is only a gallery generator. Adding features to rotate images (for instance
557 using Exif tags) or modify images (for instance to apply some filters) would open the door
558 for thousands of options that <tt>llgal</tt> does not really require (and the command line
559 interface is already pretty complex). We prefer keeping those features in other softwares
560 that the user runs before using <tt>llgal</tt>. Also, there is no technical reason to
561 include such filters in <tt>llgal</tt>. Applying them with another specialized software
562 before generating the gallery is as easy, and such software will always provide more features
563 than <tt>llgal</tt>.
564
565
566
567 <h3 class="question"><a id="misc_drop_originals">How do I scale my images to a smaller size and drop the originals?</a></h3>
568
569 <tt>llgal</tt> is not supposed to be used for this
570 (see <a href="#misc_rotate"><em>Why does llgal not provide any feature to rotate or modify images?</em></a>).
571 You should use an external tool earlier and then apply llgal on the scaled images.
572 If you really want to use <tt>llgal</tt> to scale images down, you should use <tt>--sx</tt>
573 and/or <tt>--sy</tt>. The scaled images will be placed in <tt>.llgal/scaled_*</tt>.
574
575 To drop the originals and use the scaled images directly, you should first remove the
576 originals from the main directory. Then move the scaled images from <tt>.llgal</tt> to
577 the main directory and remove the <tt>scaled_</tt> suffix
578 (<tt>rename 's@^\.llgal/scaled_@@' .llgal/scaled_*</tt> should do the trick).
579
580 Finally, re-run the same <tt>llgal</tt> command line without <tt>--sx</tt> and/or
581 <tt>--sy</tt>.
582 You should get the same gallery as before, without the links from the slides to the
583 original images.
584
585
586
587
588 </div>
589
590 <hr />
591
592 <address id="addr">
593 The <a href="mailto:llgal AT googlegroups.com">llgal team</a>.
594 </address>
595
596 <div id="modif">
597 $Id: howto.html,v 1.1 2006/05/07 00:46:01 bgoglin Exp $
598 </div>
599
600 </body>
601 </html>