path: root/doc/gphoto2.xml

<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

<!-- just to make all references to the name consistent -->
<!ENTITY docname "The gPhoto2 Manual">

]>
<book>

  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 

  <bookinfo>
    <title>&docname;</title>
    <authorgroup>
      <author>
        <firstname>The gPhoto2</firstname>
        <surname>Team</surname>
      </author>
      <editor>
        <firstname>Tim</firstname>
        <surname>Waugh</surname>
        <affiliation>
	  <address><email>twaugh@redhat.com</email></address>
	</affiliation>
      </editor>
      <editor>
        <firstname>Hans Ulrich</firstname>
        <surname>Niedermann</surname>
        <affiliation>
	  <address><email>gp@n-dimensional.de</email></address>
	</affiliation>
      </editor>
    </authorgroup>
  </bookinfo>
 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 

  <preface>
    <title>About this document</title>
    <subtitle>Mission statement, history and options for the future</subtitle>

    <para>
      This document is "&docname;".
    </para>

    <formalpara>
      <title>Mission statement</title>
      <para>
	&docname; intends to be a comprehensive source of
	information helping users and developers to get more value out
	of the gPhoto2 software suite (i.e. libgphoto2, gphoto2 CLI
	interface, gtkam). 
      </para>
    </formalpara>

    <formalpara>
      <title>Document history</title>
      <para>
	Hans Ulrich Niedermann first wrote a few text files of
	user documentation for gphoto2. Then shortly before the 2.0
	release, Tim Waugh wrote the man pages in Docbook XML. Then 
	hun migrated the text files into the XML file and began with
	general improvements.
      </para>
    </formalpara>

    <formalpara>
      <title>Ideas for the future</title>
      <para>
	The following ideas are just ideas, not mandatory policy.
      </para>
    </formalpara>
    
    <orderedlist>
      <listitem>
	<simpara>	
	  Add the FAQ, a gtkam manual, the older developer
	  docs and the current autogenerated source code documentation
	  in convenient places.
	</simpara>	
      </listitem>
	<listitem>
	<simpara>
	  Improve the document structure.
	</simpara>
	</listitem>
      <listitem>
	<simpara>
	  Create a pure ASCII text version in addition to HTML and
	  PDF.
	</simpara>
      </listitem>
    </orderedlist>

    <!--
    <variablelist>
      <title>Typographic conventions</title>
      <varlistentry>
        <term><command>command</command></term>
        <listitem>
          <simpara>This is a system command which can be executed by
            entering it into a shell. </simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><systemitem class="library">library</systemitem></term>
        <listitem>
          <simpara>This is a system library.</simpara>
        </listitem>
      </varlistentry>
    </variablelist>
    -->
 
  </preface>


  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 

  <chapter id="quickstart">
    <title>Quick start</title>

    <abstract>
      <simpara>
        How you quickly get your pictures to your computer,
        assuming somebody has already set up everything correctly.
      </simpara>
    </abstract>

    <para>This chapter assumes that somebody has set up your system
      correctly for use with 
      <systemitem class="library">libgphoto2</systemitem>. This is
      something the packages from your system vendor
      (<acronym>RPM</acronym> packages, <acronym>DEB</acronym>
      packages or <acronym>BSD</acronym> ports) and/or your system
      administrator should already have done for you. If not, follow
      the instructions in the <xref linkend="setup"/> chapter first.
    </para>

    <para>FIXME: We need examples using <acronym>RS232</acronym>
      cameras, gtkam and the gphoto2 shell.</para>

    <section>
      <title>Using the <command>gphoto2</command> command line
	interface (<acronym>CLI</acronym>)</title>

      <para>
	OK, we begin with finding out how you can connect a camera to
	your computer:
      </para>
      <screen>
<prompt>$uli@mir:~$ </prompt><command>gphoto2 <parameter>--list-ports</parameter></command>
<computeroutput>Devices found: 4
Path                             Description
--------------------------------------------------------------
serial:/dev/ttyS0                Serial Port 0                   
serial:/dev/ttyS2                Serial Port 2                   
serial:/dev/ttyS3                Serial Port 3                   
usb:                             Universal Serial Bus	  </computeroutput>
<prompt>uli@mir:~$ </prompt>
      </screen>
      <para>
	In this example, we see that we have the three serial devices
	<filename class="devicefile">/dev/ttyS0</filename>, 
	<filename class="devicefile">/dev/ttyS2</filename> and
	<filename class="devicefile">/dev/ttyS3</filename> which are
	configured properly and to which <command>gphoto2</command> has
	write permissions for.
	Additionally, there is also a <acronym>USB</acronym>
	bus. However, we cannot tell yet whether we will have write
	access to the <acronym>USB</acronym> device file your camera
	will be assigned from your operating system. 
      </para>

      <para>
	The next step is to connect you camera and find out whether
	<command>gphoto2</command> can find it. This may only work with
	<acronym>USB</acronym>. (FIXME: can any of the people with
	<acronym>RS232</acronym> cameras help me on this issue?)
      </para>
      <screen>
<prompt>uli@mir:~$ </prompt><command>gphoto2 <parameter>--auto-detect</parameter></command>
<computeroutput>Model                          Port                                             
----------------------------------------------------------
Canon PowerShot G2             usb:            </computeroutput>
<prompt>uli@mir:~$ </prompt>
      </screen>
      <para>
	In this case, a camera called "Canon PowerShot G2" is connected
	to your system's <acronym>USB</acronym> bus.
      </para>

      <para>
	OK, so now let's see what we can find out about the camera:
      </para>
      <screen>
<prompt>uli@mir:~$ </prompt><command>gphoto2 <parameter>--summary</parameter></command>
<computeroutput>Detected a 'Canon PowerShot G2'.                                                
Camera Summary:

Camera identification:
  Model: Canon PowerShot G2
  Owner: Hans Ulrich Niedermann

Power status: on battery (power OK)

Flash disk information:
  Drive D:
   31'885'312 bytes total
   27'668'480 bytes available

Time: 2002-07-09 20:45:15 (host time +0 seconds)
</computeroutput>
<prompt>uli@mir:~$ </prompt>
      </screen>
      <para>
	The actual result of 
	<command>gphoto2 <parameter>--summary</parameter></command>
	may be different from camera to camera. However, we can see that
	<command>gphoto2</command> obviously can talk to the camera, and
	we get some information about the camera.
      </para>

      <para>
	OK, now that we have seen that there is some space occupied on
	the storage medium of the camera, let's have a look at what is
	stored there:
      </para>
      <screen>
<prompt>uli@mir:~$ </prompt><command>gphoto2 <parameter>--list-files</parameter></command>
<computeroutput>Detected a 'Canon PowerShot G2'.                                                
There are no files in folder '/'.
There are no files in folder '/DCIM'.
There are 4 files in folder '/DCIM/154CANON':
#1     CRW_5417.CRW               rd  2334 KB image/x-canon-raw
#2     IMG_5415.JPG               rd  1044 KB image/jpeg
#3     IMG_5416.JPG               rd    31 KB image/jpeg
#4     MVI_5418.AVI               rd   682 KB video/x-msvideo
There are no files in folder '/DCIM/CANONMSC'.</computeroutput>
<prompt>uli@mir:~$ </prompt>
      </screen>
      <para>
	There are multiple folders on the camera, and there are several
	files of different types and sizes on stored in one of them. One
	is a raw file of the type this camera produces, two are <acronym>JPEG</acronym>
	files (one large and one small) and one seems to be a short
	video sequence.
      </para>

      <para>
	Now that we have an impression of what expects us when we
	actually download the images from the camera, we are going to do
	that:
      </para>
      <screen>
<prompt>uli@mir:~/tmp$ </prompt><command>gphoto2 <parameter>--get-all-files</parameter></command>
<computeroutput>Detected a 'Canon PowerShot G2'.                                                
Downloading 'CRW_5417.CRW' from folder '/DCIM/154CANON'...
Saving file as CRW_5417.CRW                                                     
Downloading 'IMG_5415.JPG' from folder '/DCIM/154CANON'...
Saving file as IMG_5415.JPG                                                     
Downloading 'IMG_5416.JPG' from folder '/DCIM/154CANON'...
Saving file as IMG_5416.JPG                                                     
Downloading 'MVI_5418.AVI' from folder '/DCIM/154CANON'...
Saving file as MVI_5418.AVI                                                     </computeroutput>
<prompt>uli@mir:~/tmp$ </prompt>
      </screen>
      <para>
	And now we have all the files in our current directory (in
	this case ~/tmp) and can do something with them.
      </para>

      <para>
	Well, that's about it.
	You may also want to have a look at the
	<link linkend="cli-examples">command line examples</link> from
	the <xref linkend="gphoto2-cli"/> man page and the examples
	described on 
	<ulink url="http://www.gphoto.org/">www.gphoto.org</ulink>.
      </para>
    </section>    

  </chapter>
 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 

  <chapter id="setup">
    <title>Setting up your system for use with 
      <systemitem class="library">libgphoto2</systemitem>
      and <command>gphoto2</command>
    </title>

    <abstract>
      <para>This chapter aims to help you set up your system such that
        you can use 
        <systemitem class="library">libgphoto2</systemitem>
        with any frontend. However, we will have some examples using
        the <xref linkend="gphoto2-cli"/> command line frontend, as
        this is the frontend which is always provided.
      </para>
    </abstract>

    <section>
      <title>System Overview</title>
      <para>
        gPhoto2 consists of two libraries
        <systemitem class="library">libgphoto2</systemitem> (
        see <xref linkend="libgphoto2"/>), and
        <systemitem class="library">libgphoto2_port</systemitem>
        (see <xref linkend="libgphoto2_port"/>), which is used by the
        former, 
        and a command line frontend (<command>gphoto2</command>, 
        see <xref linkend="gphoto2-cli"/>). 
        Other (GUI) frontends (like e.g. gtkam) are available as
        separate packages.
      </para>

      <para>
        In order to get access to the camera, your frontend process requires
        write permissions to the respective device special file, e.g. to
        <filename class="devicefile">/dev/ttyS3</filename> or 
        <filename class="devicefile">/proc/bus/usb/1/012</filename>. 
      </para>
      <para>
        For security reasons, we strongly recommend not to run any 
        <xref linkend="libgphoto2"/>
        frontend as root. So you have to set up the permissions of your camera
        device accordingly. This is described in the following two sections,
	<xref linkend="perms-rs232"/> and <xref linkend="perms-usb"/>.
      </para>
      <para>
        Then you can run your frontend. For the command line 
        <xref linkend="libgphoto2"/> frontend 
        <xref linkend="gphoto2-cli"/>,
        this is described in the <xref linkend="gphoto2-cli"/> man
        page.
      </para>    
    </section>

    <section id="perms-rs232">
      <title>Setting up permissions for serial (<acronym>RS232</acronym>) ports</title>
      <note>
	<simpara>
	  I don't have any experience with serial ports for user
	  processes. So take this section with a grain of salt.
	</simpara>
      </note>
      <para>
        If you have a serial port reserved for the camera, you may just chown
        the device file to the user you want to run gphoto2 as.
      </para>    
    </section>

    <section id="perms-usb">
      <title>Setting up permissions for <acronym>USB</acronym> ports</title>
      <para>
        As <acronym>USB</acronym> is designed for hotplugging of
	devices, there is a mechanism that dynamically creates the
	device files for the devices currently connected and switched
	on.
      </para>
      <para>
        The operating system has to determine which users may access a device
        dynamically. As the operating system cannot determine this by itself,
        there have to be some helper applications.
      </para>
      <para>
        The configuration of these helper applications is explained in the
        following section.
      </para>

      <!-- ================================================== -->
      <section>

        <title><acronym>USB</acronym> ports on Linux</title>

        <para>
          As gphoto2 provides a user space driver, in order to have gphoto2
          access your camera, you have to disable all kernel drivers which want
          to handle the camera themselves (e.g. the Linux
          <systemitem class="resource">dc2xx</systemitem> or
          <systemitem class="resource">stv680</systemitem>
          drivers). You can check whether these modules are loaded by
          executing <command>lsmod</command>.
        </para>

	<para>We will not cover basic <acronym>USB</acronym> setup
	  here. For how to get <acronym>USB</acronym> working on your
	  hardware and your system at all, we'd like to refer you to
	  <ulink url="http://www.linux-usb.org/USB-guide/">http://www.linux-usb.org/USB-guide/</ulink>
	  and especially
	  <ulink url="http://www.linux-usb.org/USB-guide/c122.html">http://www.linux-usb.org/USB-guide/c122.html</ulink>
	  .
	  This page explains the USB basics in a better way than we
	  could do.
	</para>

        <para>
          Now that you've got your basic <acronym>USB</acronym> system
	  working, you have basically two options to allow user access
	  to <acronym>USB</acronym> devices on your Linux system:
        </para>

        <orderedlist>

          <listitem id="usbdevfs">
            <simpara>
              allow a certain user and/or group or the whole world
	      access to <emphasis>all</emphasis> <acronym>USB</acronym> devices
              by mounting 
              <filename class="directory">/proc/bus/usb</filename>
              with adequate user and/or group permissions (default
              is world-readable and root-only-writable, which is good)
            </simpara>
          </listitem>

          <listitem id="hotplug">
            <simpara>
              use hotplug (<ulink
                url="http://linux-hotplug.sourceforge.net/">http://linux-hotplug.sourceforge.net/</ulink>)
              and allow access only to the <acronym>USB</acronym>
	      devices you want to be accessible (you need 
              <filename class="directory">/proc/bus/usb</filename>
              mounted here as well, but not mounted writable by
              anybody else than root) 
            </simpara>
          </listitem> 

        </orderedlist>

        <para>    
          Solution <xref linkend="hotplug"/> has a huge advantage over 
          solution <xref linkend="usbdevfs"/>: It doesn't allow the
          user/group to interfere with or eavesdrop on any other
	  <acronym>USB</acronym> devices which might be attached, such
	  as <acronym>USB</acronym> keyboards, fingerprint reader or
	  similar. The following paragraphs thus describe setting up 
          <xref linkend="hotplug"/>.
        </para>

	<note>
	  <para>The fact that we are using the name "usbcam" for
	    setting up permissions for gphoto2 has a reason. In fact,
	    the permission setup you're doing here has nothing to do
	    with gphoto2 specifically - any user space software
	    wanting to access your USB camera will be able to make use
	    of your camera only if the permissions are correctly set
	    up. So I (hun) chose the identifier and script name
	    "usbcam" and not "gphoto2cam" or somethink similar.
	  </para>
	</note>

        <para>
          On Linux systems, from the 2.4 kernel series on, the kernel supports
          hotplugging. You may have to compile a kernel with hotplug support if
          you're not already running one. You may have to install the hotplug
          package
	  (<ulink url="http://linux-hotplug.sourceforge.net/">http://linux-hotplug.sourceforge.net/</ulink>) 
	  if you don't have it installed already.
        </para>

        <para>
          You can find out if your kernel has hotplug support by
	  looking for the file
	  <filename>/proc/sys/kernel/hotplug</filename>.
          If it exists, you have a hotplug enabled kernel. If 
          <screen>
<prompt>[user@system ~]$ </prompt><command>cat <parameter>/proc/sys/kernel/hotplug</parameter></command>
          </screen>
	  prints the path to  your hotplug binary (usually 
          <command>/sbin/hotplug</command>) and this binary exists,
          you are ready to rock.
        </para>      

        <para>
          Also note that the following solution does
          <emphasis>not</emphasis> 
          provide absolute security and that you should definitely
	  know the security implications of the respective
	  <command>usbcam</command> script you are going to use.
        </para>

        <orderedlist>

          <listitem>
            <para>
              You must have the files 
              <filename>devices</filename> and 
              <filename>drivers</filename> in your
              <filename class="directory">/proc/bus/usb</filename>
              directory. If not, check the following paragraph for
              hints.
            </para>
            <para>
              Load your <acronym>USB</acronym> driver and mount the <acronym>USB</acronym> device filesystem,
              i.e. e.g.
              <screen>
<prompt># </prompt><command>modprobe</command> <parameter>usb-uhci</parameter>
<prompt># </prompt><command>modprobe</command> <parameter>usb-ohci</parameter>
<prompt># </prompt><command>mount <parameter>-t usbdevfs</parameter> <parameter>/proc/bus/usb</parameter></command>
              </screen>
              Modern distributions like Redhat 7.2 handle this
              automatically if you have your <acronym>USB</acronym> hardware enabled.
              Check your <acronym>BIOS</acronym> settings if <command>lspci</command>
              doesn't list any <acronym>USB</acronym> hardware.
            </para>
          </listitem>

          <listitem>
            <para>
              Add the output of 
              <screen>
<prompt># </prompt><command>gphoto2 <parameter>--print-usb-usermap</parameter></command>
              </screen>
              to the file
              <filename>/etc/hotplug/usb.usermap</filename> after
              removing all lines beginning with "usbcam".
            </para>
	    <formalpara>
	      <title>Debian peculiarity</title>
	      <para>
		As Debian uses a structured hotplug setup, you 
		should use its benefits instead of working against
		it. Instead of modifying
		<filename>/etc/hotplug/usb.usermap</filename>
		directly, we set up special file
		<filename>/usr/lib/hotplug/usbcam/usb.usermap</filename> 
		and let <command>update-usb.usermap</command>
		update the
		<filename>/etc/hotplug/usb.usermap</filename> file:
		<screen>
<prompt># </prompt><command>mkdir <parameter>/usr/lib/hotplug/usbcam</parameter></command>
<prompt># </prompt><command>gphoto2 <parameter>--print-usb-usermap</parameter> > <filename>/usr/lib/hotplug/usbcam/usb.usermap</filename></command>
<prompt># </prompt><command>update-usb.usermap</command>
		</screen>
	      </para>
	    </formalpara>
            <para>
              This makes hotplug recognise all <acronym>USB</acronym> cameras which your version 
              of <xref linkend="libgphoto2"/> supports and makes
              <command>hotplug</command> run the
              <command>usbcam</command> script you choose in step
              <xref linkend="chooseusbcamscript"/>whenever one of these
              cameras is attached.
            </para>
          </listitem>

          <listitem id="chooseusbcamscript">
            <para>
              Choose the right 
              <filename>/etc/hotplug/usb/usbcam</filename>
              script for you.
              Example scripts are found in 
              <filename class="directory">packaging/linux-hotplug</filename> 
              in the source tree and in 
              <filename class="directory">linux-hotplug/</filename>
              after installation and in the doc dir of the binary
              package. Choose one, adapt it for your needs, and copy
              it to the file <filename>/etc/hotplug/usb/usbcam</filename>. The
              directory 
              <filename class="directory">/etc/hotplug</filename>
              should already exists, whereas it may be that you have
              to create the directory 
              <filename class="directory">/etc/hotplug/usb</filename>.
            </para>
            <para>
              All three scripts shipped with gPhoto2 also have extensive
              commentary explaining their usage in more detail.
            </para>
            <variablelist>
              <varlistentry>
                <term><filename>usbcam.console</filename></term>
                <listitem>
                  <simpara>
                    The most simple solution is using
                    <filename>usbcam.console</filename>. This
                    changes the permissions so that the user owning
                    the console according to the 
                    <systemitem class="library">pam_console</systemitem>
                    access the camera. This works only if you're logging in with
                    <systemitem class="library">pam_console</systemitem>, 
                    i.e. e.g. using <command>gdm</command> on Redhat Linux.
                  </simpara>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><filename>usbcam.user</filename></term>
                <listitem>
                  <simpara>
                    If you want only one user to have access to the camera, use
                    <filename>usbcam.user</filename> and change it
                    accordingly. There is a specially marked line in
                    the script you have to change.
                  </simpara> 
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><filename>usbcam.group</filename></term>
                <listitem>
                  <simpara>
                    If you want multiple users to have access to the camera, add all
                    of these users to one group - either a special
                    group 
                    <systemitem class="groupname">camera</systemitem>
                    or a generic group 
                    <systemitem class="groupname">users</systemitem>
                    will do - and use that group in 
                    <filename>usbcam.group</filename>. 
                    There is a specially marked line in
                    the script you have to change.</simpara>
                </listitem>
              </varlistentry>  
            </variablelist>
          </listitem>

          <listitem>
            <para>
              Make the script file you just created and possibly adapted
              <filename>/etc/hotplug/usb/usbcam</filename>
              executable.
            </para>
          </listitem>

          <listitem>
            <para>
              Plug in the camera and switch it on. If you already did so, please
              unplug and/or switch off first. The kernel will now notice that
              your camera has been connected and, hopefully finding no kernel
              driver for the device, will ask hotplug to do something about it.
            </para>
            <para>
              Hotplug will then look into 
              <filename>/etc/hotplug/usb.usermap</filename> and find that
              the <command>usbcam</command> script is to be called for
              the newly attached device. Thus
              <command>/etc/hotplug/usb/usbcam</command> is executed,
              hopefully setting the device permissions correctly. 
            </para>
            <para>Your <filename>/var/log/messages</filename> syslog
              file will contain some messages to that effect.
            </para>
          </listitem>

          <listitem>
            <para>
              Run <xref linkend="gphoto2-cli"/> or any other 
              <xref linkend="libgphoto2"/> frontend and enjoy:
            </para>
            <screen>
<prompt>[user@home ~]$ </prompt><command>gphoto2</command> <parameter>--list-ports</parameter>
<prompt>[user@home ~]$ </prompt><command>gphoto2</command> <parameter>--auto-detect</parameter>
<prompt>[user@home ~]$ </prompt><command>gphoto2</command> <parameter>--summary</parameter>
<prompt>[user@home ~]$ </prompt><command>gphoto2</command> <parameter>--list-files</parameter>
<prompt>[user@home ~]$ </prompt><command>gphoto2</command> <parameter>--get-all-images</parameter>
	    </screen>
          </listitem>

        </orderedlist>

      </section>

    </section>

    <section>

      <title>Specifying the port and camera you use</title>

      <abstract>
	<simpara>
	  <systemitem class="library">libgphoto2</systemitem> 
	  identifies a camera by two values: the 
	  <link linkend="port-names">port</link> it is connected to
	  and the <link linkend="camera-names">name</link> of the
	  camera.
          How these may be specified is discussed in this chapter.
        </simpara>
      </abstract>

      <section id="port-names">

        <title>Port names</title>

        <variablelist>
          <varlistentry>
            <term>Serial ports</term>
            <listitem>
              <para>
                are named like 
                <systemitem class="resource">serial:/dev/ttyS2</systemitem>
                if you want to use the serial device
                <filename class="devicefile">/dev/ttyS2</filename>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><acronym>USB</acronym> ports</term>
            <listitem>
              <para>
                As <acronym>USB</acronym> works with auto detection, you do not have to specify a device
                file. Therefore you just use the gphoto2 port 
                <systemitem class="resource">usb:</systemitem>.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

      </section>

      <section id="camera-names">

        <title>Camera name</title>

        <para>
          The model name of the camera does not have to be specified when using
          the <systemitem class="resource">usb:</systemitem> port. 
          Otherwise you can specify a camera model like 
          <systemitem class="resource">Canon PowerShot G2</systemitem>. 
          You will be better off choosing the model from
          the list of supported models rather than just trying to type
          your camera model. 
        </para>

        <screen>
          <prompt>[me@home ~]$ </prompt><command>gphoto2</command> <parameter>--camera</parameter> <parameter>"<replaceable>Canon PowerShot G2</replaceable>"</parameter> <parameter>--list-files</parameter>
        </screen>

      </section>

    </section>

  </chapter>

  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 

  <chapter>
    <title>Developer Documentation: The Inner Workings</title>

    <abstract>
      <para>
        How it works internally, how you can work on it and how
        you can use it in your own software.
      </para>
    </abstract>

    <para>The <acronym>API</acronym>s defined here are described in more detail by the
      autogenerated documentation at FIXME. Eventually, they should be
      included here, but as they currently are in Docbook SGML and
      this was written in Docbook XML, this isn't trivial.</para>

    <para>Anyway, we provide you with the architecture context here
      and will let you read up on the <acronym>API</acronym> details in the respective
      external documentation.</para>


    <section>
      <title>The gPhoto2 software architecture</title>
      <figure id="architecture-overview">
        <title>The gPhoto2 system architecture</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/architecture.png" format="PNG"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/architecture.eps" format="EPS"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/architecture.jpg" format="JPG"/>
          </imageobject>
          <textobject>
            <phrase>Diagram describing the gPhoto2 software architecture</phrase>
          </textobject>
          <caption>
            <para>Diagram describing how frontends, libgphoto2,
              camlibs, libgphoto2_port and your Operating System work
              together.</para>
          </caption>
        </mediaobject>
      </figure>
    </section>


    <section>
      <title>The <systemitem class="library">libgphoto2</systemitem>
        <acronym>API</acronym></title>

      <figure id="architecture-libgphoto2">
        <title>The libgphoto2 <acronym>API</acronym> within the gPhoto2 system architecture</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2-api.png" format="PNG"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2-api.eps" format="EPS"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2-api.jpg" format="JPG"/>
          </imageobject>
          <textobject>
            <phrase>The libgphoto2 <acronym>API</acronym> within the context of gPhoto2 software architecture</phrase>
          </textobject>
          <caption>
            <para>Diagram describing where the libgphoto2 <acronym>API</acronym> is
              located within the gPhoto2 software architecture</para>
          </caption>
        </mediaobject>
      </figure>

    </section>


    <section>
      <title>The <systemitem class="library">camlib</systemitem>
        <acronym>API</acronym></title>

      <figure id="architecture-camlib">
        <title>The camlib <acronym>API</acronym> within the gPhoto2 system architecture</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2-camlib.png" format="PNG"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2-camlib.eps" format="EPS"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2-camlib.jpg" format="JPG"/>
          </imageobject>
          <textobject>
            <phrase>The camlib <acronym>API</acronym> within the context of gPhoto2 software architecture</phrase>
          </textobject>
          <caption>
            <para>Diagram describing where the camlib <acronym>API</acronym> is
              located within the gPhoto2 software architecture</para>
          </caption>
        </mediaobject>
      </figure>

    </section>


    <section>
      <title>The <systemitem class="library">libgphoto2_port</systemitem>
        <acronym>API</acronym></title>

      <figure id="architecture-libgphoto2_port">
        <title>The libgphoto2_port <acronym>API</acronym> within the gPhoto2 system architecture</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2_port.png" format="PNG"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2_port.eps" format="EPS"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/libgphoto2_port.jpg" format="JPG"/>
          </imageobject>
          <textobject>
            <phrase>The libgphoto2_port <acronym>API</acronym> within the context of gPhoto2 software architecture</phrase>
          </textobject>
          <caption>
            <para>Diagram describing where the libgphoto2_port <acronym>API</acronym> is
              located within the gPhoto2 software architecture</para>
          </caption>
        </mediaobject>
      </figure>

    </section>

  </chapter>

  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 

  <chapter>
    <title>Utopia: A look into the possible future</title>
    
    <abstract>
      <para>
        Things that may or may not be implemented in the
        future. Usefulness and feasability of these things may vary
        considerably.
      </para>
    </abstract>

    <section>
      <title>Language Bindings</title>
      <para>If somebody is interested in writing a
        <systemitem class="library">libgphoto2</systemitem>
        frontend in another programming language, it would be nice to
        have language bindings for that language. Perl, Python and
        Java (JNI) come to mind...
      </para>
    </section>

    <section>
      <title>The gPhoto2 file system</title>

      <figure id="gphoto2fs">
        <title>The gPhoto2 file system architecture</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/gphotofs.png" format="PNG"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/gphotofs.eps" format="EPS"/>
          </imageobject>
          <imageobject>
            <imagedata fileref="figures/gphotofs.jpg" format="JPG"/>
          </imageobject>
          <textobject>
            <phrase>The gPhoto2 file system software architecture</phrase>
          </textobject>
          <caption>
            <para>Diagram describing where the gPhoto2 file system is
              located within the gPhoto2 and system software architecture</para>
          </caption>
        </mediaobject>
      </figure>
    </section>

  </chapter>

  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== --> 

<reference>
  <title>The gPhoto2 Reference (the man pages)</title>

  <refentry id="gphoto2-cli">
    <refentryinfo>
      <author>
	<firstname>The gPhoto2</firstname><surname>Team</surname>
      </author>

      <editor>
	<firstname>Tim</firstname>
	<surname>Waugh</surname>
	<affiliation>
	  <address><email>twaugh@redhat.com</email></address>
	</affiliation>
      </editor>

      <date>February 2002</date>
    </refentryinfo>

    <refmeta>
      <refentrytitle>gphoto2</refentrytitle>
      <manvolnum>1</manvolnum>
    </refmeta>

    <refnamediv>
      <refname>gphoto2</refname>
      <refpurpose>command-line <systemitem class="library">gphoto2</systemitem> client</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <cmdsynopsis>
	<command>gphoto2</command>
	<arg choice="opt">--debug</arg>
	<group choice="opt">
	  <arg>-q</arg>
	  <arg>--quiet</arg>
	</group>
	<group choice="opt">
	  <arg>-v</arg>
	  <arg>--verbose</arg>
	</group>
	<group choice="opt">
	  <arg>-h</arg>
	  <arg>--help</arg>
	</group><sbr/>
	<arg choice="opt">--list-cameras</arg>
	<arg choice="opt">--usb-usermap-script <replaceable>NAME</replaceable></arg><sbr/>
	<arg choice="opt">--print-usb-usermap</arg>
	<arg choice="opt">--list-ports</arg>
	<arg choice="opt">--stdout</arg><sbr/>
	<arg choice="opt">--stdout-size</arg>
	<arg choice="opt">--auto-detect</arg>
	<arg choice="opt">--port <replaceable>PATH</replaceable></arg><sbr/>
	<arg choice="opt">--speed <replaceable>SPEED</replaceable></arg>
	<arg choice="opt">--camera <replaceable>MODEL</replaceable></arg>
	<arg choice="opt">--filename <replaceable>FILENAME</replaceable></arg><sbr/>
	<arg choice="opt">--usbid <replaceable>USBID</replaceable></arg>
	<group choice="opt">
	  <arg>-a</arg>
	  <arg>--abilities</arg>
	</group>
	<arg choice="opt">--folder <replaceable>FOLDER</replaceable></arg><sbr/>
	<group choice="opt">
	  <group>
	    <arg>-R</arg>
	    <arg>--recurse</arg>
	  </group>
	  <arg choice="opt">--norecurse</arg>
	</group>
	<group choice="opt">
	  <arg>-l</arg>
	  <arg>--list-folders</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-L</arg>
	  <arg>--list-files</arg>
	</group>
	<group choice="opt">
	  <arg>-m <replaceable>NAME</replaceable></arg>
	  <arg>--mkdir <replaceable>NAME</replaceable></arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-r <replaceable>NAME</replaceable></arg>
	  <arg>--rmdir <replaceable>NAME</replaceable></arg>
	</group>
	<group choice="opt">
	  <arg>-n</arg>
	  <arg>--num-files</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-p <replaceable>RANGE</replaceable></arg>
	  <arg>--get-file <replaceable>RANGE</replaceable></arg>
	</group>
	<group choice="opt">
	  <arg>-P</arg>
	  <arg>--get-all-files</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-t <replaceable>RANGE</replaceable></arg>
	  <arg>--get-thumbnail <replaceable>RANGE</replaceable></arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-T</arg>
	  <arg>--get-all-thumbnails</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-r <replaceable>RANGE</replaceable></arg>
	  <arg>--get-raw-data <replaceable>RANGE</replaceable></arg>
	</group>
	<arg choice="opt">--get-all-raw-data</arg><sbr/>
	<arg choice="opt">--get-audio-data <replaceable>RANGE</replaceable></arg>
	<arg choice="opt">--get-all-audio-data</arg><sbr/>
	<group choice="opt">
	  <arg>-d <replaceable>RANGE</replaceable></arg>
	  <arg>--delete-file <replaceable>RANGE</replaceable></arg>
	</group>
	<group choice="opt">
	  <arg>-D</arg>
	  <arg>--delete-all-files</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-u <replaceable>FILENAME</replaceable></arg>
	  <arg>--upload-file <replaceable>FILENAME</replaceable></arg>
	</group>
	<arg choice="opt">--capture-preview</arg><sbr/>
	<arg choice="opt">--capture-image</arg>
	<arg choice="opt">--capture-movie</arg>
	<arg choice="opt">--capture-sound</arg><sbr/>
	<arg choice="opt">--capture-show-info <replaceable>RANGE</replaceable></arg><sbr/>
	<arg choice="opt">--summary</arg>
	<arg choice="opt">--manual</arg>
	<arg choice="opt">--about</arg>
	<arg choice="opt">--shell</arg>
      </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para><xref linkend="libgphoto2"/> is a 
        cross-platform digital camera library, and
        <xref linkend="gphoto2-cli"/> is a command-line client for
        it.</para>

      <para>Where an option takes a range of files, thumbnails, or
       other data, they are numbered beginning at 1.  A range is a
       comma-separated list of numbers or spans
       (<quote><replaceable>first</replaceable>-<replaceable>last</replaceable></quote>).
       Ranges are XOR (exclusive or), so that <quote>1-5,3,7</quote>
       is equivalent to <quote>1,2,4,5,7</quote>.</para>

      <variablelist>
	<varlistentry>
	  <term><option>--debug</option></term>
	  <listitem>
	    <para>Turn on debugging.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-q</option>, <option>--quiet</option></term>
	  <listitem>
	    <para>Quiet output (default=verbose).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-v</option>, <option>--version</option></term>
	  <listitem>
	    <para>Display version and exit.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-h</option>, <option>--help</option></term>
	  <listitem>
	    <para>Display a short usage message.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--list-cameras</option></term>
	  <listitem>
	    <para>List supported camera models.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--usb-usermap-script</option> <replaceable>NAME</replaceable></term>
	  <listitem>
	    <para>Use <replaceable>NAME</replaceable> as the hotplug usb script used in the output of <option>--print-usb-usermap</option>. Default is "usbcam".</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--print-usb-usermap</option></term>
	  <listitem>
	    <para>For every camera supported by your version of <command>gphoto2</command>, print the corresponding line for inclusion into the <filename>usb.usermap</filename> hotplug config file. The script name used in these lines is specified with the <option>--usb-usermap-script</option> option.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--list-ports</option></term>
	  <listitem>
	    <para>List supported port devices.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--stdout</option></term>
	  <listitem>
	    <para>Send file to stdout.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--stdout-size</option></term>
	  <listitem>
	    <para>Print filesize before data.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--auto-detect</option></term>
	  <listitem>
	    <para>List auto-detected cameras.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--port</option> <replaceable>PATH</replaceable></term>
	  <listitem>
	    <para>Specify port device.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--speed</option> <replaceable>SPEED</replaceable></term>
	  <listitem>
	    <para>Specify serial transfer speed.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--camera</option> <replaceable>MODEL</replaceable></term>
	  <listitem>
	    <para>Specify camera model.  Most model names contain
	     spaces: remember to enclose the name in quotes so that
	     the shell knows it is one parameter.  For example:
	     <userinput><option>--camera</option> "Kodak
	     DC240"</userinput>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--filename</option> <replaceable>FILENAME</replaceable></term>
	  <listitem>
	    <para>Specify a filename.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--usbid</option> <replaceable>USBID</replaceable></term>
	  <listitem>
	    <para>(Expert only) Override <acronym>USB</acronym> IDs.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-a</option>, <option>--abilities</option></term>
	  <listitem>
	    <para>Display camera abilities.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-f</option>, <option>--folder</option>
           <replaceable>FOLDER</replaceable></term>
	  <listitem>
	    <para>Specify camera folder (default="/").</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-R</option>, <option>--recurse</option></term>
	  <listitem>
	    <para>Recursion (default for download).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--no-recurse</option></term>
	  <listitem>
	    <para>No recursion (default for deletion).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-l</option>, <option>--list-folders</option></term>
	  <listitem>
	    <para>List folders in folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-L</option>, <option>--list-files</option></term>
	  <listitem>
	    <para>List files in folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-m</option>, <option>--mkdir</option>
	   <replaceable>NAME</replaceable></term>
	  <listitem>
	    <para>Create a directory.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-r</option>, <option>--rmdir</option>
	   <replaceable>NAME</replaceable></term>
	  <listitem>
	    <para>Remove a directory.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-n</option>, <option>--num-files</option></term>
	  <listitem>
	    <para>Display number of files.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-p</option>, <option>--get-file</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Get files given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-P</option>, <option>--get-all-files</option></term>
	  <listitem>
	    <para>Get all files from folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-t</option>, <option>--get-thumbnail</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Get thumbnails given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-T</option>, <option>--get-all-thumbnails</option></term>
	  <listitem>
	    <para>Get all thumbnails from folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-r</option>, <option>--get-raw-data</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Get raw data given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--get-all-raw-data</option></term>
	  <listitem>
	    <para>Get all raw data from folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--get-audio-data</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Get audio data given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--get-all-audio-data</option></term>
	  <listitem>
	    <para>Get all audio data from folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--delete-files</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Delete files given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--delete-all-files</option></term>
	  <listitem>
	    <para>Delete all files in folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-u</option>, <option>--upload-file</option>
	   <replaceable>FILENAME</replaceable></term>
	  <listitem>
	    <para>Upload a file to camera.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--capture-preview</option></term>
	  <listitem>
	    <para>Capture a quick preview.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--capture-image</option></term>
	  <listitem>
	    <para>Capture an image.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--capture-movie</option></term>
	  <listitem>
	    <para>Capture a movie.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--capture-sound</option></term>
	  <listitem>
	    <para>Capture an audio clip.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--show-info</option> <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Show info.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--summary</option></term>
	  <listitem>
	    <para>Summary of camera status.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--manual</option></term>
	  <listitem>
	    <para>Camera driver manual.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--about</option></term>
	  <listitem>
	    <para>About the camera driver.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--shell</option></term>
	  <listitem>
	    <para>Start the gphoto2 shell, an interactive environment.
              See <link linkend="shell-mode">SHELL MODE</link><!--xref linkend="shell-mode"/--> for a detailed description.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1 id="shell-mode">
      <title>Shell Mode</title>
      <para>The following commands are available:</para>
      
      <variablelist>
        <varlistentry>
          <term>cd</term>
          <listitem>
            <para>Change to a directory on the camera.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>lcd</term>
          <listitem>
            <para>Change to a directory on the local
              machine.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>exit, quit, q</term>
          <listitem>
            <para>Exit the gphoto2 shell.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>get</term>
          <listitem>
            <para>Download the file to the current directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>get-thumbnail</term>
          <listitem>
            <para>Download the thumbnail to the current directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>get-raw</term>
          <listitem>
            <para>Download raw data to the current directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>show-info</term>
          <listitem>
            <para>Show information.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>delete</term>
          <listitem>
            <para>Delete a file or directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>show-exif</term>
          <listitem>
            <para>Show EXIF information (only if compiled with
              EXIF support).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>help, ?</term>
          <listitem>
            <para>Displays command usage.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>ls</term>
          <listitem>
            <para>List the contents of the current directory on
              the camera.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>See also</title>
      <para><xref linkend="libgphoto2"/>,
	  &docname;,
        <filename path="doc/">gphoto2-cli.txt</filename>, 
	  <ulink url="http://www.gphoto.org/">http://www.gphoto.org/</ulink>,
	  <ulink url="http://www.gphoto.org/gphoto2/cli.html">http://www.gphoto.org/gphoto2/cli.html</ulink>
      </para>
    </refsect1>

    <refsect1 id="cli-examples">
      <title>Examples</title>
      <variablelist>
        <varlistentry>
          <term><userinput><command>gphoto2</command> <option>--list-ports</option></userinput></term>
          <listitem>
            <para>Shows what kinds of ports (<acronym>USB</acronym> and serial) you have.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><userinput><command>gphoto2</command> <option>--auto-detect</option></userinput></term>
          <listitem>
            <para>Shows what camera(s) you have connected.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><userinput><command>gphoto2</command> <option>--list-files</option></userinput></term>
          <listitem>
            <para>List files on camera.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><userinput><command>gphoto2</command> <option>--get-file</option> <parameter>7-13</parameter></userinput></term>
          <listitem>
            <para>Get files number 7 through 13 from the list output by <userinput><command>gphoto2</command> <option>--list-files</option></userinput>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><userinput><command>gphoto2</command> <option>--usb-usermap-script</option> <parameter>gphoto2cam</parameter> <option>--print-usb-usermap</option></userinput> >> <filename>/etc/hotplug/usb.usermap</filename></term>
          <listitem>
            <para>Append a line to the <command>hotplug</command> config file <filename>/etc/hotplug/usb.usermap</filename> for every supported camera, using <filename>/etc/hotplug/usb/gphoto2cam</filename> for setting up permissions correctly.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

  </refentry>

  <refentry id="libgphoto2">
    <refentryinfo>
      <author><firstname>The gPhoto2</firstname><surname>Team</surname></author>
      <editor>
	<firstname>Hans Ulrich</firstname>
	<surname>Niedermann</surname>
	<affiliation>
	  <address><email>gp@n-dimensional.de</email></address>
	</affiliation>
      </editor>
    </refentryinfo>

    <refmeta>
      <refentrytitle>gphoto2</refentrytitle>
      <manvolnum>3</manvolnum>
    </refmeta>

    <refnamediv>
      <refname>gphoto2</refname>
      <refpurpose>cross-platform digital camera library</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <synopsis>#include &lt;gphoto2.h&gt;</synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para>The <systemitem class="library">gphoto2</systemitem>
        library provides applications with access to a variety of
        cameras.</para>
      <para>This man page will be extended with autogenerated
        documentation of the interface types and methods used for
        communication between the 
        <systemitem class="library">gphoto2</systemitem> 
        library and a frontend.</para> 
    </refsect1>

    <refsect1>
      <title>Files</title>
      <variablelist>
        <varlistentry>
          <term><filename>~/.gphoto/settings</filename></term>
          <listitem>
            <para>Here
              <systemitem class="library">gphoto2</systemitem>
              applications may store their configuration used to
              access
              <systemitem class="library">gphoto2</systemitem>.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>See also</title>
        <para><xref linkend="gphoto2-cli"/>,
          <xref linkend="libgphoto2_port"/>,
	  &docname;,
	  the automatically generated <acronym>API</acronym> docs,
          <ulink url="http://www.gphoto.org/">http://www.gphoto.org/</ulink> 
      </para>
    </refsect1>

  </refentry>

    <refentry id="libgphoto2_port">
      <refentryinfo>
        <author><firstname>The gPhoto2</firstname><surname>Team</surname></author>
        <editor>
          <firstname>Hans Ulrich</firstname>
          <surname>Niedermann</surname>
          <affiliation>
            <address><email>gp@n-dimensional.de</email></address>
          </affiliation>
        </editor>
      </refentryinfo>

      <refmeta>
        <refentrytitle>gphoto2_port</refentrytitle>
        <manvolnum>3</manvolnum>
      </refmeta>

      <refnamediv>
        <refname>gphoto2_port</refname>
        <refpurpose>cross-platform port access library</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <synopsis>#include &lt;gphoto2_port.h&gt;</synopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>
        <para>The 
          <systemitem class="library">libgphoto2_port</systemitem> 
          library was written to provide <xref linkend="libgphoto2"/>
          with a generic way of accessing ports. In this function, 
          <systemitem class="library">libgphoto2_port</systemitem> is the
          successor of the 
          <systemitem class="library">libgpio</systemitem> library.
        </para>
        <para>
          Currently, 
          <systemitem class="library">libgphoto2_port</systemitem> 
          supports serial (<acronym>RS-232</acronym>) and <acronym>USB</acronym> connections, the latter
          requiring 
          <systemitem class="library">libusb</systemitem>
          to be installed.
        </para>
        <para>
          The autogenerated <acronym>API</acronym> docs will be added here in the future.
        </para>
      </refsect1>

      <refsect1>
        <title>See also</title>
        <para><xref linkend="libgphoto2"/>,
          &docname;,
          <ulink url="http://www.gphoto.org/">http://www.gphoto.org/</ulink>,
	  the automatically generated <acronym>API</acronym> docs,
          <ulink url="http://libusb.sourceforge.net/">http://libusb.sourceforge.net/</ulink>
        </para>
      </refsect1>
    </refentry>

  </reference>

  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== -->
  
  <appendix>
    <title>Resources: Where to find related information</title>
    <variablelist>
      <varlistentry>
        <term><ulink url="http://www.gphoto.org/">http://www.gphoto.org/</ulink></term>
        <listitem>
          <simpara>The home page of the gPhoto project.</simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><ulink url="http://sourceforge.net/projects/gphoto/">http://sourceforge.net/projects/gphoto/</ulink></term>
        <listitem>
          <simpara>The gPhoto project page.</simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><ulink url="http://libusb.sourceforge.net/">http://libusb.sourceforge.net/</ulink></term>
        <listitem>
          <simpara>The <systemitem class="library">libusb</systemitem>
	    home page. <systemitem class="library">libusb</systemitem>
	    allows C programs to access the <acronym>USB</acronym> interface of all
	    supported operating systems in an OS independent manner.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><ulink url="http://sourceforge.net/projects/libexif/">http://sourceforge.net/projects/libexif/</ulink></term>
        <listitem>
          <simpara>The
            <systemitem class="library">libexif</systemitem> project
            page. <systemitem class="library">libexif</systemitem>
	    allows programs written in C to access the metainformation
	    from the <acronym>EXIF</acronym> tags in the <acronym>JPEG</acronym> files most modern cameras
	    produce.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
	<term><ulink url="http://www.teaser.fr/~hfiguiere/linux/digicam.html">http://www.teaser.fr/~hfiguiere/linux/digicam.html</ulink></term>
	<listitem>
	  <simpara>Hubert Figuiere's digicam support list</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><ulink url="http://n-dimensional.de/projects/digicam/">http://n-dimensional.de/projects/digicam/</ulink></term>
	<listitem>
	  <simpara>Hans Ulrich Niedermann's home page (one of the
	    developers), with current issues of &docname;,
	    daily CVS snapshot tarballs and patches, and packages
	    which are updated from time to time.
	  </simpara>
	</listitem>
      </varlistentry>
    </variablelist>
  </appendix>

  <!-- =========================================================== --> 
  <!-- =========================================================== --> 
  <!-- =========================================================== -->

</book>

<!--
Local Variables:
mode: xml
sgml-indent-data: t
End:
-->