<?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 legal SYSTEM "legal.xml">
<!ENTITY appname "Back In Time">
<!ENTITY app "<application>&appname;</application>">
<!ENTITY appversion "0.9.26">
<!ENTITY manrevision "0.9.26">
<!ENTITY date "November 2008">
]>
<!--
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://live.gnome.org/DocumentationProject
  Template version: 3.0 beta
  Template last modified 2006-11-21

-->
<!-- =============Document Header ============================= -->
<article id="index" lang="C">
  <articleinfo> 
    <title>&app; Manual</title>
    <abstract role="description">
      <para>&app; is a simple backup tool for KDE4 desktop.</para>
    </abstract>         

    <copyright> 
      <year>2008-2009</year> 
      <holder>Oprea Dan</holder> 
    </copyright> 

    <!-- An address can be added to the publisher information. -->
	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="legal.xml"/>
    <!-- The file legal.xml contains link to license for the documentation, 
        and other legal stuff such as "NO WARRANTY" statement. 
        Please do not change any of this. -->

<!-- According to GNU FDL, revision history is mandatory if you are -->
<!-- modifying/reusing someone else's document.  If not, you can omit it. -->
<!-- Remember to remove the &manrevision; entity from the revision entries other
-->
<!-- than the current revision. -->
<!-- The revision numbering system for GNOME manuals is as follows: -->
<!-- * the revision number consists of two components -->
<!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
<!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
<!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
<!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
<!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
<!-- to V3.0, and so on. -->  

    <releaseinfo>This manual describes version &appversion; of Back In Time.
    </releaseinfo> 
    <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the &app; application or
      this manual, send an email to:  
      <ulink url="mailto:dan@le-web.org" type="mailto">dan@le-web.org</ulink>. 
      </para>
<!-- Translators may also add here feedback address for translations -->
    </legalnotice> 
  </articleinfo> 

<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->
<!-- Use the Introduction section to give a brief overview of what
     the application is and what it does. -->
  <sect1 id="backintime-introduction"> 
    <title>Introduction</title> 
    <para>&app; is a simple backup tool for Linux (this is KDE4 version). The backup is done by taking snapshots of 
	a specified set of folders.</para> 
	<para>All you have to do is:</para>
    <itemizedlist> 
      <listitem><para>configure where to save snapshots</para></listitem>
      <listitem><para>cofigure what folders to backup</para></listitem>
      <listitem><para>schedule automatic backup: disabled, every 5 minutes, every 10 minutes, every hour, every day, every week, every month</para></listitem>
    </itemizedlist> 
	<para>&app; acts as a "user mode" backup tool. This means that you can backup/restore only folders 
	you have write access to (actually you can backup read-only folders, but you can't restore them).</para>
	<para>If you want to run it as root you need to use "su" (command line), "gksu" (Gnome) or "kdesudo" (KDE).</para>
	<para>A new snapshot is created only if something changed since the last snapshot (if any).</para>
	<para>A snapshot contains all the files from the selected folders (except for exclude patterns).
	In order to reduce disk space it use hard-links (if possible) between snapshots for unchanged files.
	This way a file of 10Mb, unchanged for 10 snapshots, will use only 10Mb on the disk.</para>
	<para>When you restore a file 'A', if it already exists on the file system it will be renamed to 
	'A.backup.currentdate'.</para>
  </sect1>

<!-- =========== Getting Started ============================== -->
<!-- Use the Getting Started section to describe the steps required
     to start the application and to describe the user interface components
     of the application. If there is other information that it is important
     for readers to know before they start using the application, you should
     also include this information here. 
     If the information about how to get started is very short, you can 
     include it in the Introduction and omit this section. -->

  <sect1 id="backintime-getting-started"> 
    <title>Getting Started</title> 
    <para>You can start &app; in the following ways:</para> 
    <variablelist>
    	<varlistentry>
    		<term><guimenu>Applications</guimenu> menu</term>
    		<listitem>
    		<para>Choose 
    		<menuchoice>
    		<guisubmenu>System</guisubmenu>
    		<guimenuitem>Back In Time</guimenuitem>
    		</menuchoice>. </para>
    		</listitem>
    	</varlistentry>
    	<varlistentry>
    		<term>Command line</term>
    		<listitem>
    		<para>To start &app; from a command line, type the following command, then 
			press <keycap>Return</keycap>:</para>
    		<para><command>backintime [--gnome | --kde4] [ [--snapshots] path | --backup | --backup-job | 
			--snapshots-list | --snapshots-list-path | --last-snapshot | --last-snapshot-path |
			--help | --version | --license]</command></para> 
			<itemizedlist>
				<listitem>
    				<para>--gnome - use GNOME GUI (if installed)</para>
				</listitem>
				<listitem>
    				<para>--KDE4 - use KDE4 GUI (if installed)</para>
				</listitem>
				<listitem>
    				<para>path - go directly to the specified file or folder. 
					If the application is already running if pass the path to the running instance.
					If the main window is not the only window (there is already a dialog) the parameter is ignored.</para> 
				</listitem>
				<listitem>
    				<para>-s, --snapshots - go directly to the specified file or folder and 
					show snapshots dialog.
					If the application is already running if pass the path to the running instance.
					If the main window is not the only window (there is already a dialog) the parameter is ignored.</para> 
				</listitem>
				<listitem>
    				<para>-b, --backup - take a snapshot now (if needed).</para> 
				</listitem>
				<listitem>
    				<para>--backup-job - take a snapshot (if needed) depending on schedule rules (used for cron jobs).</para> 
				</listitem>
				<listitem>
    				<para>--snapshots-path - display the path where is saves the snapshots (if configured).</para> 
				</listitem>
				<listitem>
    				<para>--snapshots-list - display the list of snapshot IDs.</para> 
				</listitem>
				<listitem>
    				<para>--snapshots-list-path - display the path to snapshots.</para> 
				</listitem>
				<listitem>
    				<para>--last-snapshot - display last snapshot ID.</para> 
				</listitem>
				<listitem>
    				<para>--last-snapshot-path - display the path to the last snapshot.</para> 
				</listitem>
				<listitem>
    				<para>-h, --help - display a small help and exit.</para> 
				</listitem>
				<listitem>
    				<para>-v, --version - display the version and exit.</para> 
				</listitem>
				<listitem>
    				<para>--license - show license and exit.</para> 
				</listitem>
    		</itemizedlist>
    		</listitem>
    	</varlistentry>
    </variablelist>

    <!-- Include any descriptions of the GUI immediately after the screenshot of the main UI, -->
    <!-- for example, the items on the menubar and on the toolbar. This section is optional. -->

  </sect1>

<!-- =========== Main Window ============================== -->
  <sect1 id="backintime-mainwindow">
  <title>Main Window</title>

    <!-- ==== Figure ==== -->
      <figure id="mainwindow-fig"> 
	<title>Main Window</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/mainwindow.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

  <para>The <application>Back In Time</application> main window contains the following elements:</para>

  <variablelist>

	<varlistentry>
	<term>Main toolbar</term>
	<listitem><para>Take a new snapshot (if neccesary)</para></listitem>
	<listitem><para>Update snapshots list</para></listitem>
	<listitem><para>Edit selected snapshot's name</para></listitem>
	<listitem><para>Remove selected snapshot</para></listitem>
	<listitem><para>Settings dialog</para></listitem>
	<listitem><para>About dialog</para></listitem>
	<listitem><para>Help</para></listitem>
	<listitem><para>Quit</para></listitem>
	</varlistentry>

	<varlistentry>
	<term>Files toolbar</term>
	<listitem><para>Go to parent folder</para></listitem>
	<listitem><para>Current path</para></listitem>
	<listitem><para>Show/Hide hidden (.*) and backup (*.~) files</para></listitem>
	<listitem><para>Restore current file/folder</para></listitem>
	<listitem><para>Copy current file/folder</para></listitem>
	<listitem><para>Snapshots: show all snapshots for current the file/folder</para></listitem>
	</varlistentry>

	<varlistentry>
	<term>Snapshots list</term>
	<listitem>
	<para>Navigate between 'now' and snapshots</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Places list</term>
	<listitem>
	<para>Quickly navigate to special folders: home, root, bookmarks and folders to backup</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Files list</term>
	<listitem>
	<para>Navigate through the file system at the moment specified in snapshots list.</para>
	<para>You can sort the files (by clicking on column headers):</para>
    	<itemizedlist> 
			<listitem>by name (folders always first)</listitem>
			<listitem>by size</listitem>
			<listitem>by date</listitem>
    	</itemizedlist> 
	<para>If you click/double-click a file it will be opened using KDE4 file association. Keep in mind that snapshots are 'readonly'.</para>
	<para>If you click/double-click a folder it will go to that folder.</para>
	</listitem>
	</varlistentry>

  </variablelist>

  </sect1>

<!-- ================ Settings Dialog ================================ -->
  <sect1 id="settingsdialog"> 
    <title>Settings Dialog</title> 
    <para>When the application starts for the first time (not configured yet) this dialog is 
	displayed automaticaly.</para>

	<para></para>
	<guimenuitem>General</guimenuitem>

    <!-- ==== Figure ==== -->
    <figure id="settings-destination"> 
	<title>Settings Dialog: General</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/settings_general.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->

	<para>Where to save snapshots.</para>
	<para>You can schedule automatic backups:</para>
    <itemizedlist> 
		<listitem>disabled</listitem>
		<listitem>every 5 minutes</listitem>
		<listitem>every 10 minutes</listitem>
		<listitem>every hour</listitem>
		<listitem>every day</listitem>
		<listitem>every week</listitem>
		<listitem>every month</listitem>
    </itemizedlist> 
	<para>Automatic backup use cron jobs so cron must be running.</para>

	<para></para>
	<guimenuitem>Include</guimenuitem>

    <!-- ==== Figure ==== -->
    <figure id="settings-include"> 
	<title>Settings Dialog: Include</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/settings_include.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->

	<para>Define the folders you want to backup.</para>

	<para></para>
	<guimenuitem>Exclude</guimenuitem>

    <!-- ==== Figure ==== -->
    <figure id="settings-exclude"> 
	<title>Settings Dialog: Exclude</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/settings_exclude.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->

	<para>For include folders you can exclude some files and folders.</para>
	<para>You can specifiy them directly or using patterns.</para>

	<para></para>
	<guimenuitem>Auto-Remove</guimenuitem>

    <!-- ==== Figure ==== -->
    <figure id="settings-auto-remove"> 
	<title>Settings Dialog: Auto-Remove</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/settings_auto_remove.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->

	<para>You can automatically remove snapshots older then a specific date or if the free space is 
	less then a specified value.</para>
	<para>Smart remove allow you to reduce the number of snapshots using the following rules:</para>
    	<itemizedlist> 
			<listitem>keep all snapshots from today and yesterday</listitem>
			<listitem>keep one snapshot for the last week and one for two weeks ago</listitem>
			<listitem>keep one snapshot per month for all previous months of this year</listitem>
			<listitem>keep one snapshot per year for all previous years</listitem>
    	</itemizedlist> 
	<para>By default it does not remove named snapshots.</para>

	<para></para>
	<guimenuitem>Options</guimenuitem>

    <!-- ==== Figure ==== -->
    <figure id="settings-options"> 
	<title>Settings Dialog: Options</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/settings_options.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->

	<para>Enable notifications: if there is an error while taking a snapshot it will display a notification popup.</para>

    <!-- ==== Figure ==== -->
    <figure id="settings-expert-options"> 
	<title>Settings Dialog: Expert Options</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/settings_expert_options.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->

	<para>Enable schedule per included folder: if selected include list (include tab) will show a 
	second column ('Schedule'). This column allow you to specify the schedule per folder.</para>

  </sect1>

<!-- ================ Snapshots Dialog ================================ -->
  <sect1 id="snapshotsdialog"> 
    <title>Snapshots Dialog</title> 
    <para>Show all snapshots for a specific file or folder.</para>

    <!-- ==== Figure ==== -->
      <figure id="snapshotsdialog-fig"> 
	<title>Snapshots Dialog</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/snapshots.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

	<para>Click/Double-click an item in the snapshots list to open it with KDE4 file associations.</para>
	<para>When you select an item, you can:</para>
    <itemizedlist> 
		<listitem>Jump to: close the dialog an go to the selected snapshot in the main window</listitem>
		<listitem>Copy the item to clipboard</listitem>
		<listitem>Restore it (only for snapshots)</listitem>
   	</itemizedlist> 
	<para>You can compare two different snapshots.
	By default it use 'meld' to compare files adn folders.
	Use diff options to change the diff command and it's parameters.</para>
  </sect1>

<!-- =========== user.callback ============================== -->
  <sect1 id="backintime-user-callback"> 
    <title>user.callback</title> 
    <para>During backup process the application can call a user callback at different steps.
	This callback is "$XDG_CONFIG_HOME/backintime/user.callback" (by default $XDG_CONFIG_HOME is ~/.config).
	The first argument is the reason:</para> 
	<itemizedlist>
		<listitem>
			<para>1 - Backup process begins.</para>
		</listitem>
		<listitem>
			<para>2 - Backup process ends.</para>
		</listitem>
		<listitem>
			<para>3 - A new snapshot was taken. The extra arguments are snapshot ID and snapshot path.</para>
		</listitem>
		<listitem>
			<para>4 - There was an error. The second argument is the error code:</para>
			<itemizedlist>
				<listitem>
					<para>1 - The application is not configured.</para>
				</listitem>
				<listitem>
					<para>2 - A "take snapshot" process is already running.</para>
				</listitem>
				<listitem>
					<para>3 - Can't find snapshots folder (is it on a removable drive ?).</para>
				</listitem>
				<listitem>
					<para>4 - A snapshot for "now" already exist.</para>
				</listitem>
			</itemizedlist>
		</listitem>
	</itemizedlist>

  </sect1>

<!-- ============= Bugs ================================== -->
<!-- This section is optional and is commented out by default. 
     You can use it to describe known bugs and limitations of the 
	  program if there are any - please be frank and list all
     problems you know of. 
  
  <sect1 id="backintime-bugs">
  <title>Known Bugs and Limitations</title>
  <para> </para>
 </sect1>
-->

<!-- ============= About ================================== -->
<!-- This section contains info about the program (not docs), such as
      author's name(s), web page, license, feedback address. This
      section is optional: primary place for this info is "About.." box of
      the program. However, if you do wish to include this info in the
      manual, this is the place to put it. Alternatively, you can put this information in the title page.-->
  <sect1 id="backintime-about"> 
    <title>About &app;</title> 
    <para> &app; was written by Oprea Dan
      (<email>dan@le-web.org</email>). To find more information about
      &app;, please visit the 
      <ulink url="http://backintime.le-web.org" type="http">Back In Time Web
	page</ulink>. </para>
    <para>
      To report a bug or make a suggestion regarding this application or
      this manual, sent a mail to
      <ulink url="mailto:dan@le-web.org" type="mailto">dan@le-web.org</ulink>.
    </para>

    <para> This program is distributed under the terms of the GNU
      General Public license version 2 as published by the Free Software
      Foundation. A copy of this license can be found in the file
      LICENSE included with the source code of this program. </para>

  </sect1> 
</article>
