# BINS

## 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 `/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.

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