<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!-- Define an entity for your application if it is not part of KDE
       CVS -->
  <!ENTITY kbackup "<application>KBackup</application>">
  <!ENTITY kappname "&kbackup;"><!-- replace kmyapplication here
                                            do *not* replace kappname-->
  <!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc.  Leave
                                     this unchanged if your
                                     application is not maintained in KDE CVS -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"> <!-- ONLY If you are writing non-English
                                     original documentation, change
                                     the language here -->

  <!-- Do not define any other entities; instead, use the entities
       from entities/general.entities and $LANG/user.entities. -->
]>

<!-- ................................................................ -->

<!-- The language must NOT be changed here. -->
<!-- If you are writing original documentation in a language other -->
<!-- than English, change the language above ONLY, not here -->
<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The &kbackup; Handbook (for version 0.7)</title>

<authorgroup>
<author>
<!-- This is just put in as an example.  For real documentation, please
     define a general entity in entities/contributor.entities, e.g.
<!ENTITY George.N.Ugnacious "<personname><firstname>George</firstname><othername>N.</othername><surname>Ugnacious</surname></personname>">
<!ENTITY George.N.Ugnacious.mail "<email>gnu@kde.org</email>">
and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.
 -->
<personname>
<firstname>Martin</firstname>
<surname>Koller</surname>
</personname>
<email>kollix@aon.at</email>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2006 - 2010</year>
<holder>Martin Koller</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<date>2009-06-14</date>
<releaseinfo>1.06.00</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kbackup; is an application which lets you back up your data in a simple, user friendly way.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>system</keyword>
<keyword>KBackup</keyword>
<keyword>backup</keyword>
<keyword>storage</keyword>
<keyword>archive</keyword>
<keyword>zip</keyword>
<keyword>gzip</keyword>
<keyword>bzip2</keyword>
</keywordset>

</bookinfo>

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

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<para>
&kbackup; is a program that lets you back up any directories or files,
whereby it uses an easy to use directory tree to select the things to back up.
It lets you save your settings in so called "profile" files, where a profile is a simple
textfile containing definitions for directories and files to be included
or excluded from the backup process.
Also, it lets you define where the backup shall be saved to.
The target can be either a local directory (e.g. a local mounted device
like a ZIP drive, USB stick, etc.) but it can also be any remote URL
(e.g. smb://remote/some_path) to back up your data to some central server, etc.
</para>

<para>
The program can also run an automated backup without using a graphical user interface.
One can simply create a profile and use this settings to tell &kbackup; what to do
when run in non-interactive mode, e.g. by starting it from a cron job.
</para>

<para>
The program was designed to be very simple in its use so that it can be used
by non-computer experts.
</para>

<para>
The storage format is the well known TAR format, whereby the data can still be stored
in compressed format (bzip2 or gzip).
</para>

<para>
The current implementation features only the backup step. To restore data back into
your system, you currently have to use e.g. konqueror to open the TAR backup files
and drag/drop the files back to your file system.
This is also an advantage of the usage of the well known and well supported TAR file
format.
</para>
<para>
If the files are compressed, you can uncompress all files
from the current directory recursively down with the following command:
</para>
<para>
find . -name \*bz2 -print0 | xargs -0 bunzip2
</para>

</chapter>

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

<para>
All you need to do is to select which directories you want to store.
This is done by selecting all the directories in the treeview on the left side
of the main window.
</para>

<para>
If you select a directory, &kbackup; will automatically store all files and
subdirectories below it.
If you want to exclude parts of a selected directory, simply deselect that files/directories
inside the still selected directory.
</para>

<para>
In general this means: A selected directory will store everything in it and below it,
except the deselected parts in it.
This also means, whenever you reuse a profile (see below) later on and new files
have been added to a directory already selected for backup, all the new files will
also be stored.
</para>

<para>

<screenshot>
<screeninfo>Here's a screenshot of &kbackup;</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="mainwindow.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Screenshot of Main Window</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>


<sect1 id="kbackup-profiles">
<title>Using profiles</title>

<para>
To keep a selection for later use, simply save it into a &kbackup; Profile file.
Use the File Menu and select "Save profile".
</para>

<para>
To reload a selection into &kbackup;, use the File Menu "Load Profile".
</para>

<para>
&kbackup; saves in a profile the selections for all included directories/files,
excluded directories/files, the target directory/URL, defined archive prefix,
the defined maximum slice file size, etc.
</para>

<para>
If you want to ease the usage of backing up every day the same set of
files, simply store your settings into a &kbackup; profile (a .kbp file)
and pass that file on the commandline.
</para>

<para>
E.g.:
</para>

<para>
kbackup myData.kbp
</para>

<para>
Hint: you can also create a shortcut on your desktop to a .kbp file
as the file type is registered to start &kbackup; on double click
</para>

</sect1>

<sect1 id="archive-slices">
<title>Archive slices</title>
<para>
As a medium has normally limited capacity (e.g. 100MB ZIP disc),
&kbackup; will create several archive slices.
</para>
<para>
Each archive slice will get its own name, which looks like this:
</para>
<para>
backup_2006.08.26-13.04.44_1.tar
</para>
<para>
The name contains the creation date and time (which will be the same for all
slices of one backup) and a trailing slice sequence number (_1 in this example).
</para>
<para>
In the menu File/Profile Settings you can define a different archive prefix than the
default "backup".
</para>

<para>
In the Profile Settings Dialog you can also define a maximum archive slice size,
which limits the slice size even if there would be more space left on the target
device.
This helps to create archive slices which can then be later burned on a CD/DVD, etc.
If you explicitely limit the size of an archive slice, the available size
will be marked with (*) in the mainwindow.
</para>
<para>
But even if you define a slice to be of "unlimited" size, there are other constraints
which limit the size of a slice:
<itemizedlist>
<listitem><para>limited by the target directory (when stored directly into a local dir)</para></listitem>
<listitem><para>limited by the "tmp" dir when we create a tmp file for later upload to a remote URL</para></listitem>
</itemizedlist>
</para>

<para>
In the Profile Settings, you can also define a maximum number of backups being kept
in the target directory, and therefore automatically deleting all older backups there.
E.g. if you set it to 3, &kbackup; will keep the last 3 backups and delete all older ones.
</para>

</sect1>


<sect1 id="incremental-backup">
<title>Incremental Backup</title>
<para>
With an incremental backup not all files will be saved every time the backup runs, but only
the files which have changed since the last backup. This has the great advantage that the
incremental backup will usually include much less files than a full backup and therefore
will be finished in a much shorter time.
</para>
<para>
This works as follows: In the profile you define an interval (in days) for the full backup.
E.g. when you define 5 days, then &kbackup; will do a full backup of all files every 5 days.
Whenever you start &kbackup; before the interval expires with this profile - regardless
how often you run a backup - only the files which have changed since the last backup will
be saved. &kbackup; stores the timestamp of the last backup into the profile and knows
therefore what to do when run the next time.
</para>
<para>
The archive slice files created during an incremental backup will contain the text "_inc", e.g.:
</para>
<para>
backup_2010.06.14-18.50.26_1_inc.tar
</para>
<para>
Full backup slice files will not include "_inc" in the name, e.g.:
</para>
<para>
backup_2010.06.13-20.58.14_1.tar
</para>
<para>
When one wants to restore files from an incremental backup, it's important to look for
the most recent version of a file to be restored in all "_inc" files and finally also the last full backup
slice file.
This exactly is also the disadvantage of the incremental backup (but no advantage without disadvantage ;-) )
</para>
<para>
If you want to do a full backup earlier than the defined incremental cycle time defined in a profile,
you can do so by checking the "Force Full Backup" option in the user interface.
When &kbackup; is started via the command line, this can be achieved by using the option --forceFull
</para>
<para>
A forced full backup will restart the backup cycle, e.g. &kbackup; counts the days to the next full backup
from the time of the last full backup.
</para>
</sect1>


<sect1 id="archive-compression">
<title>Archive Compression</title>
<para>
&kbackup; will compress the files stored if you activate this
in the profile settings. Depending on
the availability on your system it chooses bzip2 or gzip compression.
&kbackup; will compress every single file
and store all files with an added file extension (.bzip2 or .gz) into the
then not-compressed .tar archive.
</para>

<para>
When you have selected to create the backup on some local filesystem
(e.g. your extra disc, ZIP drive, etc.) - which means you did not
enter a remote target URL - &kbackup; might split the whole backup into several archive slices
due to media capacity limitations.
</para>
<para>
e.g.:
</para>
<para>
backup_2006.08.26-13.04.44_1.tar
</para>
<para>
backup_2006.08.26-13.04.44_2.tar
</para>

</sect1>

<sect1 id="automating">
<title>Automating Backup</title>

<para>
If you want to automate the process of the backup, &kbackup; offers different
commandline options to help with this:
<itemizedlist>
<listitem><para>--auto</para>
<para>
When you run &kbackup; with this option and a given .kbp profile, it will
start, load the given profile, run the backup and terminate when done.
All this is done with a visible &kbackup; user interface.
</para>
</listitem>

<listitem><para>--autobg</para>
<para>
When you run &kbackup; with this option and a given .kbp profile, it will
run the same process as with --auto  but _without_ showing any graphical user interface.
Therefore the suffix "bg" which stands for "background" - everything is done in the background
so this is the right option to be used when you do your backups e.g. started by a cron job.
</para>
<para>
When using --autobg the output from &kbackup; - showing the progress of the backup - is written
to stderr. By default the output includes just a few important messages and a summary at the end.
If you pass --verbose in addition, then you will also see each filename currently being backed up.
</para>
</listitem>
</itemizedlist>
</para>

</sect1>

</chapter>

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

<!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
application windows and their menubar and toolbar commands for easy reference.
Also include any keys that have a special function but have no equivalent in the
menus or toolbars. This may not be necessary for small apps or apps with no tool
or menu bars. -->

<sect1 id="kapp-mainwindow">
<title>The main &kbackup; window</title>

<para>
</para>

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

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Open Recent</guimenuitem>
</menuchoice></term>
<listitem><para><action>Shows a submenu with the recently used profiles for easy selection
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>New Profile</guimenuitem>
</menuchoice></term>
<listitem><para><action>Clears the selection and the target input field, to be able to define
a new profile.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Load Profile</guimenuitem>
</menuchoice></term>
<listitem><para><action>Loads a profile</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save Profile</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves all settings into the currently loaded profile</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save Profile As...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves all settings into a profile with a new name</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Profile Settings</guimenuitem>
</menuchoice></term>
<listitem><para><action>In the settings, you can define whether the archive-slice files
start with the default name "backup" or with an alternative name.
Also you can limit the archive slice size. See chapter "Archive Slices".
These settings are also stored into the profile.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Ctrl+Q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> &kbackup;</para></listitem>
</varlistentry>

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

<sect2>
<title>The <guimenu>Settings</guimenu> Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Dock in System Tray</guimenuitem>
</menuchoice></term>
<listitem><para><action>
When this option is activated, an icon is shown in the system tray, which reflects the current
status of a backup operation. An animation is shown when a backup is in progress, else you see
a static icon.
If this option is selected, the closing of the mainwindow will not terminate &kbackup;.
The application must be explicitely terminated by selecting the "Quit" action.
Via the context menu of the &kbackup; system tray icon you can start and cancel a backup operation -
which is the same as you can do in the mainwindow.
The tooltip on this icon also gives progress information (Number of saved files, size of the backup and
the last saved file).
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Enable All Messages</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Activating this entry clears all internally stored "Do not ask again" flags for
the dialogs shown in &kbackup;
</action></para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>


<sect2>
<title>The <guimenu>Help</guimenu> Menu</title>

<!-- Assuming you have a standard help menu (help, what's this, about -->
<!-- &kbackup;, about KDE) then the documentation is already written. -->
<!-- The following entity is valid anywhere that a variablelist is -->
<!-- valid.  -->

&help.menu.documentation;

</sect2>

</sect1>
</chapter>

<chapter id="developers">
<title>Developer's Guide to &kbackup;</title>

<!-- (OPTIONAL) A Programming/Scripting reference chapter should be
used for apps that use plugins or that provide their own scripting hooks
and/or development libraries. -->

<para>
&kbackup; can be extended by using a shellscript (or any other executable)
which will be started at three different points during the backup process.
The idea behind it is to allow to mount, unmount, eject media in a system
specific way, or do other things with the produced archive files.
</para>

<para>
The script to execute must be given with the --script commandline option.
</para>

<para>Here is a sample script</para>

<example><title>sliceScript.sh</title>
<programlisting>
#!/bin/sh

mode=$1
archive=$2
target=$3
mountPoint=$4

case "$mode" in
 "slice_init" )
    if [ "$mountPoint" != "" ]
    then
      mount /media/zip
      rm -f /media/zip/backup_2*.tar*
    fi
 ;;

 "slice_closed" )
 ;;

 "slice_finished" )
    if [ "$mountPoint" != "" ]
    then
      umount /media/zip
      eject /media/zip
    fi
 ;;
esac
</programlisting>
</example>

<para>
The script is always invoked with four commandline argument:
</para>
<itemizedlist>
<listitem><para>invocation mode</para> </listitem>
<listitem><para>archive (slice) file name</para> </listitem>
<listitem><para>target directory/URL</para> </listitem>
<listitem><para>mountpoint of the target directory if it's a local dir, else an empty string</para> </listitem>
</itemizedlist>

<para>
There are three possible invocation modes:
</para>

<para>
<itemizedlist>

<listitem><para>slice_init</para>
<para>called before a new archive slice is being created on disc</para>
 </listitem>

<listitem><para>slice_closed</para>
<para>called after an archive slice has been created, but before it has been put into
the target directory</para>
<para>
This can be used if you want to copy the archive slice to some additional place, e.g.
the archive is sent to the main server (via a target URL), but you want to keep the last
backup also onto the local disc.
</para>
</listitem>

<listitem><para>slice_finished</para>
<para>called after an archive slice has been successfully transferred into the
target directory</para>
</listitem>

</itemizedlist>
</para>

</chapter>

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

<!-- (OPTIONAL but recommended) This chapter should include all of the silly
(and not-so-silly) newbie questions that fill up your mailbox. This chapter
should be reserved for BRIEF questions and answers! If one question uses more
than a page or so then it should probably be part of the
"Using this Application" chapter instead. You should use links to
cross-reference questions to the parts of your documentation that answer them.
This is also a great place to provide pointers to other FAQ's if your users
must do some complicated configuration on other programs in order for your
application work. -->

&reporting.bugs;
&updating.documentation;

</chapter>

<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>

<para>
&kbackup;
</para>
<para>
Program copyright &copy; 2006 - 2009 Martin Koller <email>kollix@aon.at</email>
</para>

<para>
Documentation Copyright &copy; 2006 - 2009 Martin Koller
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->

<!-- Determine which license your application is licensed under,
     and delete all the remaining licenses below:

     (NOTE:  All documentation are licensed under the FDL,
     regardless of what license the application uses) -->

&underGPL;        	 <!-- GPL License -->

</chapter>

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


<sect1 id="getting-kapp">
<title>How to obtain &kbackup;</title>

<!-- This first entity contains boiler plate for applications that are
part of KDE CVS.  You should remove it if you are releasing your
application -->

<para>
You can download &kbackup; from www.kde-apps.org
</para>
</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<!-- This entity contains the boilerplate text for standard -->
<!-- compilation instructions.  If your application requires any -->
<!-- special handling, remove it, and replace with your own text. -->

&install.compile.documentation;

</sect1>

</appendix>

&documentation.index;
</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
-->