<?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 "Mars 2009">
]>
<!--
      (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 GNOME desktop.</para>
    </abstract>         

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

    <!-- An address can be added to the publisher information. -->
    <publisher role="maintainer"> 
      <publishername>Oprea Dan</publishername>
    </publisher> 

	<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. -->

    <authorgroup> 
      <author> 
    		<firstname>Oprea</firstname> 
    		<surname>Dan</surname> 
    		<affiliation> 
    	  		<!-- <orgname></orgname> -->
    	  		<!-- The email address of the author is optional and is commented out by default. 
    			<address> <email>doc-writer2@gnome.org</email> </address> 
    			-->
    		</affiliation> 
      </author> 
    </authorgroup>
    

<!-- 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. -->  
    <revhistory>
      <revision> 
		<revnumber>Back In Time Manual V&manrevision;</revnumber> 
		<date>&date;</date> 
		<revdescription> 
	  		<para role="author">Oprea Dan
        <!-- The email address of the author is optional and is commented out by default.  
	    	<email>docwriter2@gnome.org</email> -->
	  		</para>
	  		<para role="publisher">Oprea dan</para>
		</revdescription> 
      </revision>
	  <!--
      <revision> 
		<revnumber>Full title of previous manual.</revnumber> 
		<date>Release date of previous manual.</date> 
		<revdescription> 
	  		<para role="author">Documentation Writer 1 
	  		</para>
	  		<para role="publisher">GNOME Documentation Project</para>
		</revdescription> 
      </revision> 
	  -->
    </revhistory> 

    <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 Gnome 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 Tools</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 double-click a file it will be opened using gnome file association. Keep in mind that snapshots are 'readonly'.</para>
	<para>If you double-click a folder it will go to that folder.</para>
	<para>If you "right-click" on a file or folder you will see a popup-menu</para>
    	<itemizedlist> 
			<listitem>Open: open the item using gnome-open</listitem>
			<listitem>Copy: copy selected item into clipboard (you can paste the file/folder into your file-manager)</listitem>
			<listitem>Snapshots: show all snapshots for the current file/folder</listitem>
			<listitem>Restore (only for snapshots items): restore selected file/folder</listitem>
    	</itemizedlist> 
	</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-general"> 
	<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 directories.</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/snapshotsdialog.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

	<para>Double-click an item in the snapshots list to open it with gnome 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>

	<para>If you "right-click" on a snapshot you will see a popup-menu</para>
    	<itemizedlist> 
			<listitem>Open: open the item using gnome-open</listitem>
			<listitem>Copy: copy selected item into clipboard (you can paste the file/folder into your file-manager)</listitem>
			<listitem>Jump to: close the dialog an go to the selected snapshot in the main window</listitem>
			<listitem>Restore (only for snapshots): restore selected file/folder</listitem>
			<listitem>Diff: compare it with another snapshot</listitem>
    	</itemizedlist> 
  </sect1>

<!-- ================ Integration with Nautilus ================================ -->
  <sect1 id="integrationwithnautilus"> 
    <title>Integration with Nautilus</title> 
	<para>It is not are "real" integration with Nautilus but it is simple to setup.</para>
	<para>You need to install nautilus-actions. On Ubuntu you can install it with the command:</para>
	<para>
	<command>sudo apt-get install nautilus-actions</command>
	</para>
	<para>
	Now just create an action from
		<menuchoice>
    		<guimenu>System</guimenu>
    		<guisubmenu>Preferences</guisubmenu>
    		<guimenuitem>Nautilus Actions Configuration</guimenuitem>
    	</menuchoice>.
	</para>
	<para>1. Click Add button</para>
    <!-- ==== Figure ==== -->
      <figure id="nautilus-actions-step1-fig"> 
	<title>Nautilus Integration: Step 1</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/nautilus_actions_step1.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
	<para>2. Menu Item &amp; Action Tab</para>
    	<itemizedlist> 
			<listitem>%M - Open &app; directly to the specified path</listitem>
			<listitem>--snapshots %M - Open &app; an go to SnapshotsDialog for the specifies path</listitem>
    	</itemizedlist> 
    <!-- ==== Figure ==== -->
      <figure id="nautilus-actions-step2-fig"> 
	<title>Nautilus Integration: Step 2</title> 
	<para>You can set Action Parameters to:</para>
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/nautilus_actions_step2.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
	<para>3. Conditions Tab</para>
    <!-- ==== Figure ==== -->
      <figure id="nautilus-actions-step3-fig"> 
	<title>Nautilus Integration: Step 3</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/nautilus_actions_step3.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
	<para>4. Advanced conditions Tab</para>
    <!-- ==== Figure ==== -->
      <figure id="nautilus-actions-step4-fig"> 
	<title>Nautilus Integration: Step 4</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/nautilus_actions_step4.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
	<para>5. Click OK button, and you should see the new action in actions list</para>
    <!-- ==== Figure ==== -->
      <figure id="nautilus-actions-step5-fig"> 
	<title>Nautilus Integration: Step 5</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata fileref="figures/nautilus_actions_step5.png" format="PNG"/></imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
	<para>That's it. Now from Nautilus "Right-click" the file/foder you want and click "Back In Time"</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>
