Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 documen-
       tation  in  HTML	 in /usr/share/doc/bins/index.html as well as a	-h op-
       tion.

       bins is a program that takes a collection of directories	and files con-
       taining	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 ver-
		 sions (instead	of generating several  images,	one  for  each
		 size).

		 Default is false.

		 STR  is an optional argument to set how the one image is gen-
		 erated. 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/de-
		 scription 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 al-
		 bum.  If set, some more links and icons are added to directly
		 access	 the  .xml files for editing. This is for editing pur-
		 poses,	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 tem-
		 plate 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	gener-
		 ated 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 al-
			   bum thumbnail in sub-albums page  if	 it  has  pic-
			   tures, 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  be-
			   cause  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 bor-
			   der.

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

		 compactHTML
			   If  set  to 1, generated HTML code is cleaned up to
			   reduce the size of pages and	thus, speed up	brows-
			   ing.	 This  reduces	the size of HTML BINS files by
			   about 30%. See HTML::Clean(3) to know how optimiza-
			   tions are performed.

		 configFileName
			   Can	be set in the global config file, but only in-
			   fluences 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	thumb-
			   nail	 in  the thumbnails page instead of one	of the
			   size	name. 0	is the first size (Small  in  the  de-
			   fault  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  im-
			   ages.   Setting  this  option can yield significant
			   space savings, especially for thumbnail and	image-
			   list	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 back-
			   groundImage	will  be excluded from the current di-
			   rectory.

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

		 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  com-
			   mand	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 pro-
			   cessed. You can also	use the	-i  command  line  op-
			   tion.

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

		 jpegQuality
			   Quality of scaled jpegs (lower number =  more  com-
			   pression, 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	orien-
			   tation is already correct). Warning : if  whenSrcS-
			   maller  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 al-
			   bum pages appear to be unsupported at  the  moment;
			   this	option is disabled.)

		 noRotation
			   Don't  perform rotation on files matching this reg-
			   exp.	This can used in conjunction with scaleIfSame-
			   Size=0 and a	scaled size of 100%x100% to keep orig-
			   inal	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, al-
			   ways, or smaller  (if  the  progressified  file  is
			   smaller than	the baseline).

		 reverseOrder
			   Are	we reversing sorting order for pictures	or di-
			   rectories ? 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 ro-
			   tated the first time,  and  then  it	 is  left  un-
			   touched.  If	 set  to  destination, this is all the
			   scaled images and thumbnails	that are rotated. This
			   is less efficient, but the original images are pre-
			   served (and is useful if the	 original  images  are
			   read-only).	If  set	 to  none, no rotation is per-
			   formed.

		 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 destina-
			   tion	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  pic-
			   tures  and thumbnails ? Can be either scale or sam-
			   ple.	sample	       is faster, scale	is better.

		 searchEngine
			   If  1,  generate  a	search	page.  Images  can  be
			   searched  on	 description fields set	in the search-
			   Fields 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 al-
			   bum.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	thumb-
			   nail	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 cur-
			   rently only makes use of

				     title

				     description

				     people

				     location

				     date

				     event

		 bins	   which works as described with the binsrc file  set-
			   tings,  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 Orienta-
			   tion	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  replac-
			   ing it with the value in the	image.

       album.xml This  file contains an	album element, which contains descrip-
		 tion 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	white-
		 space	are ignored.  Otherwise, the line is exactly the file-
		 name.	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/tem-
		 plates.default	 should	 show  how  they  work,	 as  does  the
		 HTML::Template	documentation.	Aside from the COLOR substitu-
		 tions 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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SETTINGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bins&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help