<?xml version='1.0' ?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

<!ENTITY appversion "2.0">
<!ENTITY docversion "2.0.1">
<!ENTITY pubdate "May, 2003">

]>

<article id="index">
  <articleinfo>
    <title>GNOME PalmOS Synchronization Tools</title>
    
    <authorgroup>
      <author><firstname>Aaron</firstname><surname>Weber</surname></author>
    </authorgroup>
    <copyright>
      <year>2003</year>
      <holder>Ximian, Inc.</holder>
    </copyright>
    
   <releaseinfo>
      This is version &docversion; of the gnome-pilot manual. It describes
      version &appversion; of the gnome-pilot package, used to set up
      and perform synchronization between PalmOS devices and your
      GNOME desktop.
   </releaseinfo>

    <legalnotice id="legalnotice">
      <para>
	  Permission is granted to copy, distribute and/or modify this
	  document under the terms of the GNU Free Documentation
	  License (GFDL), Version 1.1 or any later version published
	  by the Free Software Foundation with no Invariant Sections,
	  no Front-Cover Texts, and no Back-Cover Texts.  You can find
          a copy of the GFDL in the main GNOME help pages or in the
	  file COPYING-DOCS distributed with this software.
         </para>
         <para> 
          This manual is part of a collection of GNOME manuals
          distributed under the GFDL.  If you want to distribute this
          manual separately from the collection, you can do so by
          adding a copy of the license to the manual, as described in
          section 6 of the license.
	</para>

        <para>
          Some product and service names, are trademarks or registered
          trademarks of various companies or organizations. Where
          those names appear in any GNOME documentation, and the
          members of the GNOME Documentation Project are made aware of
          those trademarks, then the names are in capital letters or
          initial capital letters.
        </para>
    </legalnotice>
  </articleinfo>

  <para>
    The <systemitem>gnome-pilot</systemitem> package, along with the
    optional conduits in <systemitem>evolution-pilot</systemitem>,
    allows you to move information between your handheld PalmOS device
    and your GNOME desktop.  You must run the setup tool before
    synchronizing. The setup tool will normally also start the GNOME
    Pilot Daemon, <systemitem>gpilotd</systemitem>. If it is not
    running, you may need to start it with the command
    <command>/usr/libexec/gpilotd</command>. You can also start the
    daemon using the GNOME Pilot panel applet. To add the applet to
    your GNOME panel, right-click on any blank space in the panel and 
    select <menuchoice><guimenu>Add to
    Panel</guimenu><guisubmenu>Utility</guisubmenu><guimenuitem>Pilot
    Applet</guimenuitem></menuchoice>.
  </para>




  <sect1 id="conftool">
    <title>GNOME Pilot Configuration Tool</title>
  <para>
    To start the GNOME Pilot configuration tool, double-click on the
    Palm Pilot icon in the GNOME Control Center, or enter the command
    <command>gpilotd-control-applet</command>. You can also start the
    configuration tool by clicking on the GNOME Pilot applet in your
    panel.
  </para>
  
  <para>
    There are three tabs in the <interface>gnome-pilot
    Settings</interface> tool: <guilabel>PDAs</guilabel>,
    <guilabel>Devices</guilabel>, and
    <guilabel>Conduits</guilabel>. In addition, the first time you run
    the GNOME Pilot tools, you will be guided through setup by an
    assistant.
  </para>

  <sect2 id="assistant">
    <title>The GNOME Pilot Setup Assistant</title>
      <para>
        The setup assistant will guide you through getting your PalmOS
        device ready to synchronize with your desktop system. At each
        step, enter the information requested and then click
        <guibutton>Next</guibutton>.
      </para>
      <para>
        The first step is to describe how your PDA is connected to
        your desktop.  Check <xref linkend="setup-conftool-devices" />
        for more information about the data requested by this step.
      </para>
      <para>
        The second step is device identification. If you have used
        synchronization software with the PDA before, it will
        already have a synchronization ID that your desktop can get
        from it. If you have not, you can set the owner name and ID on
        the PDA from your desktop.
      </para>

      <para>
        Once you have completed this step, the GNOME Pilot software
        will contact your PalmOS device and get or set the owner name
        and other information.
      </para>
      <para>
        The last step is to choose a name to use when referring to the
        configured PalmOS device, and a directory on your desktop
        system where you will store backups and other data.
      </para>

    </sect2>


  <sect2 id="conftool-pilots">
    <title>Adding or Editing a PDA Entry: The "PDAs" Tab</title>
    <para>
      The <guilabel>PDAs</guilabel> tab lists the handheld devices you
      have configured. If you have not used the gnome-pilot Settings
      tool before, you will not have any items in this list, and the
      tool will open a new window to walk you through the process of
      creating one.  To add a new PDA, click
      <guibutton>Add...</guibutton>. To edit an existing PDA entry,
      select it and click the <guibutton>Edit...</guibutton>.  To
      delete an entry, select it and click
      <guibutton>Delete</guibutton>.
    </para>

    <para>
      When editing or creating an entry, you will be asked for four
      pieces of information:
      <variablelist>
        <varlistentry>
          <term>Owner</term>
          <listitem>
            <para>
              This is the Owner name used on your PDA. If your pilot
              already has a name configured, you can get it from the
              pilot by clicking the <guibutton>Get from
              PDA</guibutton> button. Alternatively, you can set or
              change the Owner name by entering a name and clicking
              the <guibutton>Send to PDA</guibutton> button.
            </para>
          </listitem>
        </varlistentry>


        <varlistentry>
          <term>PDA ID</term>
          <listitem>
            <para>
              This is the ID number from your PDA.  You can get this
              value from the handheld by clicking the <guibutton>Get
              from PDA</guibutton> button. Alternatively, you can set
              or change the ID by entering a number and clicking the
              <guibutton>Send to PDA</guibutton> button.
            </para>
          </listitem>
        </varlistentry>


        <varlistentry>
          <term>Name of PDA</term>
          <listitem>
            <para>
              This is the name by which your handheld will be
              identified. For example, you could call it MyPilot, or
              Palm5, or Roger.
            </para>
          </listitem>
        </varlistentry>


        <varlistentry>
          <term>Local folder</term>
          <listitem>
            <para>
              This is the directory where you will store information
              backed up from your handheld.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
    </para>
  </sect2>
  <sect2 id="setup-conftool-devices">
    <title>Adding or Editing an entry under the Device Settings Tab</title>
    <para>
      The device settings tab controls the way your desktop system
      looks at your handheld as hardware. To add an entry to the list,
      click <guibutton>Add...</guibutton>, or, to edit one, select it and
      click <guibutton>Edit...</guibutton>.  To delete an entry,
      select it and click <guibutton>Delete</guibutton>.
    </para>
    <para>
      For each entry you may choose:
    </para>

    <variablelist>
      <varlistentry>
        <term>Name</term>
        <listitem>
          <para>
            This is a name used to display the device in a list. You
            may choose almost any name you find convenient.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Type</term>
        <listitem>
          <para>
            Select the type of connection you have: Serial, USB, IrDA
            (infrared), Network or Bluetooth.  Bluetooth connections
        require that pilot-link has been compiled with bluetooth support.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Timeout</term>
        <listitem>
          <para>
            Amount of time to try to connect to system, in seconds. If
            there is no communication between the desktop and the handheld for
            this many seconds, the system will give up trying.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Device</term>
        <listitem>
          <para>
	    For USB, Serial and IrDA devices types, your handheld
            connects to the computer as a special file in the
            <systemitem>/dev</systemitem> directory. The name of the
            file will vary from system to system. In many cases
            however, it will be <systemitem>/dev/pilot</systemitem>.
            Other possible values are
            <systemitem>/dev/ttyS0</systemitem> or
            <systemitem>/dev/ttyS1</systemitem> for serial cradles
            (under Windows, these would be referred to as COM ports),
            and <systemitem>/dev/ttyUSB0</systemitem> or
            <systemitem>/dev/ttyUSB1</systemitem> for USB cradles.
            The special device name <systemitem>usb:</systemitem>
            can be used to enable libusb syncing (as opposed to usbserial).
            This option may not be available, depending on the version
            of pilot-link in use.
          </para>
        
          <para>
            You will need to make sure that your user account has
            read, write, and execute permissions on this device.  To
            add those permissions, become root with the
            <command>su</command> command and enter the command
            <command>chmod a+wrx /dev/ttyS0</command>. Substitute the
            name of the device you are setting.
          </para>

	  <para>
	    Some devices such as <systemitem>/dev/ttyUSB1</systemitem>
	    only exist while the PDA is attempting to sync.  In such
	    cases, you will need to configure permissions using the
	    <systemitem>udev</systemitem> system.
	  </para>
          <para>
            If you have not chosen the correct device, you will get an
            error message when you click <guibutton>OK</guibutton>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Speed</term>
        <listitem>
          <para>
            For USB, Serial and IrDA connections, select a number from
            the dropdown. The higher the number, the faster you are
            asking the system to transfer information. Normally, you
            should not change this; it is set, by default, for the
            fastest value that your connection type can
            provide. However, you may set it higher or lower if you
            wish. If you experience problems at high speeds, reducing
            the transfer speed sometimes helps.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </sect2>
  <sect2 id="setup-conduits">
    <title>Conduit Settings</title>

    <para>
      A Conduit is a specialized program that channels data between
      your computer and your handheld. The
      <application>gnome-pilot</application> package includes several, and
      you can also install additional conduits such as those for
      Ximian Evolution.
    </para>

    <para>
      Each configured handheld may have its own set of conduits and
      conduit settings.
    </para>

    <para>
      If a conduit is disabled, that type of data will be ignored when
      you HotSync. If a conduit is enabled, its data will be
      synchronized according to its settings. To enable or disable a
      conduit, select it and click the <guilabel>Enable</guilabel> or
      <guilabel>Disable</guilabel> button on the right side of the list
      of conduits.
    </para>
    
    <para>
      To edit the settings, select a conduit and click the
      <guilabel>Settings...</guilabel> button.  Each conduit will have
      at least two settings: an <guilabel>Action</guilabel> to perform
      whenever you synchronize, and a <guilabel>One Time
      Action</guilabel>, performed only the next time you synchronize.
    </para>

    <para>
      Not all conduits will have all of actions. The list of possible
      actions is:
      <variablelist>
      <varlistentry>
        <term>Disabled</term>
        <listitem>
          <para>
            Do nothing.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Synchronize</term>
        <listitem>
          <para>
            Ensure that data is the same in both places, copying new
            data from the PDA to the desktop, and from the desktop to the
            PDA.
          </para>
        </listitem>
      </varlistentry> 

      <varlistentry>
        <term>Copy to pilot</term>
        <listitem>
          <para>
            Copy all data from the desktop to the pilot. New data
            added on the pilot will not be copied back up to the desktop.
          </para>
        </listitem>
      </varlistentry> 


      <varlistentry>
        <term>Copy from pilot</term>
        <listitem>
          <para>
            
            Copy all data from the pilot to the desktop. New data
            added on the desktop will not be copied down to the pilot.
          </para>
        </listitem>
      </varlistentry> 

    </variablelist>
  </para>

  <para>
    Other settings may be available as well, including Conduit
    Priority, which determines the order in which conduits will be
    used, and <guilabel>Sync Private Records</guilabel>, which
  determines whether to copy private information as well as public, or
  just the public data.
</para>
</sect2>
<!--
<sect1 id="advanced">
  <title>The Advanced Tab</title>
  <para>
    The advanced tab allows you to set the Sync PCId. If you know this
    number and wish to change it, enter it and then click
    <guibutton>Close</guibutton>.
  </para>
</sect1>
-->
</sect1>

<sect1 id="pilot-applet">
  <title>The Pilot Applet</title>
  <para>
    The GNOME Pilot panel applet sits in your panel until you are
    ready to synchronize your PalmOS device. If the pilot access
    daemon is running, the applet will appear in black
    and white. If it is not running, the applet will appear red and
    black. If the daemon is paused, the applet will be yellow and black.
  </para>
  <para>
    Click once on the applet with the left mouse button to start the
    GNOME Pilot configuration tool.
  </para>
  <para>
    Other actions for the applet are available in the right-click
    menu. They are:
  </para>
  <variablelist>
      <varlistentry>
        <term>Restore</term>
        <listitem>
          <para>
            If your PalmOS device has lost all data, select this item
            to restore it from a backup you made earlier.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Pause Daemon</term>
        <listitem>
          <para>
            Pause the GNOME Pilot daemon
            <application>gpilotd</application>. If the daemon is paused, this item
            will read <guilabel>Continute</guilabel>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Restart</term>
        <listitem>
          <para>
            Stop and restart the daemon.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Last Log</term>
        <listitem>
          <para>
            Display the results of the last synchronization performed.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Preferences</term>
        <listitem>
          <para>
            Click this item to select what happens when you click the
            applet, and whether to display notices in dialog boxes.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Help...</term>
        <listitem>
          <para>
            Display this manual
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>About</term>
        <listitem>
          <para>
            Information about the application and its authors.
          </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term>Remove from Panel</term>
        <listitem>
          <para>
            Remove the applet from the panel.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Move</term>
        <listitem>
          <para>
            Move the applet with the mouse. To stop moving the applet, click once.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
</sect1>



</article>
