Mercurial > bins

comparison doc/bins.1 @ 0:a84c32f131df 1.1.29

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import vendor version
author Peter Gervai <grin@grin.hu>
date Wed, 15 Oct 2008 23:28:56 +0200
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:a84c32f131df
1 .TH "BINS" "1"
2 .SH "NAME"
3 bins \(em Generate a static HTML photo albums using XML and EXIF tags
4 .SH "SYNOPSIS"
5 .PP
6 \fBbins\fR [\fB-f \fIconfig_file\fR\fP] [\fB-o \fISTR\fR\fP] [\fB-d \fISTR\fR\fP] [\fB-c \fIcolor_style\fR\fP] [\fB-s \fIstyle\fR\fP] [\fB-t \fItemplate_dir\fR\fP] [\fB-p\fP] [\fB-e\fP] [\fB-i \fIiKey,iKey...\fR\fP] [\fB-v \fIX\fR\fP] [\fB-h\fP] \fIsource_dir\fR \fItarget_dir\fR
7 .SH "DESCRIPTION"
8 .PP
9 This manual page documents briefly the
10 \fBbins\fR command.
11 .PP
12 This manual page was written for the \fBDebian\fP distribution
13 because the original program does not have a manual page.
14 Instead, it has documentation in HTML in
15 \fB/usr/share/doc/bins/index.html\fP as well as a
16 \fB-h\fP option.
17 .PP
18 \fBbins\fR is a program that takes a
19 collection of directories and files containing
20 JPEG images and XML descriptions, combines them with a set of
21 HTML templates, and produces a complete photo
22 gallery of static HTML files, rescaled images
23 at three sizes, and thumbnails.
24 .SH "OPTIONS"
25 .IP "\fB-f \fIconfig_file\fR\fP" 10
26 use an alternative configuration file, instead of
27 \fB~/.bins/binsrc.\fP.
28 .IP "\fB-o \fISTR\fR\fP" 10
29 Tells script to use only one copy of image using
30 HTML size specs (height, width specs in the image
31 tag) for scaled versions (instead of generating
32 several images, one for each size).
33 .IP "" 10
34 Default is false.
35 .IP "" 10
36 \fISTR\fR is an optional argument
37 to set how the one image is generated. Possible values:
38
39 .RS
40 .IP "scaled" 10
41 (make scaled copy of orig in target_dir
42 hierarchy, sized to max size). Default.
43 .IP "copied" 10
44 (copy orig to web dir)
45 .IP "custom" 10
46 (use copy if filesize < 1meg
47 resize, resave, if bigger than 1 meg)
48 .RE
49
50 .IP "\fB-d \fISTR\fR\fP" 10
51 Determine if tags found in EXIF structure are
52 added in desc files.
53 .IP "" 10
54 \fISTR\fR is one of "always", "never" or "exist"
55 ("exist" only adds if the desc file already exist.)
56 Default is always.
57 .IP "\fB-c \fIcolor_style\fR\fP" 10
58 Color style to use. Can be \fBblue\fP (default one), \fBgreen\fP,
59 \fBivory\fP and \fBpink\fP or
60 any other one defined in configuration/description files.
61 This option is deprecated (and thus, not supported by all
62 templates), in favor of alternate stylesheets and the
63 \fBcustomStyleSheet\fP parameter.
64 .IP "\fB-s \fIstyle\fR\fP" 10
65 Template style to use (styles provided for now are
66 \fBjoi\fP, \fBmarc\fP,
67 \fBmartin\fP, \fBmwolson\fP \fBpetrus\fP, \fBsatyap\fP and
68 \fBswigs\fP).
69 .IP "\fB-t \fItemplate_dir\fR\fP" 10
70 Specify location of html templates.
71 .IP "" 10
72 Default is \fB~/.bins\fP, falling back
73 to default versions in
74 \fB/etc/bins/templates.\fIstyle\fR\fP.
75 .IP "\fB-p\fP " 10
76 Numbers preceding the album title, followed by
77 an underscore are stripped.
78 If this option is given, then prefix ordering
79 numbers on directories are removed. For example,
80 if one has directories \fBmay\fP,
81 \fBjune\fP, and \fBaugust\fP, they
82 can be renamed \fB0_may\fP,
83 \fB1_june\fP, and \fB2_august\fP and
84 they will appear in the album in the correct
85 order.
86 .IP "\fB-e\fP" 10
87 Tells the script to generate an editable version of
88 the album. If set, some more links and icons are added to
89 directly access the \fB.xml\fP files for
90 editing. This is for editing purposes, not for a final
91 album.
92 .IP "\fB-i \fIiKey,iKey...\fR\fP" 10
93 Sets "ignore" keywords which will be compared against
94 the contents of the \fBignore\fP field of the
95 album's XML file, in the \fBignore\fP field in
96 \fBdescription\fP section. If any of the
97 \fIiKeys\fR match those in the album's
98 "ignore" field, that album will not be processed. See also
99 the \fBignore\fP parameter.
100 .IP "\fB-n \fIiKey,iKey...\fR\fP" 10
101 Sets "hidden" keywords which will be compared against
102 the contents of the \fBignore\fP field of the
103 album's XML file, in the \fBignore\fP field in
104 \fBdescription\fP section. If any of the
105 \fIiKeys\fR match those in the album's
106 "ignore" field, that album will be hidden: it will not be
107 linked anywhere. See also the \fBhidden\fP parameter.
108 .IP "\fB-v \fIX\fR\fP " 10
109 \fIX\fR is the verbosity level (between 0 and 3)
110 .IP "\fB-h\fP " 10
111 Show the help string this man page was originally based on.
112 .SH "SETTINGS"
113 .PP
114 bins is also controlled by other files.
115 .IP "\fB/etc/bins/binsrc\fP" 10
116 .IP "\fB~/.bins/binsrc\fP" 10
117 The \fBbinsrc\fP files are
118 XML files with a top level
119 \fBbins\fP tag. There are three element
120 names with \fBbins\fP: \fBparameter\fP,
121 \fBcolors\fP, and \fBsizes\fP.
122 Each of these has a \fBname\fP attribute
123 which names the data in the element content.
124 .IP "" 10
125 The \fBcolors\fP element has a
126 \fBstyle\fP attribute, that can be used with
127 the \fBcolorStyle\fP parameter or the
128 \fB-c\fP command line option. It contains
129 \fBcolor\fP elements. The
130 \fBcolor\fP elements name has one of the
131 following values which is substituted into the template
132 files. This tag is deprecated, in favor of alternate
133 stylesheets and the \fBcustomStyleSheet\fP parameter.
134 .RS
135 .IP "" 10
136 PAGE_BACK
137 .IP "" 10
138 PAGE_TITLE
139 .IP "" 10
140 MAINBAR_BACK
141 .IP "" 10
142 MAINBAR_TITLE
143 .IP "" 10
144 MAINBAR_LINK
145 .IP "" 10
146 MAINBAR_CURRENTPAGE
147 .IP "" 10
148 SUBBAR_BACK
149 .IP "" 10
150 SUBBAR_LINK
151 .IP "" 10
152 SUBBAR_CURRENTPAGE
153 .IP "" 10
154 SUBBAR_TITLE
155 .RE
156 .IP "" 10
157 The \fBsizes\fP element contains
158 \fBsize\fP elements which each have a
159 \fBname\fP attribute, a
160 \fBshortname\fP attribute, a
161 \fBheight\fP attribute, and a
162 \fBwidth\fP attribute. These default to
163 .RS
164 .IP "" 10
165 Small, Sm, 40%, 40%
166 .IP "" 10
167 Medium, Med, 64%, 64%
168 .IP "" 10
169 Large, Lg, 100%, 100%
170 .RE
171 .IP "" 10
172 \fBname\fP and
173 \fBshortname\fP are used in the output
174 HTML and in generated filenames. The
175 default values listed above are passed through
176 \fBgettext\fP for localization; overrides
177 in \fBbinsrc\fP files are not, and should
178 be in the desired language.
179 .IP "" 10
180 For the \fBparameter\fP elements the
181 \fBname\fP attribute names one of the
182 following parameters.
183 .RS
184 .IP "addExifToDescFile" 10
185 If set to 1 (the default), write EXIF data found in
186 the image file to the image desc file (but see also
187 the \fB-d\fP flag).
188 .IP "albumThumbInSubAlbumPage" 10
189 If set to 1 (the default), display the current
190 album thumbnail in sub-albums page
191 if it has pictures, with links to
192 the thumbnails page.
193 .IP "allThumbnailsPage" 10
194 If set to \fB1\fP, generate a page with all
195 thumbnails in the album and
196 sub-albums. This is deactivated
197 because it is an alpha feature which
198 seems to not work properly.
199 .IP "backgroundImage" 10
200 Set this to the image that should be displayed
201 as the background of the album pages. The Image will
202 be copied to the static files directory. This works
203 only with joi, marc, martin and petrus templates for now.
204
205 .IP "borderOnThumbnails" 10
206 Width of the border of the thumbnail's image in
207 the thumbnails page, in pixels. \fB0\fP means no border.
208
209 .IP "colorStyle" 10
210 Name of the color style to use. Default is
211 \fBblue\fP. See also the
212 \fB-c\fP option which takes precedence.
213 This option is deprecated (and thus, not supported by
214 all templates), in favor of alternate stylesheets and
215 the \fBcustomStyleSheet\fP parameter.
216 .IP "compactHTML" 10
217 If set to \fB1\fP, generated
218 HTML code is cleaned up to reduce
219 the size of pages and thus, speed up browsing. This
220 reduces the size of HTML BINS files
221 by about 30%. See \fBHTML::Clean(3)\fR to
222 know how optimizations are performed.
223 .IP "configFileName" 10
224 Can be set in the global config file, but only
225 influences the basename of the local user config
226 file. Defaults to \fB.binsrc\fP.
227 .IP "createEmptyDescFields" 10
228 If set to 1 (the default), add empty description
229 fields in the \fBdescription\fP section
230 when the image description file is created to ease
231 later manual editing.
232 .IP "createHtaccess" 10
233 If \fB1\fP, create an Apache
234 \fB.htaccess\fP file in the root dir of
235 the album with the encoding charset bound to
236 \fBhtml\fP and \fBhtm\fP files. This is a parameter global for the album, it
237 can't be set in album.xml.
238 .IP "customStyleSheet" 10
239 Set this to the CSS file that should be used as
240 the stylesheet for the album pages. The CSS file will
241 be copied to the static files directory. This works
242 only with joi, marc, martin and petrus templates for now.
243
244 .IP "dateString" 10
245 Specify the format of date strings. This variable
246 accepts all formats supported by \fBdate(1)\fR.
247
248 .IP "defaultSize" 10
249 Size to use when user clicks directly on the
250 thumbnail in the thumbnails page instead of one of
251 the size name. 0 is the first size
252 (\fBSmall\fP in the default config), 1
253 the second (\fBMedium\fP), and so
254 on. Set this variable to \-1 if you don't want the
255 thumbnail to be clickable.
256 .IP "deExifyImages" 10
257 If set to 1, do NOT copy exif data found in the
258 source images to any of the generated resized images.
259 Setting this option can yield significant space
260 savings, especially for thumbnail and imagelist
261 pages.
262 .IP "emptyAlbumDesc" 10
263 If set to 1, and album desciption is not set, no
264 message will be displayed (instead of the "No
265 long/short description available" one).
266 .IP "enlarge" 10
267 If set to 1, small images are enlarged
268 in the "med" and "large" series. (defaults to 0).
269 .IP "excludeBackgroundImage" 10
270 If set to 1, the image with the name given in
271 \fBbackgroundImage\fP will be excluded from the
272 current directory.
273
274 .IP "excludeDirs" 10
275 Exclude directories that match this regexp (if
276 set). Set to
277 CVS$ in default config, so that CVS
278 subdirs aren't processed by bins.
279
280 .IP "excludeFiles" 10
281 Exclude image files that match this regexp (if
282 set). No image files are excluded in default config.
283
284 .IP "globalConfigDir" 10
285 Can't usefully be set, since it has already been
286 used when the first config file is read. Defaults
287 to \fB/etc/bins\fP.
288 .IP "hidden" 10
289 Put here a comma separated list of keyword. If
290 one on this keyword is found in the
291 \fBignore\fP field in the
292 \fBdescription\fP section of an
293 \fBalbum.xml\fP, then this sub-album
294 will be hidden, i.e. it will be generated but not
295 linked anywhere. You can also use the
296 \fB-n\fP command line option.
297 .IP "homeURL" 10
298 Set this to your home page's
299 URL. This is used for the leave button
300 in some templates.
301 .IP "htmlEncoding" 10
302 HTML pages charset encoding.
303 .IP "ignore" 10
304 Put here a comma separated list of keyword. If
305 one on this keyword is found in the
306 \fBignore\fP field in the
307 \fBdescription\fP section of an
308 \fBalbum.xml\fP, then this sub-album
309 will be ignored, i.e. it will not be processed. You
310 can also use the \fB-i\fP command line
311 option.
312 .IP "imagePageCycling" 10
313 If set to 0 next/prev-Links will be hidden if
314 the actual page is the last/first Image page.
315 .IP "javaScriptPreloadImage" 10
316 If set to \fB1\fP, add some
317 javascript code in image pages to preload the next
318 image of the same size when current one is loaded, to
319 speed up the album browsing.
320 .IP "javaScriptPreloadThumbs" 10
321 If set to \fB1\fP, add some
322 javascript code in thumbnails pages to preload
323 thumbnails of the next page when current one is
324 loaded, to speed up the album browsing.
325 .IP "jpegQuality" 10
326 Quality of scaled jpegs (lower number = more
327 compression, lower quality) in 1-100 range (default
328 of 75). See imagemagick docs for more details.
329 .IP "linkInsteadOfCopy" 10
330 If set to 1, we link the picture instead of
331 copying it if possible (i.e. scaleIfSameSize is set to
332 \fB0\fP and destination image doesn't
333 have to be rotated: \fBrotateImages\fP is
334 set to \fBoriginal\fP or
335 \fBnone\fP, or orientation is already
336 correct). Warning : if whenSrcSmaller is set
337 to enlarge, original image can be modified.
338 .IP "linkRelative" 10
339 If set to 1, we use a relative path for the link if
340 \fBlinkInsteadOfCopy\fP is set to 1.
341
342 .IP "maxAlbumsForLongSubAlbum" 10
343 If the number of sub albums is greater (than
344 this value which defaults to 20),
345 generate a short sub album page
346 instead of the long one. (Short sub album pages
347 appear to be unsupported at the moment; this option
348 is disabled.)
349 .IP "noRotation" 10
350 Don't perform rotation on files matching this
351 regexp. This can used in conjunction with
352 \fBscaleIfSameSize=0\fP and a scaled size of
353 \fB100%x100%\fP to keep original pictures in
354 your album.
355 .IP "numThumbsPerPage" 10
356 Number of thumbnails (default of 16) displayed
357 in each page in an album.
358 .IP "pathImgNum" 10
359 If set to 1 the path in the imageview contains
360 the number of the current image.
361 .IP "pathShowIcon" 10
362 If set to 1 the path contains icons.
363 .IP "previewMaxWidth" 10
364 .IP "previewMaxHeight" 10
365 Max thumbnail width and height (default 150x150).
366 .IP "jpegProgressify" 10
367 whether to convert generated jpegs to
368 progressive using jpegtran (if available). can be
369 \fBnever\fP, \fBalways\fP, or
370 \fBsmaller\fP (if the progressified file
371 is smaller than the baseline).
372 .IP "reverseOrder" 10
373 Are we reversing sorting order for pictures or
374 directories ? 0=none, 1=dirs, 2=pix, 3=both. See
375 also \fB-r\fP command line option.
376
377 .IP "rotateImages" 10
378 Do we rotate images if the
379 \fBOrientation\fP EXIF tag is found? If set to \fBoriginal\fP (the default), the original image is rotated the first
380 time, and then it is left untouched. If set to
381 \fBdestination\fP, this is all the scaled
382 images and thumbnails that are rotated. This is less
383 efficient, but the original images are preserved (and
384 is useful if the original images are read-only). If
385 set to \fBnone\fP, no rotation is
386 performed.
387 .IP "rotateWithJpegtran" 10
388 If set to \fB1\fP,
389 \fBbins\fP try to use the
390 \fBjpegtran\fP program to rotate
391 JPEG images if it is
392 available. \fBjpegtran\fP is faster and
393 lossless, but some versions fail to perform rotation
394 correctly, so it is deactivated in default config. If
395 set to \fB0\fP or if
396 \fBjpegtran\fP is not found,
397 \fBmogrify\fP (from ImageMagick) is
398 used.
399 .IP "scaleIfSameSize" 10
400 If set to 1, we scale the picture even
401 if destination size is the same as the
402 original picture, if set to 0 (the default), the
403 original image is just copied if the
404 size is correct.
405 .IP "scaleMethod" 10
406 What method should be used to create scaled
407 pictures and thumbnails ? Can be either
408 \fBscale\fP or
409 \fBsample\fP. \fBsample\fP is \fBfaster\fP, scale is better.
410
411 .IP "searchEngine" 10
412 If 1, generate a search page. Images can be searched
413 on description fields set in the
414 \fBsearchFields\fP parameter.
415
416 .IP "searchFields" 10
417 Space separated list of description field names used
418 by the search engine, if
419 \fBsearchEngine\fP is set to 1.
420
421 .IP "searchLimit" 10
422 Maximum results returned by the search engine, if
423 \fBsearchEngine\fP is set to 1. Note
424 that if this number is too high, it can hang the
425 browser.
426
427 .IP "stripDirPrefix" 10
428 If \fB1\fP, numbers preceding the
429 album title, followed by an underscore, are
430 stripped. If this parameter is set, then prefix
431 ordering numbers on directories are removed. For
432 example, if one has directories may, june, and august,
433 they can be renamed \fB0_may\fP,
434 \fB1_june\fP, and
435 \fB2_august\fP and they will appear in
436 the album in the correct order. This can be overridden
437 by the \fB-p\fP command line option.
438 .IP "templateStyle" 10
439 Name of the template style to use. Default is
440 \fBswigs\fP. Other templates provided
441 with BINS are \fBjoi\fP,
442 \fBmarc\fP, \fBmartin\fP,
443 \fBpetrus\fP and
444 \fBsatyap\fP. Several templates can be
445 used for different sub-album of an album, by using
446 this parameter in the \fBbins\fP section
447 of the \fBalbum.xml\fP files. See also
448 the \fB-s\fP option which takes precedence
449 over binsrc (but not album.xml).
450 .IP "thumbnailBackground" 10
451 If set to 1, add a background colour
452 (SUBBAR_BACK) to the thumbnail's cell in the
453 thumbnails page so that if the top and bottom borders
454 are wider than the image (for example, if it is in
455 portrait mode), instead of spilling over, there is a
456 border around the whole picture. By default, use the
457 PAGE_BACK color.
458 .IP "thumbnailInImageList" 10
459 Display thumbnails on the Image List page, set
460 to 1 by default.
461 .IP "thumbnailPageCycling" 10
462 If set to 0 next/prev-Links will be hidden if
463 the actual page is the last/first
464 Thumbnail page.
465 .IP "thumbPrevNext" 10
466 If set to 1 (the default), display thumbnails close
467 to the previous and next link at the
468 bottom of the image page.
469 .IP "thumbsPerRow" 10
470 Number of thumbnails (default of 4) displayed in each
471 row in an album.
472 .IP "titleOnThumbnail" 10
473 Should the title be displayed on top on the
474 thumbnail in the thumbnails page? (defaults to 1.)
475 .IP "treePreview" 10
476 If set to 1, preview thumbnails will be showed
477 in the album tree page. This works only with joi,
478 marc and petrus templates for now.
479
480 .IP "updateOriginalPerms" 10
481 If set to 1, read permissions on images will be
482 set, to ensure http deamon will be able to read
483 them.
484
485 .IP "userConfigDir" 10
486 Can be set in the global config file (since
487 after the user one is read, it is too late).
488 Defaults to \fB~/.bins\fP and is
489 processed by \fBbsd_glob\fP (see
490 \fBFile::Glob\fP for details.)
491
492 .IP "xmlEncoding" 10
493 XML files charset encoding.
494 .RE
495 .IP "\fB\fIimage.jpg\fR\fP" 10
496 The EXIF tags are extracted from
497 the image. Currently only the
498 \fBOrientation\fP tag influences the
499 processing, but a variety of settings are copied into the
500 HTML file generated via the
501 \fBdetails.html\fP template.
502 .IP "\fB\fIimage.jpg\fR.xml\fP" 10
503 The XML file contains an
504 \fBimage\fP element, which contains three child
505 elements:
506 .RS
507 .IP "\fBdescription\fP" 10
508 which has \fBfield\fP children that
509 contain per-image data. The \fBname\fP attribute names the tag (allowing simple
510 extensibility, see the
511 \fBbins_edit\fP \fB\-\-generic\fP flag) but
512 \fBbins\fP itself currently only
513 makes use of
514 .RS
515 .IP "" 10
516 title
517 .IP "" 10
518 description
519 .IP "" 10
520 people
521 .IP "" 10
522 location
523 .IP "" 10
524 date
525 .IP "" 10
526 event
527 .RE
528 .IP "\fBbins\fP" 10
529 which works as described with the
530 \fBbinsrc\fP file settings, except
531 that many of the settings are not meaningful in the
532 context of a single picture.
533 .IP "\fBexif\fP" 10
534 which has a cache of values copied from the
535 EXIF tags in the image, to allow
536 simpler processing by other tools.
537 .IP "" 10
538 If a user wants to override the
539 EXIF values and provide a
540 replacement (such as a corrected
541 \fBOrientation\fP or an
542 \fBOwner\fP setting that reflects who
543 you loaned the camera to) adding a
544 \fBpriority\fP attribute with a value
545 of "1" will prevent \fBbins\fP from
546 replacing it with the value in the image.
547 .RE
548 .IP "\fBalbum.xml\fP" 10
549 This file contains an
550 \fBalbum\fP element, which contains
551 \fBdescription\fP and \fBbins\fP stanza as described for an image. The are extensible in
552 the same manner, but \fBbins\fP only makes
553 use of
554 .RS
555 .IP "" 10
556 dirname
557 .IP "" 10
558 descFileName
559 .IP "" 10
560 shortdesc
561 .IP "" 10
562 title
563 .IP "" 10
564 sampleimage
565 .IP "" 10
566 longdesc
567 .RE
568 .IP "\fBinclude_images.txt\fP" 10
569 includes image filenames (relative to the current
570 album, i.e. the directory where the
571 \fBinclude_images.txt\fP file is stored.)
572 Each filename appears on a line by itself; a line
573 beginning with a \fB#\fP is a comment, and
574 lines composed entirely of whitespace are ignored.
575 Otherwise, the line is exactly the filename. These images
576 are included in the order listed, and added after any that
577 actually appear in the directory.
578 .IP "\fB\fItemplate\fR.html\fP" 10
579 There are a number of template
580 HTMLfiles which are used to generate
581 the actual images. The base names of these are
582 .RS
583 .IP "" 10
584 tree
585 .IP "" 10
586 imagelist
587 .IP "" 10
588 subalbum
589 .IP "" 10
590 thumbnail
591 .IP "" 10
592 details
593 .IP "" 10
594 image
595 .RE
596 .IP "" 10
597 The default versions of these files in
598 \fB/etc/bins/templates.default\fP should
599 show how they work, as does the
600 \fBHTML::Template\fP documentation. Aside
601 from the \fBCOLOR\fP substitutions described
602 above, a template can also reference
603 .RS
604 .IP "" 10
605 BINS_VERSION
606 .IP "" 10
607 ENCODING
608 .IP "" 10
609 GENERATED_DATE
610 .IP "" 10
611 BINS_ID
612 .RE
613 .SH "SEE ALSO"
614 .PP
615 bins_edit (1), jpegtran (1), File::Glob, HTML::Template, imagemagick.
616 .SH "AUTHOR"
617 .PP
618 This manual page was written by Mark W. Eichin eichin@thok.org for
619 the \fBDebian\fP system (but may be used by others). As it is
620 mostly derived from the \fBbins\fP program
621 itself, it is covered by the GNU General Public License.
622 .\" created by instant / docbook-to-man, Wed 24 Aug 2005, 23:31