<!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:
-->