Added doc of internal backup format.

2 files changed, 272 insertions, 2 deletions

diff --git a/kde2/doc/de/index.docbook.in b/kde2/doc/de/index.docbook.in
index 1befb34..78bb6c3 100644
--- a/kde2/doc/de/index.docbook.in
+++ b/kde2/doc/de/index.docbook.in
@@ -58,6 +58,7 @@ von Psion PDAs, sowie zum Formatieren von Lauferken derselben.
 <keyword>plptools</keyword>
 <keyword>KPsion</keyword>
 <keyword>Psion</keyword>
+<keyword>EPOC</keyword>
 <keyword>PDA</keyword>
 <keyword>Sicherung</keyword>
 <keyword>Rücksicherung</keyword>
@@ -532,7 +533,143 @@ modifizieren. Der Dialog Einstellungen besteht aus drei Seiten:
 <chapter id="Interna">
 <title>Internals</title>
 
-<para>TBD</para>
+<sect1 id="backupformat">
+<title>Die Backup-Dateien</title>
+
+<para>Bei den Backup-Dateien die von &kpsion; angelegt werden, handelt es
+sich um simple, mit gzip koprimierte tar-Archive.
+Die Dateien sind nach folgendem Schema benannt:
+<variablelist>
+<varlistentry>
+<term>TYP-YYYY-MO-DD-HH-MI-SS.tar.gz</term>
+<listitem><para>
+  wobei
+  <variablelist>
+  <varlistentry>
+  <term>TYP</term>
+  <listitem><para>
+    ein einzelnes Zeichen ist und den Backup-Typ repräsentiert. 'I' steht für
+    incrementell und 'F' steht für englisch 'full' (Komplett-Backup).
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>YYYY</term>
+  <listitem><para>
+    das Jahr des Backups angibt.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>MO</term>
+  <listitem><para>
+    den Monat des Backups angibt.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>DD</term>
+  <listitem><para>
+    den Tag des Backups angibt.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>HH</term>
+  <listitem><para>
+    die Stunde des Backups angibt.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>MI</term>
+  <listitem><para>
+    die Minute des Backups angibt.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SS</term>
+  <listitem><para>
+    Die Sekunde des Backups angibt.
+  </para></listitem>
+  </varlistentry>
+  </variablelist>
+</para></listitem>
+</varlistentry>
+</variablelist>
+Die Dateinamen innerhalb des tar-Archives sind konvertiert um den
+allgemein unter Unix gültigen Namens-Schemata zu genügen: Alle Vorkommen
+des Zeichens '%' sind in die Zeichenkette '%25' umgewandelt, alle Vorkommen
+des Zeichens '/' sind in die Zeichenkette '%2f' umgewandelt und alle
+Vorkommen von '\' sind nach '/' gewandelt.
+</para>
+<para>
+Zusätzlich zu den gesicherten Dateien des Psion, enthält jedes tar-Archiv
+eine spezielle Indexdatei, in der die original-Dateiattribute und die
+64-bit Dateizeit des Psion gespeichert werden. Diese Indexdatei hat den
+Namen KPsionIncrementalIndex (für incrementelle Backups) oder
+KPsionFullIndex (für Komplett-Backups). Die Indexdatei befindet sich im
+Wurzelverzeichnis des Archivs und ist eine ASCII-Datei mit folgendem
+Aufbau:
+<variablelist>
+<varlistentry>
+<term>hhhhhhhh llllllll ssssssss aaaaaaaa fn</term>
+<listitem><para>
+  wobei
+  <variablelist>
+  <varlistentry>
+  <term>hhhhhhhh</term>
+  <listitem><para>
+    eine 8-stellige Hexadezimalzahl ist, die die obere Hälfte des
+    Datei-Modifikationsdatums enthält.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>llllllll</term>
+  <listitem><para>
+    eine 8-stellige Hexadezimalzahl ist, die die untere Hälfte des
+    Datei-Modifikationsdatums enthält.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>ssssssss</term>
+  <listitem><para>
+    eine 8-stellige Hexadezimalzahl ist, die die Dateigrösse enthält.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>aaaaaaaa</term>
+  <listitem><para>
+    eine 8-stellige Hexadezimalzahl ist, die die Dateiattribute enthält.
+  </para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>fn</term>
+  <listitem><para>
+    der unkonvertierte Original-Dateiname ist (Absoluter Pfad).
+  </para></listitem>
+  </varlistentry>
+  </variablelist>
+</para></listitem>
+</varlistentry>
+</variablelist>
+Die erste Zeile der Indexdatei enthält einen Header mit dem folgenden
+Format:
+<variablelist>
+<varlistentry>
+<term>#plpbackup index T</term>
+<listitem><para>
+  wobei
+  <variablelist>
+  <varlistentry>
+  <term>T</term>
+  <listitem><para>
+    ein einzelnes Zeichen ist, welches den Backup-Typ repräsentiert.
+    'I' steht für incrementell und 'F' steht für englisch 'full'
+    (Komplett-Backup).
+  </para></listitem>
+  </varlistentry>
+  </variablelist>
+</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+</sect1>
 </chapter>
 
 <chapter id="faq">
diff --git a/kde2/doc/en/index.docbook.in b/kde2/doc/en/index.docbook.in
index c7cb68a..10412df 100644
--- a/kde2/doc/en/index.docbook.in
+++ b/kde2/doc/en/index.docbook.in
@@ -58,6 +58,7 @@ handling backup, restore and formatting of Psion PDAs.
 <keyword>plptools</keyword>
 <keyword>KPsion</keyword>
 <keyword>Psion</keyword>
+<keyword>EPOC</keyword>
 <keyword>PDA</keyword>
 <keyword>backup</keyword>
 <keyword>restore</keyword>
@@ -520,7 +521,139 @@ consists of three tabs:
 <chapter id="Internals">
 <title>Internals</title>
 
-<para>TBD</para>
+<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">