bins

BINS(1)                     General Commands Manual                    BINS(1)



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.



                                                                       BINS(1)