<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- $Id: bins.sgml,v 1.35 2005/08/24 21:29:44 jerome Exp $ -->

<!-- This man page is Copyright 2002 Mark Eichin and released under -->
<!-- the GNU General Public License, Version 2. -->

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@

    
	The docbook-to-man binary is found in the docbook-to-man package.
	Please remember that if you create the nroff version in one of the
	debian/rules file targets (such as build), you will need to include
	docbook-to-man in your Build-Depends control field.

  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Mark</firstname>">
  <!ENTITY dhsurname   "<surname>Eichin</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>April 22, 2002</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>eichin@thok.org</email>">
  <!ENTITY dhusername  "Mark W. Eichin">
  <!ENTITY dhucpackage "<refentrytitle>BINS</refentrytitle>">
  <!ENTITY dhpackage   "bins">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; General Public License">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2002</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>Generate a static HTML photo albums using XML and EXIF tags</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>
      <arg><option>-f <replaceable>config_file</replaceable></option></arg>
      <arg><option>-o <replaceable>STR</replaceable></option></arg>
      <arg><option>-d <replaceable>STR</replaceable></option></arg>
      <arg><option>-c <replaceable>color_style</replaceable></option></arg>
      <arg><option>-s <replaceable>style</replaceable></option></arg>
      <arg><option>-t <replaceable>template_dir</replaceable></option></arg>
      <arg><option>-p</option></arg>
      <arg><option>-e</option></arg>
      <arg><option>-i <replaceable>iKey,iKey...</replaceable></option></arg>
      <arg><option>-v <replaceable>X</replaceable></option></arg>
      <arg><option>-h</option></arg>
      <arg choice="req"><replaceable>source_dir</replaceable></arg>
      <arg choice="req"><replaceable>target_dir</replaceable></arg>

    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>This manual page documents briefly the
      <command>&dhpackage;</command> command.</para>

    <para>This manual page was written for the &debian; distribution
      because the original program does not have a manual page.
      Instead, it has documentation in <acronym>HTML</acronym> in
      <filename>/usr/share/doc/bins/index.html</filename> as well as a
      <option>-h</option> option.</para>

    <para><command>&dhpackage;</command> is a program that takes a
      collection of directories and files containing
      <acronym>JPEG</acronym> images and <acronym>XML</acronym>
      descriptions, combines them with a set of
      <acronym>HTML</acronym> templates, and produces a complete photo
      gallery of static <acronym>HTML</acronym> files, rescaled images
      at three sizes, and thumbnails.</para>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
	<term><option>-f <replaceable>config_file</replaceable></option></term>
	<listitem>
	  <para>use an alternative configuration file, instead of
	  <filename>~/.bins/binsrc.</filename>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-o <replaceable>STR</replaceable></option></term>
        <listitem>
          <para>Tells script to use only one copy of image using
	    <acronym>HTML</acronym> size specs (height, width specs in the image
	    tag) for scaled versions (instead of generating
	    several images, one for each size).</para>
	  <para>Default is false.</para>
	  <para><replaceable>STR</replaceable> is an optional argument
	    to set how the one image is generated. Possible values:
	    <variablelist>
	      <varlistentry>
		<term>scaled</term>
		<listitem>
		  <para>(make scaled copy of orig in target_dir
                      hierarchy, sized to max size). Default.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>copied</term>
		<listitem>
		  <para>(copy orig to web dir)</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>custom</term>
		<listitem>
		  <para>(use copy if filesize < 1meg
                      resize, resave, if bigger than 1 meg)</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-d <replaceable>STR</replaceable></option></term>
	<listitem>
	  <para>Determine if tags found in <acronym>EXIF</acronym> structure are
	    added in desc files.</para>
	  <para><replaceable>STR</replaceable> is one of "always", "never" or "exist"
	    ("exist" only adds if the desc file already exist.)
	    Default is always.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-c <replaceable>color_style</replaceable></option></term>
	<listitem>
	  <para>
	    Color style to use. Can be <literal>blue</literal>
	    (default one), <literal>green</literal>,
	    <literal>ivory</literal> and <literal>pink</literal> 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
	    <literal>customStyleSheet</literal> parameter.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-s <replaceable>style</replaceable></option></term>
	<listitem>
	  <para>Template style to use (styles provided for now are
	  <literal>joi</literal>, <literal>marc</literal>,
	  <literal>martin</literal>, <literal>mwolson</literal>
	  <literal>petrus</literal>, <literal>satyap</literal> and
	  <literal>swigs</literal>).</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-t <replaceable>template_dir</replaceable></option></term>
	<listitem>
	  <para>Specify location of html templates.</para>
	  <para>Default is <filename>~/.bins</filename>, falling back
	    to default versions in
	    <filename>/etc/bins/templates.<replaceable>style</replaceable></filename>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-p</option>
        </term>
        <listitem>
	  <para>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 <filename>may</filename>,
	    <filename>june</filename>, and <filename>august</filename>, they
	    can be renamed <filename>0_may</filename>,
	    <filename>1_june</filename>, and <filename>2_august</filename> and
	    they will appear in the album in the correct
	    order.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-e</option></term>
	<listitem>
	  <para>Tells the script to generate an editable version of
	    the album.  If set, some more links and icons are added to
	    directly access the <filename>.xml</filename> files for
	    editing. This is for editing purposes, not for a final
	    album.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-i <replaceable>iKey,iKey...</replaceable></option></term>
	<listitem>
	  <para>Sets "ignore" keywords which will be compared against
	  the contents of the <sgmltag>ignore</sgmltag> field of the
	  album's XML file, in the <sgmltag>ignore</sgmltag> field in
	  <sgmltag>description</sgmltag> section.  If any of the
	  <replaceable>iKeys</replaceable> match those in the album's
	  "ignore" field, that album will not be processed.  See also
	  the <sgmltag>ignore</sgmltag> parameter.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-n <replaceable>iKey,iKey...</replaceable></option></term>
	<listitem>
	  <para>Sets "hidden" keywords which will be compared against
	  the contents of the <sgmltag>ignore</sgmltag> field of the
	  album's XML file, in the <sgmltag>ignore</sgmltag> field in
	  <sgmltag>description</sgmltag> section.  If any of the
	  <replaceable>iKeys</replaceable> match those in the album's
	  "ignore" field, that album will be hidden: it will not be
	  linked anywhere. See also the <sgmltag>hidden</sgmltag>
	  parameter.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v <replaceable>X</replaceable></option>
        </term>
        <listitem>
	  <para><replaceable>X</replaceable> is the verbosity level (between 0 and 3)</para>
	</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-h</option>
        </term>
        <listitem>
          <para>Show the help string this man page was originally based on.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>SETTINGS</title>
    <para>&dhpackage; is also controlled by other files.</para>
    <variablelist>
      <varlistentry>
	<term><filename>/etc/bins/binsrc</filename></term>
	<term><filename>~/.bins/binsrc</filename></term>
	<listitem>

	  <para>The <filename>binsrc</filename> files are
	    <acronym>XML</acronym> files with a top level
	    <sgmltag>bins</sgmltag> tag.  There are three element
	    names with <sgmltag>bins</sgmltag>: <sgmltag>parameter</sgmltag>,
	    <sgmltag>colors</sgmltag>, and <sgmltag>sizes</sgmltag>.
	    Each of these has a <sgmltag>name</sgmltag> attribute
	    which names the data in the element content.</para>

	  <para>The <sgmltag>colors</sgmltag> element has a
	  <sgmltag>style</sgmltag> attribute, that can be used with
	  the <sgmltag>colorStyle</sgmltag> parameter or the
	  <sgmltag>-c</sgmltag> command line option. It contains
	  <sgmltag>color</sgmltag> elements. The
	  <sgmltag>color</sgmltag> 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 <literal>customStyleSheet</literal>
	  parameter.</para>

	  <simplelist>
	    <member>PAGE_BACK</member>
	    <member>PAGE_TITLE</member>
	    <member>MAINBAR_BACK</member>
	    <member>MAINBAR_TITLE</member>
	    <member>MAINBAR_LINK</member>
	    <member>MAINBAR_CURRENTPAGE</member>
	    <member>SUBBAR_BACK</member>
	    <member>SUBBAR_LINK</member>
	    <member>SUBBAR_CURRENTPAGE</member>
	    <member>SUBBAR_TITLE</member>
	  </simplelist>
	  <para>The <sgmltag>sizes</sgmltag> element contains
	    <sgmltag>size</sgmltag> elements which each have a
	    <sgmltag>name</sgmltag> attribute, a
	    <sgmltag>shortname</sgmltag> attribute, a
	    <sgmltag>height</sgmltag> attribute, and a
	    <sgmltag>width</sgmltag> attribute.  These default to</para>
	    <simplelist>
	      <member>Small, Sm, 40%, 40%</member>
	      <member>Medium, Med, 64%, 64%</member>
	      <member>Large, Lg, 100%, 100%</member>
	    </simplelist>
	  <para><sgmltag>name</sgmltag> and
	    <sgmltag>shortname</sgmltag> are used in the output
	    <acronym>HTML</acronym> and in generated filenames.  The
	    default values listed above are passed through
	    <function>gettext</function> for localization; overrides
	    in <filename>binsrc</filename> files are not, and should
	    be in the desired language.</para>
	  <para>For the <sgmltag>parameter</sgmltag> elements the
	    <sgmltag>name</sgmltag> attribute names one of the
	    following parameters.</para>
	  <!-- parameters are sorted alphabetically -->
	  <variablelist>

	    <varlistentry>
	      <term>addExifToDescFile</term>
	      <listitem>
		<para>If set to 1 (the default), write <acronym>EXIF</acronym> data found in
		  the image file to the image desc file (but see also
		  the <option>-d</option> flag).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>albumThumbInSubAlbumPage</term>
	      <listitem>
		<para>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.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>allThumbnailsPage</term>
	      <listitem>
		<para>If set to <literal>1</literal>, 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.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>backgroundImage</term>
	      <listitem>
		<para>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.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>borderOnThumbnails</term>
	      <listitem>
		<para>Width of the border of the thumbnail's image in
		the thumbnails page, in pixels. <literal>0</literal>
		means no border.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>colorStyle</term>
	      <listitem>
		<para>Name of the color style to use. Default is
		<filename>blue</filename>. See also the
		<option>-c</option> option which takes precedence. 
		This option is deprecated (and thus, not supported by
		all templates), in favor of alternate stylesheets and
		the <literal>customStyleSheet</literal>
		parameter.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>compactHTML</term>
	      <listitem>
		<para>If set to <literal>1</literal>, generated
		<acronym>HTML</acronym> code is cleaned up to reduce
		the size of pages and thus, speed up browsing. This
		reduces the size of <acronym>HTML</acronym> BINS files
		by about 30%. See <command>HTML::Clean(3)</command> to
		know how optimizations are performed.</para>
	      </listitem>
	    </varlistentry>


	    <varlistentry>
	      <term>configFileName</term>
	      <listitem>
		<para>Can be set in the global config file, but only
		  influences the basename of the local user config
		  file.  Defaults to <filename>.binsrc</filename>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>createEmptyDescFields</term>
	      <listitem>
		<para>If set to 1 (the default), add empty description
		fields in the <sgmltag>description</sgmltag> section
		when the image description file is created to ease
		later manual editing.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>createHtaccess</term>
	      <listitem>
		<para>If <literal>1</literal>, create an Apache
		<filename>.htaccess</filename> file in the root dir of
		the album with the encoding charset bound to
		<filename>html</filename> and <filename>htm</filename>
		files. This is a parameter global for the album, it
		can't be set in album.xml.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>customStyleSheet</term>
	      <listitem>
		<para>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.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>dateString</term>
	      <listitem>
		<para>Specify the format of date strings.  This variable
		accepts all formats supported by <command>date(1)</command>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>defaultSize</term>
	      <listitem>
		<para>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
		  (<literal>Small</literal> in the default config), 1
		  the second (<literal>Medium</literal>), and so
		  on. Set this variable to -1 if you don't want the
		  thumbnail to be clickable.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>deExifyImages</term>
	      <listitem>
	        <para>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.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>emptyAlbumDesc</term>
	      <listitem>
		<para>If set to 1, and album desciption is not set, no
		message will be displayed (instead of the "No
		long/short description available" one).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>enlarge</term>
	      <listitem>
		<para>If set to 1, small images are enlarged
		  in the "med" and "large" series.  (defaults to 0).</para>
	      </listitem>
	    </varlistentry>

	     <varlistentry>
	      <term>excludeBackgroundImage</term>
	      <listitem>
		<para>If set to 1, the image with the name given in
		<literal>backgroundImage</literal> will be excluded from the
		current directory.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>excludeDirs</term>
	      <listitem>
		<para>Exclude directories that match this regexp (if
		set). Set to ^CVS$ in default config, so that CVS
		subdirs aren't processed by bins.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>excludeFiles</term>
	      <listitem>
		<para>Exclude image files that match this regexp (if
		set). No image files are excluded in default config.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>globalConfigDir</term>
	      <listitem>
		<para>Can't usefully be set, since it has already been
		  used when the first config file is read.  Defaults
		  to <filename>/etc/bins</filename>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>hidden</term>
	      <listitem>
		<para>Put here a comma separated list of keyword. If
		one on this keyword is found in the
		<literal>ignore</literal> field in the
		<sgmltag>description</sgmltag> section of an
		<filename>album.xml</filename>, then this sub-album
		will be hidden, i.e. it will be generated but not
		linked anywhere. You can also use the
		<literal>-n</literal> command line option.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>homeURL</term>
	      <listitem>
	     <para>Set this to your home page's
	     <acronym>URL</acronym>. This is used for the leave button
	     in some templates.</para>
	     </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>htmlEncoding</term>
	      <listitem>
		<para><acronym>HTML</acronym> pages charset encoding.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>ignore</term>
	      <listitem>
		<para>Put here a comma separated list of keyword. If
		one on this keyword is found in the
		<literal>ignore</literal> field in the
		<sgmltag>description</sgmltag> section of an
		<filename>album.xml</filename>, then this sub-album
		will be ignored, i.e. it will not be processed. You
		can also use the <literal>-i</literal> command line
		option.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>imagePageCycling</term>
	      <listitem>
		<para>If set to 0 next/prev-Links will be hidden if
		the actual page is the last/first Image page.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>javaScriptPreloadImage</term>
	      <listitem>
		<para>If set to <literal>1</literal>, 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.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>javaScriptPreloadThumbs</term>
	      <listitem>
		<para>If set to <literal>1</literal>, 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.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>jpegQuality</term>
	      <listitem>
		<para>Quality of scaled jpegs (lower number = more
		  compression, lower quality) in 1-100 range (default
		  of 75).  See imagemagick docs for more details.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>linkInsteadOfCopy</term>
	      <listitem>
		<para>If set to 1, we link the picture instead of
		copying it if possible (i.e. scaleIfSameSize is set to
		<literal>0</literal> and destination image doesn't
		have to be rotated: <literal>rotateImages</literal> is
		set to <literal>original</literal> or
		<literal>none</literal>, or orientation is already
		correct). Warning : if whenSrcSmaller is set
		to enlarge, original image can be modified.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>linkRelative</term>
	      <listitem>
		<para>
		  If set to 1, we use a relative path for the link if
		  <literal>linkInsteadOfCopy</literal> is set to 1.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>maxAlbumsForLongSubAlbum</term>
	      <listitem>
		<para>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.)</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>noRotation</term>
	      <listitem>
		<para>Don't perform rotation on files matching this
		regexp. This can used in conjunction with
		<literal>scaleIfSameSize=0</literal> and a scaled size of
		<literal>100%x100%</literal> to keep original pictures in
		your album.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>numThumbsPerPage</term>
	      <listitem>
		<para>Number of thumbnails (default of 16) displayed
		   in each page in an album.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>pathImgNum</term>
	      <listitem>
		<para>If set to 1 the path in the imageview contains
		the number of the current image.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>pathShowIcon</term>
	      <listitem>
		<para>If set to 1 the path contains icons.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>previewMaxWidth</term>
	      <term>previewMaxHeight</term>
	      <listitem>
		<para>Max thumbnail width and height (default 150x150).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>jpegProgressify</term>
	      <listitem>
		<para>whether to convert generated jpegs to
		progressive using jpegtran (if available).  can be
		<literal>never</literal>, <literal>always</literal>, or
		<literal>smaller</literal> (if the progressified file
		is smaller than the baseline).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>reverseOrder</term>
	      <listitem>
		<para>
		  Are we reversing sorting order for pictures or
		  directories ? 0=none, 1=dirs, 2=pix, 3=both. See
		  also <literal>-r</literal> command line option.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>rotateImages</term>
	      <listitem>
		<para>Do we rotate images if the
		<sgmltag>Orientation</sgmltag> <acronym>EXIF</acronym>
		tag is found? If set to <sgmltag>original</sgmltag>
		(the default), the original image is rotated the first
		time, and then it is left untouched. If set to
		<sgmltag>destination</sgmltag>, 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 <sgmltag>none</sgmltag>, no rotation is
		performed.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>rotateWithJpegtran</term>
	      <listitem>
		<para>If set to <literal>1</literal>,
		<filename>bins</filename> try to use the
		<filename>jpegtran</filename> program to rotate
		<acronym>JPEG</acronym> images if it is
		available. <filename>jpegtran</filename> is faster and
		lossless, but some versions fail to perform rotation
		correctly, so it is deactivated in default config. If
		set to <literal>0</literal> or if
		<filename>jpegtran</filename> is not found,
		<filename>mogrify</filename> (from ImageMagick) is
		used.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>scaleIfSameSize</term>
	      <listitem>
		<para>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.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>scaleMethod</term>
	      <listitem>
		<para>What method should be used to create scaled
		pictures and thumbnails ? Can be either
		<literal>scale</literal> or
		<literal>sample</literal>. <literal>sample</literal>
		is <literal>faster</literal>, scale is better.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>searchEngine</term>
	      <listitem>
		<para>
		  If 1, generate a search page. Images can be searched
		  on description fields set in the
		  <literal>searchFields</literal> parameter. 
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>searchFields</term>
	      <listitem>
		<para>
		  Space separated list of description field names used
		  by the search engine, if
		  <literal>searchEngine</literal> is set to 1.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>searchLimit</term>
	      <listitem>
		<para>
		  Maximum results returned by the search engine, if
		  <literal>searchEngine</literal> is set to 1. Note
		  that if this number is too high, it can hang the
		  browser.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>stripDirPrefix</term>
	      <listitem>
		<para>If <literal>1</literal>, 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 <filename>0_may</filename>,
		<filename>1_june</filename>, and
		<filename>2_august</filename> and they will appear in
		the album in the correct order. This can be overridden
		by the <literal>-p</literal> command line option.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>templateStyle</term>
	      <listitem>
		<para>Name of the template style to use. Default is
		<filename>swigs</filename>. Other templates provided
		with BINS are <filename>joi</filename>,
		<filename>marc</filename>, <filename>martin</filename>,
		<filename>petrus</filename> and
		<filename>satyap</filename>. Several templates can be
		used for different sub-album of an album, by using
		this parameter in the <sgmltag>bins</sgmltag> section
		of the <filename>album.xml</filename> files. See also
		the <option>-s</option> option which takes precedence
		over binsrc (but not album.xml).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>thumbnailBackground</term>
	      <listitem>
		<para>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.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>thumbnailInImageList</term>
	      <listitem>
		<para>Display thumbnails on the Image List page, set
		  to 1 by default.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>thumbnailPageCycling</term>
	      <listitem>
		<para>If set to 0 next/prev-Links will be hidden if
		the actual page is the last/first
		Thumbnail page.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>thumbPrevNext</term>
	      <listitem>
		<para>If set to 1 (the default), display thumbnails close
		  to the previous and next link at the
		  bottom of the image page.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>thumbsPerRow</term>
	      <listitem>
		<para>Number of thumbnails (default of 4) displayed in each
		  row in an album.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>titleOnThumbnail</term>
	      <listitem>
		<para>Should the title be displayed on top on the
		  thumbnail in the thumbnails page? (defaults to 1.)</para>
	      </listitem>
	    </varlistentry>

	     <varlistentry>
	      <term>treePreview</term>
	      <listitem>
		<para>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.
		</para>
	      </listitem>
	    </varlistentry>

	     <varlistentry>
	      <term>updateOriginalPerms</term>
	      <listitem>
		<para>If set to 1, read permissions on images will be
		set, to ensure http deamon will be able to read
		them.
		</para>
	      </listitem>
	    </varlistentry>
	    
	    <varlistentry>
	      <term>userConfigDir</term>
	      <listitem>
		<para>Can be set in the global config file (since
		  after the user one is read, it is too late).
		  Defaults to <filename>~/.bins</filename> and is
		  processed by <function>bsd_glob</function> (see
		  <function>File::Glob</function> for details.)
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>xmlEncoding</term>
	      <listitem>
		<para><acronym>XML</acronym> files charset encoding.</para>
	      </listitem>
	    </varlistentry>

	  </variablelist>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename><replaceable>image.jpg</replaceable></filename></term>
	<listitem>
	  <para>The <acronym>EXIF</acronym> tags are extracted from
	    the image.  Currently only the
	    <sgmltag>Orientation</sgmltag> tag influences the
	    processing, but a variety of settings are copied into the
	    <acronym>HTML</acronym> file generated via the
	    <filename>details.html</filename> template.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename><replaceable>image.jpg</replaceable>.xml</filename></term>
	<listitem>
	  <para>The <acronym>XML</acronym> file contains an
	    <sgmltag>image</sgmltag> element, which contains three child
	    elements:</para>
	  <variablelist>
	    <varlistentry>
	      <term><sgmltag>description</sgmltag></term>
	      <listitem>
		<para>which has <sgmltag>field</sgmltag> children that
		  contain per-image data.  The <sgmltag>name</sgmltag>
		  attribute names the tag (allowing simple
		  extensibility, see the
		  <filename>bins_edit</filename>
		  <option>--generic</option> flag) but
		  <filename>bins</filename> itself currently only
		  makes use of</para>
		<simplelist>
		  <member>title</member>
		  <member>description</member>
		  <member>people</member>
		  <member>location</member>
		  <member>date</member>
		  <member>event</member>
		</simplelist>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><sgmltag>bins</sgmltag></term>
	      <listitem>
		<para>which works as described with the
		  <filename>binsrc</filename> file settings, except
		  that many of the settings are not meaningful in the
		  context of a single picture.<!-- are any? --></para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><sgmltag>exif</sgmltag></term>
	      <listitem>
		<para>which has a cache of values copied from the
		  <acronym>EXIF</acronym> tags in the image, to allow
		  simpler processing by other tools.</para>
		<para>If a user wants to override the
		  <acronym>EXIF</acronym> values and provide a
		  replacement (such as a corrected
		  <sgmltag>Orientation</sgmltag> or an
		  <sgmltag>Owner</sgmltag> setting that reflects who
		  you loaned the camera to) adding a
		  <sgmltag>priority</sgmltag> attribute with a value
		  of "1" will prevent <filename>bins</filename> from
		  replacing it with the value in the image.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>album.xml</filename></term>
	<listitem>
	  <para>This file contains an
	    <sgmltag>album</sgmltag> element, which contains
	    <sgmltag>description</sgmltag> and <sgmltag>bins</sgmltag>
	    stanza as described for an image.  The are extensible in
	    the same manner, but <filename>bins</filename> only makes
	    use of</para>
	  <simplelist>
	    <member>dirname</member>
	    <member>descFileName</member>
	    <member>shortdesc</member>
	    <member>title</member>
	    <member>sampleimage</member>
	    <member>longdesc</member>
	  </simplelist>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>include_images.txt</filename></term>
	<listitem>
	  <para>includes image filenames (relative to the current
	    album, i.e. the directory where the
	    <filename>include_images.txt</filename> file is stored.)
	    Each filename appears on a line by itself; a line
	    beginning with a <literal>#</literal> 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.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename><replaceable>template</replaceable>.html</filename></term>
	<listitem>
	  <para>There are a number of template
	    <acronym>HTML</acronym>files which are used to generate
	    the actual images.  The base names of these are</para>
	  <simplelist>
	    <member>tree</member>
	    <member>imagelist</member>
	    <member>subalbum</member>
	    <member>thumbnail</member>
	    <member>details</member>
	    <member>image</member>
	  </simplelist>
	  <para>The default versions of these files in
	    <filename>/etc/bins/templates.default</filename> should
	    show how they work, as does the
	    <filename>HTML::Template</filename> documentation.  Aside
	    from the <literal>COLOR</literal> substitutions described
	    above, a template can also reference</para>
	  <simplelist>
	    <member>BINS_VERSION</member>
	    <member>ENCODING</member>
	    <member>GENERATED_DATE</member>
	    <member>BINS_ID</member>
	  </simplelist>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>

    <para>bins_edit (1), jpegtran (1), File::Glob, HTML::Template, imagemagick.</para>

  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

    <para>This manual page was written by &dhusername; &dhemail; for
      the &debian; system (but may be used by others).  As it is
      mostly derived from the <filename>&dhpackage;</filename> program
      itself, it is covered by the &gpl;.</para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->