<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kpsion  "<application>KPsion</application>">
  <!ENTITY kappname "&kpsion;">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % German "INCLUDE">
  <!-- DO NOT DELETE! $Revision$ -->
  <!-- DO NOT DELETE! $Date$ -->
]>

<book lang="&language;">
<bookinfo>

<title>The &kpsion; handbook</title>

<authorgroup>
<author>
<firstname>Fritz</firstname>
<surname>Elfert</surname>
<affiliation>
<address><email>felfert@to.com</email></address>
</affiliation>
</author>

<!--
<othercredit role="reviewer">
<firstname>Whoever</firstname>
<surname>Lastname</surname>
<affiliation>
<address><email>mail@somewhere.org</email></address>
</affiliation>
<contrib>Reviewer</contrib>
</othercredit>
-->

</authorgroup>

<copyright>
<year>2001</year>
<holder>Fritz Elfert</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>__DATE__</date>
<releaseinfo>__VERSION__</releaseinfo>


<abstract><para>
&kpsion; is an application for
handling backup, restore and formatting of Psion PDAs.
</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>plptools</keyword>
<keyword>KPsion</keyword>
<keyword>Psion</keyword>
<keyword>EPOC</keyword>
<keyword>PDA</keyword>
<keyword>backup</keyword>
<keyword>restore</keyword>
<keyword>format</keyword>
</keywordset>

</bookinfo>

<chapter id="Introduction">
<title>Introduction</title>

<para>Welcome to &kpsion;! &kpsion; is an application
handling backup, restore and formatting of Psion PDAs
for the K Desktop Environment. It uses the daemon <command>ncpd</command>
and the libraries from the plptools package.
</para>

<para>This program is meant to be started from the command line or from
<filename>.desktop</filename> files.
</para>

</chapter>

<chapter id="installation">
<title>Installation</title>

<sect1 id="downloading">
<title>Downloading</title>

<para>&kpsion; is part of the plptools package. The plptools package is
available at <ulink url="http://plptools.sourceforge.net/">http://plptools.sourceforge.net/</ulink>.</para>

</sect1>

<sect1 id="compiling">
<title>Compiling</title>

<para>The plptools package is not focussed on KDE application. Therefore, to
enable the build of KDE related stuff (&kpsion; is part of that) you have to
use the option <option>--enable-kde</option> when running plptools configure.</para>

<para>The build process usual works like this:</para>

<screen>
<prompt>$</prompt> <command>./configure <option>--enable-kde</option></command>
<prompt>$</prompt> <command>make</command>
<prompt>$</prompt> <command>make <option>install</option></command>
</screen>

<para>You will have to execute the last step as root. The installation process
needs to be able to write to the system wide KDE directories.</para>

</sect1>
</chapter>

<chapter id="using-kpsion">
<title>Using &kpsion;</title>

<para>
Usage of &kpsion; is easy. Normally, you start &kpsion; using the menu entry
in the Utilities section of the K-Menu.

You also can start kpsion from the shell. The syntax is one of the following:
</para>

    <cmdsynopsis>
      <command>kpsion</command>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>kpsion</command>
      <arg>--autobackup</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>kpsion</command>
      <arg>--backup <replaceable>DRIVE</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>kpsion</command>
      <arg>--restore <replaceable>DRIVE</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>kpsion</command>
      <arg>--format <replaceable>DRIVE</replaceable></arg>
    </cmdsynopsis>

<para>If started without any options, &kpsion; starts up in interactive
mode. If started with any of the above options, &kpsion; performs the
given task non interactively.</para>

<variablelist>
<varlistentry>
<term><option>--autobackup</option></term>
<listitem><para>
This specifies to run a scheduled backup of the connected
Psion. If no psion is connected, nothing happens.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--backup <replaceable>DRIVE</replaceable></option></term>
<listitem><para>
This option starts backup of the specified <replaceable>DRIVE</replaceable>.
<replaceable>DRIVE</replaceable> is a single drive letter.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--restore <replaceable>DRIVE</replaceable></option></term>
<listitem><para>
This option starts restore of the specified <replaceable>DRIVE</replaceable>.
<replaceable>DRIVE</replaceable> is a single drive letter.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--format <replaceable>DRIVE</replaceable></option></term>
<listitem><para>
This option starts format of the specified <replaceable>DRIVE</replaceable>.
<replaceable>DRIVE</replaceable> is a single drive letter.
</para></listitem>
</varlistentry>

</variablelist>

</chapter>

<chapter id="commands">
<title>Command reference</title>

<sect1 id="kpsion-mainwindow">
<title>The main &kpsion; window</title>
<para>
<screenshot>
<screeninfo>&kpsion; mainwindow.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="toplevel.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>&kpsion; mainwindow</phrase>
    </textobject>
  </mediaobject>
</screenshot>
When a Psion PDA is connected, the main window shows its drives in the
central icon view. By clicking on a drive-icon, you can toggle its selection.
If any drive is selected, the entries in the File menu and the toolbar buttons
are enabled. The most common <guimenu>actions</guimenu> are accessible via
toolbar buttons. These are:</para>
<para>
<itemizedlist>
<listitem><para>
<guiicon>
  <inlinemediaobject>
    <imageobject>
      <imagedata fileref="psion_backup.png" format="PNG"></imagedata>
    </imageobject>
  </inlinemediaobject>
</guiicon> Full backup.
</para></listitem>
<listitem><para>
<guiicon>
  <inlinemediaobject>
    <imageobject>
      <imagedata fileref="psion_restore.png" format="PNG"></imagedata>
    </imageobject>
  </inlinemediaobject>
</guiicon> Restore.
</para></listitem>
</itemizedlist>
</para>

<sect2><title>The File Menu</title><para><variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Start Full Backup</guimenuitem>
</menuchoice></term>
<listitem><para>
Starts a <action>full backup</action> of selected drives.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>i</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Start Incremental Backup</guimenuitem>
</menuchoice></term>
<listitem><para>
Starts an <action>incremental backup</action> of selected drives.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>r</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Start Restore</guimenuitem>
</menuchoice></term>
<listitem><para>
Starts <action>restore</action> of selected drives.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Start Format</guimenuitem>
</menuchoice></term>
<listitem><para>
Starts <action>formatting</action> of selected drives.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para>
<action>Quits</action> &kpsion;.
</para></listitem>
</varlistentry>

</variablelist></para></sect2>

</sect1>

</chapter>

<chapter id="Configuration">
<title>Configuration</title>

<sect1 id="firsttime">
<title>First time startup</title>

<para>
When you start &kpsion; the first time, a wizard dialog is shown which lets
you easily configure the application for your personal use. The initial setup
is divided into three steps:
</para>

<sect2>
<title>Select a backup directory</title>
<para>
<screenshot>
<screeninfo>Step one. Select a backup directory.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="firstwizard-1.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>Selecting the backup directory</phrase>
    </textobject>
  </mediaobject>
</screenshot>
The backup directory will be used by &kpsion; for storing backup archives.
You simply can accept the default proposed by this dialog if you don't have
to care about disk space used in your home directory. Otherwise, select a
directory of your choice by clicking on the Browse button. &kpsion; creates
a that directory if it does not yet exist. Of course, you need the permission
to do so.
</para>
<para></para>
</sect2>

<sect2>
<title>Adjust the backup strategy</title>
<para>
<screenshot>
<screeninfo>Step two. backup strategy.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="firstwizard-2.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>Setting the backup strategy</phrase>
    </textobject>
  </mediaobject>
</screenshot>
In the second step, you can adjust the backup strategy. For both, incremental
and full backups, you can select an interval. If any of these intervals is
enabled, &kpsion; will create a <filename>.desktop</filename> Entry in your
KDE Autostart folder. Every time KDE is started, this will start &kpsion;
in autobackup mode. If the interval is expired and your Psion is currently
connected, an unattended backup will be performed.
</para>
<para>
The third adjustment to be made is the number of backup generations to keep.
A backup generation consists of a full backup plus eventually made incremental
backups. If a backup is completed sucessfully, &kpsion; will check, if there
are more backup generations available and delete older backup generations.
</para>
<para></para>
</sect2>

<sect2>
<title>Connection parameters</title>
<para>
<screenshot>
<screeninfo>Step three. connection parameters.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="firstwizard-3.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>Setting connection parameters</phrase>
    </textobject>
  </mediaobject>
</screenshot>
In the third step, you can adjust the behavior of &kpsion; during initial
connect. If you set the connection retry interval to a non-zero value, &kpsion;
will retry a connection attempt if it had failed. Since &kpsion; needs the
ncpd daemon running, it is also possible to start this daemon on the fly if it
is not running. For this, you need to have permissions to use the specified
port. 
</para>
<para></para>
</sect2>

</sect1>

<sect1 id="newpsion">
<title>New Psion connection</title>

<para>
When &kpsion; connects to a Psion, it retrieves the PDA's unique machine ID and
verifies, if this PDA has been connected before. If the connected Psion has never
been connected to &kpsion; before, a wizard dialog is shown which lets
you assign a name for that Psion and specify a set of drives which should be
backed up when running in unattended backup mode.
</para>

<sect2>
<title>Psion Name</title>
<para>
<screenshot>
<screeninfo>Step one. psion name.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="newpsionwizard-1.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>Setting a psion name</phrase>
    </textobject>
  </mediaobject>
</screenshot>
The name of the new Psion is not used by &kpsion; internally but is used for
displaying the machine's name when connected.
</para>
<para></para>
</sect2>

<sect2>
<title>Specifying backup drives</title>
<para>
<screenshot>
<screeninfo>Step two. specifying backup drives.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="newpsionwizard-2.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>Specifying backup drives</phrase>
    </textobject>
  </mediaobject>
</screenshot>
Usually, you should select all drives except the ROM drive. The ROM drive
can be backed up, but - of course - can not be restored.
</para>
<para></para>
</sect2>
</sect1>

<sect1 id="settings">
<title>Settings</title>

<para>
All settings, configured using the First time wizard and New Psion wizard
can be changed at any time using the Settings dialog. The Settings dialog
consists of three tabs:
</para>

<sect2>
<title>Backup</title>
<para>
<screenshot>
<screeninfo>Setup, Backup.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="settings-backup.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>Settings, Backup</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para></para>
</sect2>

<sect2>
<title>Connection</title>
<para>
<screenshot>
<screeninfo>Settings, Connection.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="settings-connection.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>Settings, Connection</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para></para>
</sect2>

<sect2>
<title>Machines</title>
<para>
<screenshot>
<screeninfo>Settings, Machines.</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="settings-machines.png" format="PNG"></imagedata>
    </imageobject>
    <textobject>
      <phrase>Settings, Machines</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para></para>
</sect2>

</sect1>

</chapter>

<chapter id="Internals">
<title>Internals</title>

<sect1 id="backupformat">
<title>The backup files</title>

<para>The backup files, created by &kpsion; are simply gzipped tar files.
The files follow the following naming scheme:
<variablelist>
<varlistentry>
<term>TYPE-YYYY-MO-DD-HH-MI-SS.tar.gz</term>
<listitem><para>
  where
  <variablelist>
  <varlistentry>
  <term>TYPE</term>
  <listitem><para>
    is a single character, representing the backup type. 'I' stands for
    incremental and 'F' stands for full.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>YYYY</term>
  <listitem><para>
    is the year of creation.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>MO</term>
  <listitem><para>
    is the month of creation.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>DD</term>
  <listitem><para>
    is the day of creation.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>HH</term>
  <listitem><para>
    is the hour of creation.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>MI</term>
  <listitem><para>
    is the minute of creation.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>SS</term>
  <listitem><para>
    is the second of creation.
  </para></listitem>
  </varlistentry>
  </variablelist>
</para></listitem>
</varlistentry>
</variablelist>
The file names in the tar archives are converted to fit into general
naming scheme. All occurences of the character '%' are changed into the
string '%25', all ocurrences of '/' are changed into '%2f' and all
occurences of '\' are changed into '/'.
</para>
<para>
In addition to the data files on the psion, every archive contains a
special index file, where the original file attributes and the Psion's
64-bit hires filetime is stored. This file is named KPsionIncrementalIndex
for incremental backups or KPsionFullIndex for full backups. The index
file is stored in the archive's toplevel directory and is an ASCII file,
containing one line per data file with the following fields:
<variablelist>
<varlistentry>
<term>hhhhhhhh llllllll ssssssss aaaaaaaa fn</term>
<listitem><para>
  where
  <variablelist>
  <varlistentry>
  <term>hhhhhhhh</term>
  <listitem><para>
    is an 8-digit hexadecimal number, representing the upper half of the
    file's modification time.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>llllllll</term>
  <listitem><para>
    is an 8-digit hexadecimal number, representing the lower half of the
    file's modification time.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>ssssssss</term>
  <listitem><para>
    is an 8-digit hexadecimal number, representing the size of the file.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>aaaaaaaa</term>
  <listitem><para>
    is an 8-digit hexadecimal number, representing the native attributes of
    the file.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term>fn</term>
  <listitem><para>
    is the unconverted original absolute file name.
  </para></listitem>
  </varlistentry>
  </variablelist>
</para></listitem>
</varlistentry>
</variablelist>
The first line of the index file contains a header of the following format:
<variablelist>
<varlistentry>
<term>#plpbackup index T</term>
<listitem><para>
  where
  <variablelist>
  <varlistentry>
  <term>T</term>
  <listitem><para>
    is a single character, representing the backup type. 'I' stands for
    incremental and 'F' stands for full.
  </para></listitem>
  </varlistentry>
  </variablelist>
</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
 
<qandaset id="faqlist">
<qandaentry>
<question>
<para>I have a Psion Series 3 and &kpsion; doesn't work.</para>
</question>
<answer>
<para>This is currently a known problem with the plptools lib. You have to
wait until tis is fixed. Sorry.
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>

<chapter id="Author">
<title>Author</title>

<para>Copyright 2001 Fritz Elfert</para>

<para>&kpsion; is written by Fritz Elfert.</para>

<para>The author can be reached through email at
<email>felfert@to.com</email>.  Please report any bugs you find to me so
that I can fix them. If you have a suggestion, feel free to contact me.</para>

&underFDL;
&underGPL;

</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
sgml-set-face: t
End:
-->