--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/bins.sgml	Wed Oct 15 23:28:56 2008 +0200
@@ -0,0 +1,1098 @@
+<!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:
+-->
+
+