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
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.
