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
/etc/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
SEE ALSO
bins_edit (1), jpegtran (1), File::Glob, HTML::Template, imagemagick.
AUTHOR
This manual page was written by Mark W. Eichin eichin@thok.org for the
Debian system (but may be used by others). As it is mostly derived
from the bins program itself, it is covered by the GNU General Public
License.