--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/bins_edit.sgml	Wed Oct 15 23:28:56 2008 +0200
@@ -0,0 +1,286 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+
+<!-- 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_edit">
+
+  <!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>Set fields in XML picture description files for BINS</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>&dhpackage;</command>
+      <group><arg><option>-a</option></arg><arg><option>--album</option></arg></group>
+      <group><arg><option>-m</option></arg><arg><option>--html</option></arg></group>
+      <group><arg><option>-t <replaceable>title</replaceable></option></arg><arg><option>--title <replaceable>title</replaceable></option></arg></group>
+      <group><arg><option>-e <replaceable>event</replaceable></option></arg><arg><option>--event <replaceable>event</replaceable></option></arg></group>
+      <group><arg><option>-l <replaceable>location</replaceable></option></arg><arg><option>--location <replaceable>location</replaceable></option></arg></group>
+      <group><arg><option>-p <replaceable>people</replaceable></option></arg><arg><option>--people <replaceable>people</replaceable></option></arg></group>
+      <group><arg><option>-y <replaceable>date</replaceable></option></arg><arg><option>--date <replaceable>date</replaceable></option></arg></group>
+      <group><arg><option>-d <replaceable>description</replaceable></option></arg><arg><option>--description <replaceable>description</replaceable></option></arg></group>
+      <arg><option>--longdesc <replaceable>longDescription</replaceable></option></arg>
+      <arg><option>--shortdesc <replaceable>shortDescription</replaceable></option></arg>
+      <arg><option>--sample <replaceable>pictureFileName</replaceable></option></arg>
+      <group>
+	<arg><option>-g  <replaceable>tag</replaceable>=<replaceable>value</replaceable></option></arg>
+	<arg><option>--generic <replaceable>tag</replaceable>=<replaceable>value</replaceable></option></arg>
+      </group>
+      <group><arg><option>-h</option></arg><arg><option>--help</option></arg></group>
+      <group><arg><option>-v</option></arg><arg><option>--verbose</option></arg></group>
+      <group><arg><option>-q</option></arg><arg><option>--quiet</option></arg></group>
+
+      <arg><replaceable>file</replaceable></arg>
+      <arg rep="repeat"><replaceable>files</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>--help</option> option.</para>
+
+    <para><command>&dhpackage;</command> sets values in the XML
+      picture description files that <command>bins</command>(1) uses
+      to generate galleries.
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>OPTIONS</title>
+
+    <para>This program follows the usual GNU command line syntax,
+      with long options starting with two dashes (`-').  A summary of
+      options is included below.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term><replaceable>file</replaceable></term>
+	<listitem>
+	  <para>By default, <replaceable>file</replaceable> is the
+	    filename of the <acronym>XML</acronym> file with the image
+	    properties.  If the argument has no
+	    <filename>.xml</filename> suffix, it is added, so you can directly give
+	    picture names on the command line.  Spaces and other
+	    special characters (even newlines) can be used in values
+	    given as parameters as long as they are enclosed between
+	    quotes.</para>
+	  <para>If the <option>--album</option> option is given, the
+	    filename refers to the directory of images, and the
+	    <filename>album.xml</filename> in that directory will be
+	    modified instead.</para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-a</option></term>
+	<term><option>--album</option></term>  <!-- needs a cleaner alternate/synonym specifier -->
+        <listitem>
+	  <para>edit album description (instead of the default of
+                   editing the image description.)
+                   In this case, the file parameter must be the
+                   source directory of the album.
+                   Only the <option>--title</option>, <option>--longdesc</option>, <option>--shortdesc</option> and <option>--sample</option>
+                   switches make sense with this option.</para>
+	</listitem>
+      </varlistentry>
+      <varlistentry><term><option>-m</option></term><term><option>--html</option></term>        <listitem>
+	  <para>input value will be interpreted as <acronym>HTML</acronym> code, thus,
+                   no HTML encoding or quoting will be done.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-t <replaceable>title</replaceable></option></term><term><option>--title <replaceable>title</replaceable></option></term>        <listitem>
+	  <para>Set the title (of an image.)</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-e <replaceable>event</replaceable></option></term><term><option>--event <replaceable>event</replaceable></option></term>        <listitem>
+	  <para>Set the event name (of an album or image.)</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-l <replaceable>location</replaceable></option></term><term><option>--location <replaceable>location</replaceable></option></term>        <listitem>
+	  <para>Set the location (of an image.)</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-p <replaceable>people</replaceable></option></term><term><option>--people <replaceable>people</replaceable></option></term>        <listitem>
+	  <para>Set the list of people (of an image.)</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-y <replaceable>date</replaceable></option></term><term><option>--date <replaceable>date</replaceable></option></term>        <listitem>
+	  <para>Set the date (of an image.)</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-d <replaceable>description</replaceable></option></term><term><option>--description <replaceable>description</replaceable></option></term>        <listitem>
+	  <para>Set the description (of an image.)</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>--longdesc <replaceable>longDescription</replaceable></option></term>        <listitem>
+	  <para>Set the long description (of an album.)</para>
+	</listitem>
+      </varlistentry>
+      
+      <varlistentry><term><option>--shortdesc <replaceable>shortDescription</replaceable></option></term>        <listitem>
+	  <para>Set the short description (of an album.)</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>--sample <replaceable>pictureFileName</replaceable></option></term>        <listitem>
+	  <para>Select the sample picture, within this album, to be
+	    used on the album list (template
+	    <filename>subalbum.html</filename>.) Note that the
+	    filename is relative to the album directory, and thus
+	    doesn't have a directory component.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><option>-g  <replaceable>tag</replaceable>=<replaceable>value</replaceable></option></term>
+	<term><option>--generic <replaceable>tag</replaceable>=<replaceable>value</replaceable></option></term>
+              <listitem>
+	  <para>This lets you set arbitrary fields in the relevant
+	    <acronym>XML</acronym> file (of the image or the album.)
+	    Generic tags appear inside <sgmltag>description</sgmltag>
+	    which appears inside <sgmltag>image</sgmltag>; the
+	    <replaceable>tag</replaceable> appears as the
+	    <sgmltag>name</sgmltag> attribute of a
+	    <sgmltag>field</sgmltag> element, and the
+	    <replaceable>value</replaceable> appears as the content of
+	    the element.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-h</option></term><term><option>--help</option></term>        <listitem>
+	  <para>Gives quick help (which this man page is based on.)</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-v</option></term><term><option>--verbose</option></term>        <listitem>
+	  <para>This switch can appear several times to increase
+                   verbosity level.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>-q</option></term><term><option>--quiet</option></term>        <listitem>
+	  <para>Suppress output.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>EXAMPLES</title>
+    <para>Set the title of the <filename>Image.jpg</filename> file to "My picture":
+      <cmdsynopsis><command>bins_edit -t "My picture" Image.jpg</command></cmdsynopsis>
+    </para>
+    <para>Set the title and location of all <acronym>JPEG</acronym> pictures in the directory:
+      <cmdsynopsis><command>bins_edit --title Holiday --location Paris *.jpg</command></cmdsynopsis>
+    </para>
+    <para>Use of <acronym>HTML</acronym> values:
+      <cmdsynopsis><command>bins_edit --html --description '&lt;b&gt;BINS&lt;/b&gt; is cool' file.jpg</command></cmdsynopsis>
+    </para>
+    <para>Set the title short description and sample image of the album 
+      in the current directory (note the dot as final parameter):
+      <cmdsynopsis><command>bins_edit -a -t "My Album" --sample image.jpg --shortdesc "This is my album" .</command></cmdsynopsis>
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+
+    <para>bins (1).</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:
+-->
+
+
+