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}
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.
-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:
(make scaled copy of orig in target_dir hierarchy, sized to max size). Default.
(copy orig to web dir)
(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 /etc/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.
bins is also controlled by other files.
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.
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).
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.
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.
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.
Width of the border of the thumbnail's image in the thumbnails page, in pixels. 0 means no border.
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.
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.
Can be set in the global config file, but only influences the basename of the local user config file. Defaults to .binsrc.
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.
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.
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.
Specify the format of date strings. This variable accepts all formats supported by date(1).
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.
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.
If set to 1, and album desciption is not set, no message will be displayed (instead of the "No long/short description available" one).
If set to 1, small images are enlarged in the "med" and "large" series. (defaults to 0).
If set to 1, the image with the name given in backgroundImage will be excluded from the current directory.
Exclude directories that match this regexp (if set). Set to ^CVS$ in default config, so that CVS subdirs aren't processed by bins.
Exclude image files that match this regexp (if set). No image files are excluded in default config.
Can't usefully be set, since it has already been used when the first config file is read. Defaults to /etc/bins.
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.
Set this to your home page's URL. This is used for the leave button in some templates.
HTML pages charset encoding.
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.
If set to 0 next/prev-Links will be hidden if the actual page is the last/first Image page.
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.
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.
Quality of scaled jpegs (lower number = more compression, lower quality) in 1-100 range (default of 75). See imagemagick docs for more details.
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.
If set to 1, we use a relative path for the link if linkInsteadOfCopy is set to 1.
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.)
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.
Number of thumbnails (default of 16) displayed in each page in an album.
If set to 1 the path in the imageview contains the number of the current image.
If set to 1 the path contains icons.
Max thumbnail width and height (default 150x150).
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).
Are we reversing sorting order for pictures or directories ? 0=none, 1=dirs, 2=pix, 3=both. See also -r command line option.
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.
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.
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.
What method should be used to create scaled pictures and thumbnails ? Can be either scale or sample. sample is faster, scale is better.
If 1, generate a search page. Images can be searched on description fields set in the searchFields parameter.
Space separated list of description field names used by the search engine, if searchEngine is set to 1.
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.
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.
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).
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.
Display thumbnails on the Image List page, set to 1 by default.
If set to 0 next/prev-Links will be hidden if the actual page is the last/first Thumbnail page.
If set to 1 (the default), display thumbnails close to the previous and next link at the bottom of the image page.
Number of thumbnails (default of 4) displayed in each row in an album.
Should the title be displayed on top on the thumbnail in the thumbnails page? (defaults to 1.)
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.
If set to 1, read permissions on images will be set, to ensure http deamon will be able to read them.
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.)
XML files charset encoding.
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.
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.
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 |
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.
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 |
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.