<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "1.0">
  <!ENTITY manrevision "1.0">
  <!ENTITY date "February 2006">
  <!ENTITY app "<application>Conduit Synchronizer</application>">
  <!ENTITY appname "Conduit">
]>

<article id="index" lang="en">
  <articleinfo>
    <title>&appname; Manual</title>
    <abstract role="description">
      <para>&appname; is a program that synchronizes things</para>
    </abstract>
    <copyright>
      <year>2007</year>
      <holder>John Stowers</holder>
    </copyright>
    <publisher>
      <publishername> GNOME Documentation Project </publishername>
    </publisher>

    <authorgroup>
      <author role="maintainer">
        <firstname>John</firstname>
        <surname>Stowers</surname>
      </author>
      <author>
        <firstname>Brent</firstname>
        <surname>Gueth</surname>
      </author>
    </authorgroup>

    <revhistory>
      <revision>
        <revnumber>&appname; Manual &manrevision;</revnumber>
        <date>2008-01-03</date>
      </revision>
    </revhistory>

    <releaseinfo>This manual describes version &appversion; of &appname;</releaseinfo>
  </articleinfo>
    
  <section>
    <title>What is Conduit</title>
    <para>
      <ulink type="http" url="http://www.conduit-project.org">Conduit</ulink> is a synchronization application for GNOME. It allows you to synchronize your files, photos, emails, contacts, notes, calendar data and any other type of personal information and synchronize that data with another computer, an online service, or even another electronic device. Conduit manages the synchronization and conversion of data into other formats. For example, Conduit allows you to; </para>
      <itemizedlist>
        <listitem>
          <para>Synchronize your <ulink type="http" url="http://www.gnome.org/projects/tomboy/">Tomboy notes</ulink> with another computer </para>
        </listitem>
        <listitem>
          <para>Synchronize your PIM data to your mobile phone, <ulink type="http" url="http://en.wikipedia.org/wiki/IPod">iPod</ulink>, <ulink type="http" url="http://en.wikipedia.org/wiki/Nokia_N800">Nokia Internet tablet</ulink>, or between computers </para>
        </listitem>
        <listitem>
          <para>Upload photos to <ulink type="http" url="http://www.flickr.com">Flickr</ulink>, <ulink type="http" url="http://picasaweb.google.com">Picasa</ulink>, <ulink type="http" url="http://www.smugmug.com">Smugmug</ulink>, <ulink type="http" url="http://shutterfly.com">Shutterfly</ulink> and your iPod,  </para>
        </listitem>
        <listitem><para>... and many more</para></listitem>
      </itemizedlist>
      <para>Any combination you can imagine, Conduit will take care of the conversion and synchronization.   </para>
      <section>
        <title>Use Cases</title>
        <itemizedlist>
          <listitem>
            <para>Fred wants to sync his tomboy notes with <ulink type="http" url="http://www.google.com/notebook">Google notebook</ulink> </para>
          </listitem>
          <listitem>
            <para>Joey wants to sync whatever is on his desktop to his <ulink type="http" url="http://www.backpackit.com">backpack account</ulink> </para>
          </listitem>
          <listitem><para>Nellie wants to keep a directory on his laptop and his desktop in sync</para></listitem>
          <listitem><para>Paul wants to keep his evolution contacts in sync with his mobile phone</para></listitem>
          <listitem><para>Steve wants to keep his gnome preferences in sync between his two computers</para></listitem>
          <listitem>
            <para>John wants to keep a directory of <ulink type="http" url="http://openoffice.org">OpenOffice</ulink> documents in sync with copies held on <ulink type="http" url="http://docs.google.com">Google Docs</ulink> </para>
          </listitem>
          <listitem><para>Pete wants to have photos saved to his server to be pushed to an external back up (usb hard drive / off-site ftp)</para></listitem>
        </itemizedlist>
      </section>
      <section>
        <title>Introduction</title>
        <para>Conduit's goals are to synchronize your data as seamlessly as possible, be it from remote device or remote websites. It is about extending your life as you see it needs to be, no longer constrained by data, devices or formats. Conduit enables you to take your data where you want when you want. All of your mobile devices could be synchronized automatically by Conduit. Home file back-ups to a remote server? Synced automatically. </para>
        <para>It may sometimes seem that Conduit is overly complicated, one of the design goals has always been to make the interface as simple and intuitive as possible. However  Conduit is much more powerful then the simplistic design may lead on. This documentation will describe all the configuration options for groups and data providers, while the following gives some examples of items you may wish to synchronize; </para>
        <itemizedlist>
          <listitem>
            <para>A <ulink type="http" url="http://www.gnome.org">GNOME</ulink> user might store information in a wide variety of places on the desktop including; </para>
            <itemizedlist>
              <listitem>
                <para>
                  <ulink type="http" url="http://www.gnome.org/projects/evolution/">Evolution</ulink> (email, calendar, address book) </para>
              </listitem>
              <listitem>
                <para>
                  <ulink type="http" url="http://www.gnome.org/projects/tomboy/">Tomboy</ulink> (notes) </para>
              </listitem>
              <listitem><para>Directories (important files)</para></listitem>
              <listitem><para>Photos</para></listitem>
              <listitem><para>Bookmarks (web and feeds)</para></listitem>
              <listitem><para>Music</para></listitem>
            </itemizedlist>
          </listitem>
          <listitem><para>The user might also use one of the many popular online services including <itemizedlist><listitem><para><ulink type="http" url="http://del.icio.us">Delicious</ulink> (bookmarks) </para></listitem><listitem><para><ulink type="http" url="http://www.gmail.com">Gmail</ulink> (bookmarks, calendar, feeds, email, photos) </para></listitem><listitem><para><ulink type="http" url="http://www.flickr.com">Flickr</ulink> (photos)  </para></listitem></itemizedlist></para></listitem>
          <listitem><para>They probably also own another electronic device such as <itemizedlist><listitem><para>A second laptop, also running GNOME</para></listitem><listitem><para>A mobile phone</para> </listitem><listitem><para>A <ulink type="http" url="http://www.nokia.com">Nokia</ulink> 770/800 </para></listitem><listitem><para>A <ulink type="http" url="http://www.palm.com">Palm</ulink> or <ulink type="http" url="http://www.microsoft.com/windowsmobile/default.mspx">Windows Mobile</ulink> Pocket PC </para></listitem><listitem><para>An iPod</para>  </listitem></itemizedlist></para></listitem>
        </itemizedlist>
        <para>Its hard enough keeping your information organized when limited to the desktop, let alone the added burden of keeping your information in sync with any of the other services or devices listed above. </para>
        <para>Our goal for Conduit is to allow GNOME users to keep their information in sync. Irrespective of the type, irrespective of the way in which that information is stored. Conduit should just work. </para>
      </section>
    </section>
    <section>
      <title>Understanding the Conduit Interface</title>
      <section>
        <title>Introduction</title>
        <para>Conduit has a few basic concepts worth understanding before you begin. Knowing these concepts will help you discover things that you never knew you could keep in sync, for example, uploading photos right from your mobile phone to Picasa! </para>
        <para>
          <figure id="conduit-FIG-gui-parts">
            <title>Conduit GUI</title>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="figures/conduit-gui-parts.png" format="PNG"/>
                </imageobject>
                <caption>
                  <para>The Parts of the Conduit GUI</para>
                </caption>
                </mediaobject>
            </screenshot>
          </figure>
        </para>
        <para><xref linkend="conduit-FIG-gui-parts" /> shows the Conduit interface's four main components;</para>
        <orderedlist numeration="arabic">
          <listitem><para>The Menu<itemizedlist><listitem><para>The file, edit and help menus store operations which apply to all groups. For more information on the contents of these menus, see below. </para></listitem></itemizedlist></para></listitem>
          <listitem><para>The Data Provider Pane <itemizedlist><listitem><para>Located on the left hand side of the window, lists all of the data providers that are detected and ready for use on your system.</para></listitem><listitem><para>Data providers are the source or destination of data you wish to sync. Please refer to the <emphasis>Data Provider</emphasis> section of the documentation to receive instructions on how to configure each data provider.</para></listitem></itemizedlist></para></listitem>
          <listitem><para>The Canvas Pane <itemizedlist><listitem><para>Used to create groups of data providers to synchronize. Drag a data source to the left of the canvas pane and one or more data sinks to the right of the data pane to create a group.   For more explanation on groups please check <xref linkend="conduit-providers-and-groups" />. </para></listitem></itemizedlist></para></listitem>
          <listitem><para>The Conflicts Pane <itemizedlist><listitem><para>If you receive any conflict notifications while trying to run a sync job they will be listed here.  For information on how to deal with possible conflicts please check the <emphasis>Conflicts and Resolutions</emphasis> section of the documentation.  </para></listitem></itemizedlist></para></listitem>
        </orderedlist>
      </section>
      <section id="conduit-menus">
        <title>The Menus</title>
        <section>
          <title>The File Menu</title>
          <itemizedlist>
            <listitem><para><menuchoice> <guimenu>File</guimenu> <guimenuitem>Save</guimenuitem> </menuchoice> Saves all configured synchronization groups. Groups are saved automatically when you exit Conduit if you have selected <guilabel>Save Settings on Exit</guilabel> in <xref linkend="conduit-preferences-window" /></para></listitem>
            <listitem><para><menuchoice> <guimenu>File</guimenu> <guimenuitem>Synchronize All</guimenuitem> </menuchoice> Synchronizes all groups at the same time. You can still run each sync group separately (see the <emphasis>Groups</emphasis> section), but this saves you the time of having to select and manually going through each group to start the sync process.</para></listitem>
            <listitem><para><menuchoice> <guimenu>File</guimenu> <guimenuitem>Quit</guimenuitem> </menuchoice> Closes conduit. You will be prompted to stop any synchronization currently in progress.</para></listitem>
          </itemizedlist>
        </section>
        <section>
          <title>The Edit Menu</title>
          <itemizedlist>
            <listitem><para><menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Clear Canvas</guimenuitem> </menuchoice> Removes all configurations, data providers, and groups from the canvas pane. This allows you start using the canvas as it was a clean slate. The best time to use this is when you are re-configuring a large portion of your sync groups. There is no quick way to revert back after selecting this setting.</para></listitem>
            <listitem><para><menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Preferences</guimenuitem> </menuchoice> Global Conduit settings that effect all of your sync groups and basic Conduit operations. For more information please see <xref linkend="conduit-preferences-window" /></para></listitem>
          </itemizedlist>
        </section>
        <section>
          <title>The Help Menu</title>
          <itemizedlist>
            <listitem><para><menuchoice> <guimenu>Help</guimenu> <guimenuitem>Developers</guimenuitem> </menuchoice> If you are developer, and interested in contributing to Conduit, then this option includes links to all the appropriate documentation.</para></listitem>
            <listitem><para><menuchoice> <guimenu>Help</guimenu> <guimenuitem>Contents</guimenuitem> </menuchoice> Shows this help document.</para></listitem>
            <listitem><para><menuchoice> <guimenu>Help</guimenu> <guimenuitem>About</guimenuitem> </menuchoice> Shows the version number and a list of Conduit developers.</para></listitem>
          </itemizedlist>
        </section>
      </section>
      <section id="conduit-preferences-window">
        <title>The Preferences Window</title>
        <para>The Conduit preferences is accessed from the Edit menu. Any setting or change that you make within the preferences menu affect all of your sync groups and basic Conduit operations.</para>
        <section>
          <title>Configuration Tab</title>
          <para>The configuration tab is where all of Conduit's global settings are configured.   There are six global settings: </para>
          <itemizedlist>
            <listitem>
              <para><guilabel>Save Settings on Exit</guilabel></para>
              <para>Instructs Conduit that all configured dataproviders and groups should be saved when the application exits. </para>
            </listitem>
            <listitem>
              <para><guilabel>Show Status Icon</guilabel></para>
              <para>Shows a status icon in the notification area. This icon animates to indicate a sync is in progress.</para>
            </listitem>
            <listitem>
              <para><guilabel>Minimize to Notification Area</guilabel></para>
              <para>Instructs Conduit to minimize to the notification area instead of to the panel.</para>
            </listitem>
            <listitem>
              <para><guilabel>Use Built in Web Browser</guilabel></para>
              <para>When a data provider requires that you log onto a website, this option tells Conduit to use its own web browser to do so.</para>
            </listitem>
            <listitem><para><guilabel>When an Item Has Been Deleted</guilabel></para></listitem>
            <listitem><para><guilabel>Where There is a Two Way Conflict</guilabel></para></listitem>
          </itemizedlist>
        </section>
        <section>
          <title>Data Providers Tab</title>
          <para>This tab shows a list of the data providers that are currently installed.  </para>
        </section>
        <section>
          <title>Data Conversions Tab</title>
          <para>This tab lists the data conversions that Conduit is capable of performing. </para>
        </section>
        <section>
          <title>Mapping DB</title>
          <para>This is a list of the UID that Conduit uses to maintain accurate sync data from different sources.  Here you have the option to clear the mapping database. </para>
        </section>
      </section>
      <section>
        <title>The Web Login Window</title>
        <para>Sometimes you will be required to log into a website associated with certain data providers. The frequency at which you may have to log in is not determined by Conduit, but by the security policy of the respective data provider. For example, Box.net requires you to log in every time Conduit is run, whereas Flickr only requires you to log in once, to give permission to Conduit to upload photos. If you are required to log into a website, and you have selected the <guilabel>Use Built in Web Browser</guilabel> from the Conduit preferences, then a window will pop up like the one shown below. </para>
        <para>
          <figure id="conduit-FIG-login">
            <title>Conduit Login Window</title>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="figures/conduit-login.png" format="PNG"/>
                </imageobject>
                <caption>
                  <para>The window shown when logging into data provider websites</para>
                </caption>
                </mediaobject>
            </screenshot>
          </figure>
        </para>
      </section>
      <section id="conduit-providers-and-groups">
        <title>Data Providers and Groups</title>
        <para>Conduit represents the things your want to synchronize graphically. When data providers get added to the canvas, they get arranged into so called groups. A group is a collection of data providers that share data. In the figure below you will see the following parts </para>
        <para>
          <figure id="conduit-FIG-dp-parts">
            <title>Conduit Depicts Synchronizations Graphically</title>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="figures/conduit-dp.png" format="PNG"/>
                </imageobject>
                <caption>
                  <para>Parts of a Synchronization Group</para>
                </caption>
                </mediaobject>
            </screenshot>
          </figure>
        </para>
        <orderedlist numeration="arabic">
          <listitem><para>A data provider for synchronizing two way whose status indicates that it is ready to be synchronized.</para></listitem>
          <listitem><para>A group containing two folder dataproviders. The arrow has two ends, indicating that the two dataproviders will undergo a two way synchronization, that is data will flow in both directions, and both folders will contain the same information once the sync finishes.</para></listitem>
          <listitem><para>A second folder data provider. By convention, data providers that lie on the right side of groups are called data sinks. This is because during a one way sync, data can only flow into them.</para></listitem>
          <listitem><para>A Facebook and Picasa data provider for uploading images to those sites. Notice that that the group has three data providers, and the arrow has changed to indicate that data will flow in only one direction, that is images will be uploaded from F-Spot to Facebook and Picasa.</para></listitem>
        </orderedlist>
      </section>
    </section>
    <section>
      <title>Synchronizing Something</title>
      <para>This section describes the steps required to synchronize two data providers. The example given illustrates how to synchronize two folders but the concepts are applicable to anything you wish to synchronize. If you need more information on specific settings please refer to the corresponding section of the documentation.   </para>
      <section>
        <title>Introduction</title>
        <para><xref linkend="conduit-FIG-dp-parts" /> contains two groups. This section will describe the steps to recreate those groups. </para>
        <itemizedlist>
          <listitem><para>The top group depicts a two way synchronization of two folders</para></listitem>
          <listitem><para>The bottom group depicts a one way sync of images, from F-Spot to Facebook, and to the Picasa web albums.</para></listitem>
        </itemizedlist>
      </section>
      <section>
        <title>Example 1: Synchronizing Two Folders</title>
        <para>The following steps will recreate the two way synchronization group shown as <emphasis>#1</emphasis> in the figure above. </para>
        <orderedlist numeration="arabic">
          <listitem><para>On your desktop create three folders named folder1, folder2, and folder3.  Drag a file of your choice into folder1.</para></listitem>
          <listitem><para>Start Conduit</para></listitem>
          <listitem>
            <para>Add a data provider for <emphasis>folder1</emphasis> </para>
            <para>From the data provider pane, drag the folder data provider and drop it on the left hand side of the canvas pane. This will be the data source that we are going to sync from.</para>
          </listitem>
          <listitem>
            <para>Configure <emphasis>folder1</emphasis> </para>
            <para>Double click on the data provider you recently dropped on the canvas. This will bring up the folder configuration window as shown below. Enter something memorable in the name field and change the <emphasis>Folder Location</emphasis> to the folder you created in step 1. 
              <figure id="conduit-FIG-dp-folder-config">
                <title>Configuring Folder 1</title>
                  <screenshot>
                    <mediaobject>
                      <imageobject>
                        <imagedata fileref="figures/conduit-folder-configuration.png" format="PNG"/>
                      </imageobject>
                  </mediaobject>
                </screenshot>
              </figure>
            </para>
          </listitem>
          <listitem>
            <para>Add a data provider for <emphasis>folder2</emphasis> </para>
            <para>Drag another folder data provider from the pane on the left. This time drop it adjacent to the folder1 dataprovider. This should result in an arrow connecting it to folder1 being created. </para>
          </listitem>
          <listitem>
            <para>Configure <emphasis>folder2</emphasis> </para>
            <para>Configure the data provider so that its <emphasis>Folder Location</emphasis> points to <emphasis>folder2</emphasis> on the desktop, and importantly, its <emphasis>Folder Name</emphasis> is the same as that entered in step <emphasis>#4</emphasis>.</para>
          </listitem>
          <listitem>
            <para>Configure the synchronization parameters</para>
            <para>Right click on the associated group, and under sync options, select a two way sync. Since this is just a basic run through on how to setup a sync we are not going to go through any advanced syncing options in this section of the documentation.   If you wish more information on the options available, please see <xref linkend="conduit-providers-and-groups" />.  </para>
          </listitem>
          <listitem><para>Synchronize the two folders by right clicking on them and selecting sync, or from the File menu. Once the sync is finished you should see the file that you placed in folder1 on your desktop within folder2.</para></listitem>
        </orderedlist>
      </section>
      <section>
        <title>Example 2: Exporting Images to Multiple Destinations</title>
        <para>The second group shown in <xref linkend="conduit-FIG-dp-parts" /> shows a single F-Spot data source exporting its photos to two data sinks, a Facebook one, and a Picasa one.</para>
        <orderedlist numeration="arabic">
          <listitem><para>Start Conduit</para></listitem>
          <listitem><para>Start F-Spot</para></listitem>
          <listitem><para>Drag a F-Spot data provider from the data provider pane and drop it onto an empty spot on the canvas. A new group containing just the F-Spot data provider will be created.</para></listitem>
          <listitem><para>Drag Facebook and Picasa data providers into the Group that was just created.</para></listitem>
          <listitem><para>Configure the data providers by double clicking on them.</para></listitem>
          <listitem><para>Now synchronize the group to upload photos. You will be prompted to log into Facebook using the Conduit login window, shown in  <xref linkend="conduit-FIG-login" />.</para></listitem>
        </orderedlist>
      </section>
      <section>
        <title>Summary</title>
        <para>All sync operations work exactly like this. The only difference is the data you are syncing and the providers you are using. You always follow the same sequence of steps, </para>
        <orderedlist numeration="arabic">
          <listitem><para>Add dataproviders to create a new group, or to an existing group.</para></listitem>
          <listitem><para>Configure the data providers. Each data provider requires a unique configuration. For reference on these please the <emphasis>Data Providers</emphasis> section of the documentation.</para></listitem>
          <listitem><para>Configure the group, selecting what should happen on conflict, etc.</para></listitem>
          <listitem><para>Synchronize the dataproviders as you wish.</para></listitem>
        </orderedlist>
      </section>
    </section>
      <section>
        <title>Network Synchronization</title>
        <para>If you have two computers at home, Conduit can be used to synchronize the data between them, directly, without first having to store the data somewhere else first. The steps below will illustrate how to synchronize Tomboy notes on two computers, called nzjrs-desktop and nzjrs-laptop. The following key will be used to help explain the setup procedure.</para>
        <para>
        <itemizedlist>
          <listitem><para><inlinegraphic format="PNG" fileref="figures/network-pc1.png"/> Image taken on the first computer.</para></listitem>
          <listitem><para><inlinegraphic format="PNG" fileref="figures/network-pc2.png"/> Image taken on the second computer.</para></listitem>
        </itemizedlist>
        </para>
        
        <tip>
          <title>Network Synchronization Tip</title>
          <para>The process below, although describing Tomboy note synchronization, could be suitably modified to synchronize all sorts of data between two computers, including Contacts, Calendar information, and even F-Spot photos.</para>
        </tip>
        <orderedlist numeration="arabic">
          <listitem><para>On the first computer create a synchronization group connecting Tomboy to the Network dataprovider, which is listed in the Miscellaneous category in the dataprovider pane. This makes Tomboy available for synchronization on the second computer.
          <figure id="conduit-FIG-network-sync-pc1">
            <title>Configuration of the First Computer</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/network-sync-pc1.png" format="PNG"/>
                  </imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          </para></listitem>
          <listitem><para>After a short delay, this will result in a new category being created on the second computer. The category will take the name of the first computer, nzjrs-desktop in my case, and it shall contain any dataproviders currently available for synchronization.</para></listitem>
          <listitem><para>Still on the second computer, drag the Tomboy dataprovider from the newly created category onto the canvas. Notice how its name is Remote Tomboy, indicating it refers to data on the remote, or first, computer.
          <figure id="conduit-FIG-network-sync-pc2">
            <title>Configuration of the Second Computer</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/network-sync-pc2.png" format="PNG"/>
                  </imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          </para></listitem>
          <listitem><para>Finally, on the second computer, start the sync in the normal manner.</para></listitem>
          <listitem><para>Your tomboy notes should now be synchronized between the two computers.</para></listitem>
        </orderedlist>
        <warning>
          <title>File Synchronization</title>
          <para>Due to performance and security reasons, we do not recommend using the network sync feature to synchronize large files between two computers. We hope to address this limitation in the future.</para>
        </warning>
      </section>
</article>

