.TH "BINS" "1" 
.SH "NAME" 
bins \(em Generate a static HTML photo albums using XML and EXIF tags 
.SH "SYNOPSIS" 
.PP 
\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  
.SH "DESCRIPTION" 
.PP 
This manual page documents briefly the 
\fBbins\fR command. 
.PP 
This manual page was written for the \fBDebian\fP distribution 
because the original program does not have a manual page. 
Instead, it has documentation in HTML in 
\fB/usr/share/doc/bins/index.html\fP as well as a 
\fB-h\fP option. 
.PP 
\fBbins\fR 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. 
.SH "OPTIONS" 
.IP "\fB-f \fIconfig_file\fR\fP" 10 
use an alternative configuration file, instead of 
\fB~/.bins/binsrc.\fP. 
.IP "\fB-o \fISTR\fR\fP" 10 
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). 
.IP "" 10 
Default is false. 
.IP "" 10 
\fISTR\fR is an optional argument 
to set how the one image is generated. Possible values: 
 
.RS 
.IP "scaled" 10 
(make scaled copy of orig in target_dir 
hierarchy, sized to max size). Default. 
.IP "copied" 10 
(copy orig to web dir) 
.IP "custom" 10 
(use copy if filesize < 1meg 
resize, resave, if bigger than 1 meg) 
.RE 
 
.IP "\fB-d \fISTR\fR\fP" 10 
Determine if tags found in EXIF structure are 
added in desc files. 
.IP "" 10 
\fISTR\fR is one of "always", "never" or "exist" 
("exist" only adds if the desc file already exist.) 
Default is always. 
.IP "\fB-c \fIcolor_style\fR\fP" 10 
Color style to use. Can be \fBblue\fP 	    (default one), \fBgreen\fP, 
\fBivory\fP and \fBpink\fP 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 
\fBcustomStyleSheet\fP parameter. 
.IP "\fB-s \fIstyle\fR\fP" 10 
Template style to use (styles provided for now are 
\fBjoi\fP, \fBmarc\fP, 
\fBmartin\fP, \fBmwolson\fP 	  \fBpetrus\fP, \fBsatyap\fP and 
\fBswigs\fP). 
.IP "\fB-t \fItemplate_dir\fR\fP" 10 
Specify location of html templates. 
.IP "" 10 
Default is \fB~/.bins\fP, falling back 
to default versions in 
\fB/etc/bins/templates.\fIstyle\fR\fP. 
.IP "\fB-p\fP         " 10 
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 \fBmay\fP, 
\fBjune\fP, and \fBaugust\fP, they 
can be renamed \fB0_may\fP, 
\fB1_june\fP, and \fB2_august\fP and 
they will appear in the album in the correct 
order. 
.IP "\fB-e\fP" 10 
Tells the script to generate an editable version of 
the album.  If set, some more links and icons are added to 
directly access the \fB.xml\fP files for 
editing. This is for editing purposes, not for a final 
album. 
.IP "\fB-i \fIiKey,iKey...\fR\fP" 10 
Sets "ignore" keywords which will be compared against 
the contents of the \fBignore\fP field of the 
album's XML file, in the \fBignore\fP field in 
\fBdescription\fP section.  If any of the 
\fIiKeys\fR match those in the album's 
"ignore" field, that album will not be processed.  See also 
the \fBignore\fP parameter. 
.IP "\fB-n \fIiKey,iKey...\fR\fP" 10 
Sets "hidden" keywords which will be compared against 
the contents of the \fBignore\fP field of the 
album's XML file, in the \fBignore\fP field in 
\fBdescription\fP section.  If any of the 
\fIiKeys\fR match those in the album's 
"ignore" field, that album will be hidden: it will not be 
linked anywhere. See also the \fBhidden\fP 	  parameter. 
.IP "\fB-v \fIX\fR\fP         " 10 
\fIX\fR is the verbosity level (between 0 and 3) 
.IP "\fB-h\fP         " 10 
Show the help string this man page was originally based on. 
.SH "SETTINGS" 
.PP 
bins is also controlled by other files. 
.IP "\fB/etc/bins/binsrc\fP" 10 
.IP "\fB~/.bins/binsrc\fP" 10 
The \fBbinsrc\fP files are 
XML files with a top level 
\fBbins\fP tag.  There are three element 
names with \fBbins\fP: \fBparameter\fP, 
\fBcolors\fP, and \fBsizes\fP. 
Each of these has a \fBname\fP attribute 
which names the data in the element content. 
.IP "" 10 
The \fBcolors\fP element has a 
\fBstyle\fP attribute, that can be used with 
the \fBcolorStyle\fP parameter or the 
\fB-c\fP command line option. It contains 
\fBcolor\fP elements. The 
\fBcolor\fP 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 \fBcustomStyleSheet\fP 	  parameter. 
.RS 
.IP "" 10 
PAGE_BACK 
.IP "" 10 
PAGE_TITLE 
.IP "" 10 
MAINBAR_BACK 
.IP "" 10 
MAINBAR_TITLE 
.IP "" 10 
MAINBAR_LINK 
.IP "" 10 
MAINBAR_CURRENTPAGE 
.IP "" 10 
SUBBAR_BACK 
.IP "" 10 
SUBBAR_LINK 
.IP "" 10 
SUBBAR_CURRENTPAGE 
.IP "" 10 
SUBBAR_TITLE 
.RE 
.IP "" 10 
The \fBsizes\fP element contains 
\fBsize\fP elements which each have a 
\fBname\fP attribute, a 
\fBshortname\fP attribute, a 
\fBheight\fP attribute, and a 
\fBwidth\fP attribute.  These default to 
.RS 
.IP "" 10 
Small, Sm, 40%, 40% 
.IP "" 10 
Medium, Med, 64%, 64% 
.IP "" 10 
Large, Lg, 100%, 100% 
.RE 
.IP "" 10 
\fBname\fP and 
\fBshortname\fP are used in the output 
HTML and in generated filenames.  The 
default values listed above are passed through 
\fBgettext\fP for localization; overrides 
in \fBbinsrc\fP files are not, and should 
be in the desired language. 
.IP "" 10 
For the \fBparameter\fP elements the 
\fBname\fP attribute names one of the 
following parameters. 
.RS 
.IP "addExifToDescFile" 10 
If set to 1 (the default), write EXIF data found in 
the image file to the image desc file (but see also 
the \fB-d\fP flag). 
.IP "albumThumbInSubAlbumPage" 10 
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. 
.IP "allThumbnailsPage" 10 
If set to \fB1\fP, 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. 
.IP "backgroundImage" 10 
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. 
 
.IP "borderOnThumbnails" 10 
Width of the border of the thumbnail's image in 
the thumbnails page, in pixels. \fB0\fP 		means no border. 
 
.IP "colorStyle" 10 
Name of the color style to use. Default is 
\fBblue\fP. See also the 
\fB-c\fP option which takes precedence.  
This option is deprecated (and thus, not supported by 
all templates), in favor of alternate stylesheets and 
the \fBcustomStyleSheet\fP 		parameter. 
.IP "compactHTML" 10 
If set to \fB1\fP, 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 \fBHTML::Clean(3)\fR to 
know how optimizations are performed. 
.IP "configFileName" 10 
Can be set in the global config file, but only 
influences the basename of the local user config 
file.  Defaults to \fB.binsrc\fP. 
.IP "createEmptyDescFields" 10 
If set to 1 (the default), add empty description 
fields in the \fBdescription\fP section 
when the image description file is created to ease 
later manual editing. 
.IP "createHtaccess" 10 
If \fB1\fP, create an Apache 
\fB.htaccess\fP file in the root dir of 
the album with the encoding charset bound to 
\fBhtml\fP and \fBhtm\fP 		files. This is a parameter global for the album, it 
can't be set in album.xml. 
.IP "customStyleSheet" 10 
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. 
 
.IP "dateString" 10 
Specify the format of date strings.  This variable 
accepts all formats supported by \fBdate(1)\fR. 
 
.IP "defaultSize" 10 
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 
(\fBSmall\fP in the default config), 1 
the second (\fBMedium\fP), and so 
on. Set this variable to \-1 if you don't want the 
thumbnail to be clickable. 
.IP "deExifyImages" 10 
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. 
.IP "emptyAlbumDesc" 10 
If set to 1, and album desciption is not set, no 
message will be displayed (instead of the "No 
long/short description available" one). 
.IP "enlarge" 10 
If set to 1, small images are enlarged 
in the "med" and "large" series.  (defaults to 0). 
.IP "excludeBackgroundImage" 10 
If set to 1, the image with the name given in 
\fBbackgroundImage\fP will be excluded from the 
current directory. 
 
.IP "excludeDirs" 10 
Exclude directories that match this regexp (if 
set). Set to  
CVS$ in default config, so that CVS 
subdirs aren't processed by bins. 
 
.IP "excludeFiles" 10 
Exclude image files that match this regexp (if 
set). No image files are excluded in default config. 
 
.IP "globalConfigDir" 10 
Can't usefully be set, since it has already been 
used when the first config file is read.  Defaults 
to \fB/etc/bins\fP. 
.IP "hidden" 10 
Put here a comma separated list of keyword. If 
one on this keyword is found in the 
\fBignore\fP field in the 
\fBdescription\fP section of an 
\fBalbum.xml\fP, then this sub-album 
will be hidden, i.e. it will be generated but not 
linked anywhere. You can also use the 
\fB-n\fP command line option. 
.IP "homeURL" 10 
Set this to your home page's 
URL. This is used for the leave button 
in some templates. 
.IP "htmlEncoding" 10 
HTML pages charset encoding. 
.IP "ignore" 10 
Put here a comma separated list of keyword. If 
one on this keyword is found in the 
\fBignore\fP field in the 
\fBdescription\fP section of an 
\fBalbum.xml\fP, then this sub-album 
will be ignored, i.e. it will not be processed. You 
can also use the \fB-i\fP command line 
option. 
.IP "imagePageCycling" 10 
If set to 0 next/prev-Links will be hidden if 
the actual page is the last/first Image page. 
.IP "javaScriptPreloadImage" 10 
If set to \fB1\fP, 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. 
.IP "javaScriptPreloadThumbs" 10 
If set to \fB1\fP, 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. 
.IP "jpegQuality" 10 
Quality of scaled jpegs (lower number = more 
compression, lower quality) in 1-100 range (default 
of 75).  See imagemagick docs for more details. 
.IP "linkInsteadOfCopy" 10 
If set to 1, we link the picture instead of 
copying it if possible (i.e. scaleIfSameSize is set to 
\fB0\fP and destination image doesn't 
have to be rotated: \fBrotateImages\fP is 
set to \fBoriginal\fP or 
\fBnone\fP, or orientation is already 
correct). Warning : if whenSrcSmaller is set 
to enlarge, original image can be modified. 
.IP "linkRelative" 10 
If set to 1, we use a relative path for the link if 
\fBlinkInsteadOfCopy\fP is set to 1. 
 
.IP "maxAlbumsForLongSubAlbum" 10 
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.) 
.IP "noRotation" 10 
Don't perform rotation on files matching this 
regexp. This can used in conjunction with 
\fBscaleIfSameSize=0\fP and a scaled size of 
\fB100%x100%\fP to keep original pictures in 
your album. 
.IP "numThumbsPerPage" 10 
Number of thumbnails (default of 16) displayed 
in each page in an album. 
.IP "pathImgNum" 10 
If set to 1 the path in the imageview contains 
the number of the current image. 
.IP "pathShowIcon" 10 
If set to 1 the path contains icons. 
.IP "previewMaxWidth" 10 
.IP "previewMaxHeight" 10 
Max thumbnail width and height (default 150x150). 
.IP "jpegProgressify" 10 
whether to convert generated jpegs to 
progressive using jpegtran (if available).  can be 
\fBnever\fP, \fBalways\fP, or 
\fBsmaller\fP (if the progressified file 
is smaller than the baseline). 
.IP "reverseOrder" 10 
Are we reversing sorting order for pictures or 
directories ? 0=none, 1=dirs, 2=pix, 3=both. See 
also \fB-r\fP command line option. 
 
.IP "rotateImages" 10 
Do we rotate images if the 
\fBOrientation\fP EXIF 		tag is found? If set to \fBoriginal\fP 		(the default), the original image is rotated the first 
time, and then it is left untouched. If set to 
\fBdestination\fP, 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 \fBnone\fP, no rotation is 
performed. 
.IP "rotateWithJpegtran" 10 
If set to \fB1\fP, 
\fBbins\fP try to use the 
\fBjpegtran\fP program to rotate 
JPEG images if it is 
available. \fBjpegtran\fP is faster and 
lossless, but some versions fail to perform rotation 
correctly, so it is deactivated in default config. If 
set to \fB0\fP or if 
\fBjpegtran\fP is not found, 
\fBmogrify\fP (from ImageMagick) is 
used. 
.IP "scaleIfSameSize" 10 
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. 
.IP "scaleMethod" 10 
What method should be used to create scaled 
pictures and thumbnails ? Can be either 
\fBscale\fP or 
\fBsample\fP. \fBsample\fP 		is \fBfaster\fP, scale is better. 
 
.IP "searchEngine" 10 
If 1, generate a search page. Images can be searched 
on description fields set in the 
\fBsearchFields\fP parameter.  
 
.IP "searchFields" 10 
Space separated list of description field names used 
by the search engine, if 
\fBsearchEngine\fP is set to 1. 
 
.IP "searchLimit" 10 
Maximum results returned by the search engine, if 
\fBsearchEngine\fP is set to 1. Note 
that if this number is too high, it can hang the 
browser. 
 
.IP "stripDirPrefix" 10 
If \fB1\fP, 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 \fB0_may\fP, 
\fB1_june\fP, and 
\fB2_august\fP and they will appear in 
the album in the correct order. This can be overridden 
by the \fB-p\fP command line option. 
.IP "templateStyle" 10 
Name of the template style to use. Default is 
\fBswigs\fP. Other templates provided 
with BINS are \fBjoi\fP, 
\fBmarc\fP, \fBmartin\fP, 
\fBpetrus\fP and 
\fBsatyap\fP. Several templates can be 
used for different sub-album of an album, by using 
this parameter in the \fBbins\fP section 
of the \fBalbum.xml\fP files. See also 
the \fB-s\fP option which takes precedence 
over binsrc (but not album.xml). 
.IP "thumbnailBackground" 10 
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. 
.IP "thumbnailInImageList" 10 
Display thumbnails on the Image List page, set 
to 1 by default. 
.IP "thumbnailPageCycling" 10 
If set to 0 next/prev-Links will be hidden if 
the actual page is the last/first 
Thumbnail page. 
.IP "thumbPrevNext" 10 
If set to 1 (the default), display thumbnails close 
to the previous and next link at the 
bottom of the image page. 
.IP "thumbsPerRow" 10 
Number of thumbnails (default of 4) displayed in each 
row in an album. 
.IP "titleOnThumbnail" 10 
Should the title be displayed on top on the 
thumbnail in the thumbnails page? (defaults to 1.) 
.IP "treePreview" 10 
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. 
 
.IP "updateOriginalPerms" 10 
If set to 1, read permissions on images will be 
set, to ensure http deamon will be able to read 
them. 
 
.IP "userConfigDir" 10 
Can be set in the global config file (since 
after the user one is read, it is too late). 
Defaults to \fB~/.bins\fP and is 
processed by \fBbsd_glob\fP (see 
\fBFile::Glob\fP for details.) 
 
.IP "xmlEncoding" 10 
XML files charset encoding. 
.RE 
.IP "\fB\fIimage.jpg\fR\fP" 10 
The EXIF tags are extracted from 
the image.  Currently only the 
\fBOrientation\fP tag influences the 
processing, but a variety of settings are copied into the 
HTML file generated via the 
\fBdetails.html\fP template. 
.IP "\fB\fIimage.jpg\fR.xml\fP" 10 
The XML file contains an 
\fBimage\fP element, which contains three child 
elements: 
.RS 
.IP "\fBdescription\fP" 10 
which has \fBfield\fP children that 
contain per-image data.  The \fBname\fP 		  attribute names the tag (allowing simple 
extensibility, see the 
\fBbins_edit\fP 		  \fB\-\-generic\fP flag) but 
\fBbins\fP itself currently only 
makes use of 
.RS 
.IP "" 10 
title 
.IP "" 10 
description 
.IP "" 10 
people 
.IP "" 10 
location 
.IP "" 10 
date 
.IP "" 10 
event 
.RE 
.IP "\fBbins\fP" 10 
which works as described with the 
\fBbinsrc\fP file settings, except 
that many of the settings are not meaningful in the 
context of a single picture. 
.IP "\fBexif\fP" 10 
which has a cache of values copied from the 
EXIF tags in the image, to allow 
simpler processing by other tools. 
.IP "" 10 
If a user wants to override the 
EXIF values and provide a 
replacement (such as a corrected 
\fBOrientation\fP or an 
\fBOwner\fP setting that reflects who 
you loaned the camera to) adding a 
\fBpriority\fP attribute with a value 
of "1" will prevent \fBbins\fP from 
replacing it with the value in the image. 
.RE 
.IP "\fBalbum.xml\fP" 10 
This file contains an 
\fBalbum\fP element, which contains 
\fBdescription\fP and \fBbins\fP 	    stanza as described for an image.  The are extensible in 
the same manner, but \fBbins\fP only makes 
use of 
.RS 
.IP "" 10 
dirname 
.IP "" 10 
descFileName 
.IP "" 10 
shortdesc 
.IP "" 10 
title 
.IP "" 10 
sampleimage 
.IP "" 10 
longdesc 
.RE 
.IP "\fBinclude_images.txt\fP" 10 
includes image filenames (relative to the current 
album, i.e. the directory where the 
\fBinclude_images.txt\fP file is stored.) 
Each filename appears on a line by itself; a line 
beginning with a \fB#\fP 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. 
.IP "\fB\fItemplate\fR.html\fP" 10 
There are a number of template 
HTMLfiles which are used to generate 
the actual images.  The base names of these are 
.RS 
.IP "" 10 
tree 
.IP "" 10 
imagelist 
.IP "" 10 
subalbum 
.IP "" 10 
thumbnail 
.IP "" 10 
details 
.IP "" 10 
image 
.RE 
.IP "" 10 
The default versions of these files in 
\fB/etc/bins/templates.default\fP should 
show how they work, as does the 
\fBHTML::Template\fP documentation.  Aside 
from the \fBCOLOR\fP substitutions described 
above, a template can also reference 
.RS 
.IP "" 10 
BINS_VERSION 
.IP "" 10 
ENCODING 
.IP "" 10 
GENERATED_DATE 
.IP "" 10 
BINS_ID 
.RE 
.SH "SEE ALSO" 
.PP 
bins_edit (1), jpegtran (1), File::Glob, HTML::Template, imagemagick. 
.SH "AUTHOR" 
.PP 
This manual page was written by Mark W. Eichin eichin@thok.org for 
the \fBDebian\fP system (but may be used by others).  As it is 
mostly derived from the \fBbins\fP program 
itself, it is covered by the GNU General Public License. 
.\" created by instant / docbook-to-man, Wed 24 Aug 2005, 23:31