Ubuntu Manpage: bins — Generate a static HTML photo albums using XML and EXIF tags

NAME

       bins — Generate a static HTML photo albums using XML and EXIF tags

SYNOPSIS

       bins [-f config_file]  [-o STR]  [-d STR]  [-c color_style]  [-s style]  [-t template_dir]
       [-p]  [-e]  [-i iKey,iKey...]  [-v X]  [-h] source_dir target_dir

DESCRIPTION

       This manual page documents briefly the bins command.

       This manual page was written for the Debian distribution because the original program does
       not    have    a    manual   page.    Instead,   it   has   documentation   in   HTML   in
       /usr/share/doc/bins/index.html as well as a -h option.

       bins is a program that takes a collection of directories and files containing JPEG  images
       and  XML        descriptions,  combines  them with a set of HTML templates, and produces a
       complete photo gallery  of  static  HTML  files,  rescaled  images  at  three  sizes,  and
       thumbnails.

OPTIONS

-f config_file
use an alternative configuration file, instead of ~/.bins/binsrc..

-o STR Tells script to use only one copy of image using HTML size specs (height, width
specs in the image tag) for scaled versions (instead of generating several
images, one for each size).

Default is false.

STR is an optional argument to set how the one image is generated. Possible
values:

scaled (make scaled copy of orig in target_dir hierarchy, sized to max size).
Default.

copied (copy orig to web dir)

custom (use copy if filesize < 1meg resize, resave, if bigger than 1 meg)

-d STR Determine if tags found in EXIF structure are added in desc files.

STR is one of "always", "never" or "exist" ("exist" only adds if the desc file
already exist.) Default is always.

-c color_style
Color style to use. Can be blue (default one), green, ivory and pink or
any other one defined in configuration/description files. This option is
deprecated (and thus, not supported by all templates), in favor of alternate
stylesheets and the customStyleSheet parameter.

-s style Template style to use (styles provided for now are joi, marc, martin, mwolson
petrus, satyap and swigs).

-t template_dir
Specify location of html templates.

Default is ~/.bins, falling back to default versions in
/usr/share/bins/templates.style.

-p Numbers preceding the album title, followed by an underscore are stripped. If
this option is given, then prefix ordering numbers on directories are removed.
For example, if one has directories may, june, and august, they can be renamed
0_may, 1_june, and 2_august and they will appear in the album in the correct
order.

-e Tells the script to generate an editable version of the album. If set, some
more links and icons are added to directly access the .xml files for editing.
This is for editing purposes, not for a final album.

-i iKey,iKey...
Sets "ignore" keywords which will be compared against the contents of the ignore
field of the album's XML file, in the ignore field in description section. If
any of the iKeys match those in the album's "ignore" field, that album will not
be processed. See also the ignore parameter.

-n iKey,iKey...
Sets "hidden" keywords which will be compared against the contents of the ignore
field of the album's XML file, in the ignore field in description section. If
any of the iKeys match those in the album's "ignore" field, that album will be
hidden: it will not be linked anywhere. See also the hidden parameter.

-v X X is the verbosity level (between 0 and 3)

-h Show the help string this man page was originally based on.

SETTINGS

bins is also controlled by other files.

/etc/bins/binsrc

~/.bins/binsrc
The binsrc files are XML files with a top level bins tag. There are three
element names with bins: parameter, colors, and sizes. Each of these has a name
attribute which names the data in the element content.

The colors element has a style attribute, that can be used with the colorStyle
parameter or the -c command line option. It contains color elements. The color
elements name has one of the following values which is substituted into the
template files. This tag is deprecated, in favor of alternate stylesheets and
the customStyleSheet parameter.

PAGE_BACK

PAGE_TITLE

MAINBAR_BACK

MAINBAR_TITLE

MAINBAR_LINK

MAINBAR_CURRENTPAGE

SUBBAR_BACK

SUBBAR_LINK

SUBBAR_CURRENTPAGE

SUBBAR_TITLE

The sizes element contains size elements which each have a name attribute, a
shortname attribute, a height attribute, and a width attribute. These default
to

Small, Sm, 40%, 40%

Medium, Med, 64%, 64%

Large, Lg, 100%, 100%

name and shortname are used in the output HTML and in generated filenames. The
default values listed above are passed through gettext for localization;
overrides in binsrc files are not, and should be in the desired language.

For the parameter elements the name attribute names one of the following
parameters.

addExifToDescFile
If set to 1 (the default), write EXIF data found in the image file to
the image desc file (but see also the -d flag).

albumThumbInSubAlbumPage
If set to 1 (the default), display the current album thumbnail in sub-
albums page if it has pictures, with links to the thumbnails page.

allThumbnailsPage
If set to 1, generate a page with all thumbnails in the album and sub-
albums. This is deactivated because it is an alpha feature which seems
to not work properly.

backgroundImage
Set this to the image that should be displayed as the background of
the album pages. The Image will be copied to the static files
directory. This works only with joi, marc, martin and petrus templates
for now.

borderOnThumbnails
Width of the border of the thumbnail's image in the thumbnails page,
in pixels. 0 means no border.

colorStyle
Name of the color style to use. Default is blue. See also the -c
option which takes precedence. This option is deprecated (and thus,
not supported by all templates), in favor of alternate stylesheets and
the customStyleSheet parameter.

compactHTML
If set to 1, generated HTML code is cleaned up to reduce the size of
pages and thus, speed up browsing. This reduces the size of HTML BINS
files by about 30%. See HTML::Clean(3) to know how optimizations are
performed.

configFileName
Can be set in the global config file, but only influences the basename
of the local user config file. Defaults to .binsrc.

createEmptyDescFields
If set to 1 (the default), add empty description fields in the
description section when the image description file is created to ease
later manual editing.

createHtaccess
If 1, create an Apache .htaccess file in the root dir of the album
with the encoding charset bound to html and htm files. This is
a parameter global for the album, it can't be set in album.xml.

customStyleSheet
Set this to the CSS file that should be used as the stylesheet for the
album pages. The CSS file will be copied to the static files
directory. This works only with joi, marc, martin and petrus templates
for now.

dateString
Specify the format of date strings. This variable accepts all formats
supported by date(1).

defaultSize
Size to use when user clicks directly on the thumbnail in the
thumbnails page instead of one of the size name. 0 is the first size
(Small in the default config), 1 the second (Medium), and so on. Set
this variable to -1 if you don't want the thumbnail to be clickable.

deExifyImages
If set to 1, do NOT copy exif data found in the source images to any
of the generated resized images. Setting this option can yield
significant space savings, especially for thumbnail and imagelist
pages.

emptyAlbumDesc
If set to 1, and album desciption is not set, no message will be
displayed (instead of the "No long/short description available" one).

enlarge If set to 1, small images are enlarged in the "med" and "large"
series. (defaults to 0).

excludeBackgroundImage
If set to 1, the image with the name given in backgroundImage will be
excluded from the current directory.

excludeDirs
Exclude directories that match this regexp (if set). Set to CVS$ in
default config, so that CVS subdirs aren't processed by bins.

excludeFiles
Exclude image files that match this regexp (if set). No image files
are excluded in default config.

globalConfigDir
Can't usefully be set, since it has already been used when the first
config file is read. Defaults to /etc/bins.

hidden Put here a comma separated list of keyword. If one on this keyword is
found in the ignore field in the description section of an album.xml,
then this sub-album will be hidden, i.e. it will be generated but not
linked anywhere. You can also use the -n command line option.

homeURL Set this to your home page's URL. This is used for the leave button in
some templates.

htmlEncoding
HTML pages charset encoding.

ignore Put here a comma separated list of keyword. If one on this keyword is
found in the ignore field in the description section of an album.xml,
then this sub-album will be ignored, i.e. it will not be processed.
You can also use the -i command line option.

imagePageCycling
If set to 0 next/prev-Links will be hidden if the actual page is the
last/first Image page.

javaScriptPreloadImage
If set to 1, add some javascript code in image pages to preload the
next image of the same size when current one is loaded, to speed up
the album browsing.

javaScriptPreloadThumbs
If set to 1, add some javascript code in thumbnails pages to preload
thumbnails of the next page when current one is loaded, to speed up
the album browsing.

jpegQuality
Quality of scaled jpegs (lower number = more compression, lower
quality) in 1-100 range (default of 75). See imagemagick docs for
more details.

linkInsteadOfCopy
If set to 1, we link the picture instead of copying it if possible
(i.e. scaleIfSameSize is set to 0 and destination image doesn't have
to be rotated: rotateImages is set to original or none, or orientation
is already correct). Warning : if whenSrcSmaller is set to enlarge,
original image can be modified.

linkRelative
If set to 1, we use a relative path for the link if linkInsteadOfCopy
is set to 1.

maxAlbumsForLongSubAlbum
If the number of sub albums is greater (than this value which defaults
to 20), generate a short sub album page instead of the long one.
(Short sub album pages appear to be unsupported at the moment; this
option is disabled.)

noRotation
Don't perform rotation on files matching this regexp. This can used in
conjunction with scaleIfSameSize=0 and a scaled size of 100%x100% to
keep original pictures in your album.

numThumbsPerPage
Number of thumbnails (default of 16) displayed in each page in an
album.

pathImgNum
If set to 1 the path in the imageview contains the number of the
current image.

pathShowIcon
If set to 1 the path contains icons.

previewMaxWidth

previewMaxHeight
Max thumbnail width and height (default 150x150).

jpegProgressify
whether to convert generated jpegs to progressive using jpegtran (if
available). can be never, always, or smaller (if the progressified
file is smaller than the baseline).

reverseOrder
Are we reversing sorting order for pictures or directories ? 0=none,
1=dirs, 2=pix, 3=both. See also -r command line option.

rotateImages
Do we rotate images if the Orientation EXIF tag is found? If
set to original (the default), the original image is rotated the
first time, and then it is left untouched. If set to destination, this
is all the scaled images and thumbnails that are rotated. This is less
efficient, but the original images are preserved (and is useful if the
original images are read-only). If set to none, no rotation is
performed.

rotateWithJpegtran
If set to 1, bins try to use the jpegtran program to rotate JPEG
images if it is available. jpegtran is faster and lossless, but some
versions fail to perform rotation correctly, so it is deactivated in
default config. If set to 0 or if jpegtran is not found, mogrify (from
ImageMagick) is used.

scaleIfSameSize
If set to 1, we scale the picture even if destination size is the same
as the original picture, if set to 0 (the default), the original image
is just copied if the size is correct.

scaleMethod
What method should be used to create scaled pictures and thumbnails ?
Can be either scale or sample. sample is faster, scale is
better.

searchEngine
If 1, generate a search page. Images can be searched on description
fields set in the searchFields parameter.

searchFields
Space separated list of description field names used by the search
engine, if searchEngine is set to 1.

searchLimit
Maximum results returned by the search engine, if searchEngine is set
to 1. Note that if this number is too high, it can hang the browser.

stripDirPrefix
If 1, numbers preceding the album title, followed by an underscore,
are stripped. If this parameter is set, then prefix ordering numbers
on directories are removed. For example, if one has directories may,
june, and august, they can be renamed 0_may, 1_june, and 2_august and
they will appear in the album in the correct order. This can be
overridden by the -p command line option.

templateStyle
Name of the template style to use. Default is swigs. Other templates
provided with BINS are joi, marc, martin, petrus and satyap. Several
templates can be used for different sub-album of an album, by using
this parameter in the bins section of the album.xml files. See also
the -s option which takes precedence over binsrc (but not album.xml).

thumbnailBackground
If set to 1, add a background colour (SUBBAR_BACK) to the thumbnail's
cell in the thumbnails page so that if the top and bottom borders are
wider than the image (for example, if it is in portrait mode), instead
of spilling over, there is a border around the whole picture. By
default, use the PAGE_BACK color.

thumbnailInImageList
Display thumbnails on the Image List page, set to 1 by default.

thumbnailPageCycling
If set to 0 next/prev-Links will be hidden if the actual page is the
last/first Thumbnail page.

thumbPrevNext
If set to 1 (the default), display thumbnails close to the previous
and next link at the bottom of the image page.

thumbsPerRow
Number of thumbnails (default of 4) displayed in each row in an album.

titleOnThumbnail
Should the title be displayed on top on the thumbnail in the
thumbnails page? (defaults to 1.)

treePreview
If set to 1, preview thumbnails will be showed in the album tree page.
This works only with joi, marc and petrus templates for now.

updateOriginalPerms
If set to 1, read permissions on images will be set, to ensure http
daemon will be able to read them.

userConfigDir
Can be set in the global config file (since after the user one is
read, it is too late). Defaults to ~/.bins and is processed by
bsd_glob (see File::Glob for details.)

xmlEncoding
XML files charset encoding.

image.jpg The EXIF tags are extracted from the image. Currently only the Orientation tag
influences the processing, but a variety of settings are copied into the HTML
file generated via the details.html template.

image.jpg.xml
The XML file contains an image element, which contains three child elements:

description
which has field children that contain per-image data. The name
attribute names the tag (allowing simple extensibility, see the
bins_edit --generic flag) but bins itself currently only
makes use of

title

description

people

location

date

event

bins which works as described with the binsrc file settings, except that
many of the settings are not meaningful in the context of a single
picture.

exif which has a cache of values copied from the EXIF tags in the image, to
allow simpler processing by other tools.

If a user wants to override the EXIF values and provide a replacement
(such as a corrected Orientation or an Owner setting that reflects who
you loaned the camera to) adding a priority attribute with a value of
"1" will prevent bins from replacing it with the value in the image.

album.xml This file contains an album element, which contains description and bins
stanza as described for an image. The are extensible in the same manner, but
bins only makes use of

dirname

descFileName

shortdesc

title

sampleimage

longdesc

include_images.txt
includes image filenames (relative to the current album, i.e. the directory
where the include_images.txt file is stored.) Each filename appears on a line
by itself; a line beginning with a # is a comment, and lines composed entirely
of whitespace are ignored. Otherwise, the line is exactly the filename. These
images are included in the order listed, and added after any that actually
appear in the directory.

template.html
There are a number of template HTMLfiles which are used to generate the actual
images. The base names of these are

tree

imagelist

subalbum

thumbnail

details

image

The default versions of these files in /usr/share/bins/templates.default should
show how they work, as does the HTML::Template documentation. Aside from the
COLOR substitutions described above, a template can also reference

BINS_VERSION

ENCODING

GENERATED_DATE

BINS_ID

AUTHOR