<?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 appversion "2.15">
  <!ENTITY manrevision "1.0">
  <!ENTITY date "April 2006">
  <!ENTITY app "Disk Usage Analyzer">
]>
<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.gnome.org/projects/gdp
  Template version: 2.0 beta
  Template last modified Apr 11, 2002
  
-->
<!-- =============Document Header ============================= -->
<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo> 
    <title>&app; Manual</title>

    <abstract role="description">
      <para>&app; is a graphical, menu-driven viewer that you can
      use to view and monitor your disk usage and folder structure.</para>
    </abstract>

    <copyright> 
      <year>2006</year> 
      <holder>Fabio Marzocca</holder> 
    </copyright> 
<!-- translators: uncomment this:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->
    <publisher> 
      <publishername> GNOME Documentation Project </publishername> 
    </publisher> 

   &legal;

   <authorgroup> 
   <author> 
		<firstname>Fabio</firstname> 
		<surname>Marzocca</surname> 
		<affiliation> 
	  	<orgname>GNOME Documentation Project</orgname> 
	  	<address> <email>thesaltydog@gmail.com</email> </address> 
		</affiliation> 
   </author> 

   <author role="maintainer">
   	<firstname>Fabio</firstname>
	<surname>Marzocca</surname>
	<affiliation>
	  <address><email>thesaltydog@gmail.com</email></address>
	</affiliation>
   </author>
      
<!-- This is appropriate place for other contributors: translators,
      maintainers,  etc. Commented out by default.
   <othercredit role="translator">
		<firstname>Latin</firstname> 
		<surname>Translator 1</surname> 
		<affiliation> 
	  	<orgname>Latin Translation Team</orgname> 
	  	<address> <email>translator@gnome.org</email> </address> 
		</affiliation>
		<contrib>Latin translation</contrib>
   </othercredit>
-->
    </authorgroup>

    <revhistory>
      <revision> 
		<revnumber>&app; Manual 1.0</revnumber> 
		<date>April 2006</date> 
		<revdescription> 
	  		<para role="author">Emmanuele Bassi
	    		<email>ebassi@gmail.com</email>
	  		</para>
	  		<para role="publisher">GNOME Documentation Project</para>
		</revdescription> 
      </revision>
    </revhistory> 

    <releaseinfo>This manual describes version &appversion; of &app;.</releaseinfo> 
    
    <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the &app; application or
	this manual, follow the directions in the 
	<ulink url="ghelp:gnome-feedback" type="help">GNOME Feedback Page</ulink>. 
      </para>
<!-- Translators may also add here feedback address for translations -->
    </legalnotice> 
  </articleinfo> 

  <indexterm> 
    <primary>Disk Usage Analyser</primary> 
  </indexterm> 

<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->

  <sect1 id="baobab-introduction"> 
    <title>Introduction</title> 

      <para><application>&app;</application> is is a graphical, menu-driven
      application to analyse disk usage in any Gnome environment. <application>&app;</application> can easily scan 
       either the whole filesystem tree, or a specific user-requested directory 
       branch (local or remote). </para>
       <para>It also auto-detects in real-time any changes 
       made to your home directory as far as any mounted/unmounted device. 
       <application>&app;</application> also provides a full graphical treemap 
       window for each selected folder.</para>

  </sect1>

<!-- ================ Getting Started ================================ -->
	<sect1 id="baobab-getting-started">
	<title>Getting Started</title>

    <para><application>&app;</application> can be started in three ways:</para>
	 <itemizedlist>
    <listitem><para>from Gnome menu <menuchoice><guimenu>Applications</guimenu><guimenuitem>Accessories</guimenuitem></menuchoice>;</para>
    		</listitem>
    <listitem><para>from a terminal window;</para>
    		</listitem>
    <listitem><para>from Nautilus "Open with..." ;</para>
    		</listitem>
    </itemizedlist> 


<para>If you want to start <application>&app;</application> from a terminal window, just type:</para> 
  
<para><command>baobab &lt;full_path_to_a_directory&gt;</command>, then press <keycap>Return</keycap>.</para>  
<para></para> 
	<para>If launched from Gnome menu, <application>&app;</application> starts and remains in a stand-by state, waiting for user action.</para> 
    <para>When you start <application>&app;</application> from the Gnome Menu, the following window is displayed.</para>

    <!-- ==== Figure ==== -->
      <figure id="baobab-fig"> 
	<title>&app; Window</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject>
	    <imagedata fileref="figures/baobab_window.png" format="PNG"/> 
	    </imageobject>
	    <textobject> 
	      <phrase>Shows &app; main window. Contains menubar, display area, scrollbars, and statusbar. </phrase> 
	    </textobject> 
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

<para>The user can then:</para>
	<itemizedlist>
    <listitem><para>start a full filesystem scan;</para>
    		</listitem>
    <listitem><para>select a specific local directory branch to scan</para>
    		</listitem>
    <listitem><para>select a remote server and folder to scan</para>
    		</listitem>
    <listitem><para>set preferences</para>
    		</listitem>
	</itemizedlist>
	
	<note><para>If you run a full filesystem scan, 
	<application>&app;</application> window will start drawing the tree as soon 
	as the thread starts scanning the filesystem. If any large partition is mounted 
	on the filesystem, that will be scanned too.</para></note>

</sect1>

<!-- ================ Usage ================================ -->

  <sect1 id="baobab-usage"> 
    <title>Usage</title>

    <sect2 id="baobab-fullscan">
      <title>Full filesystem scan</title>
        <para>To start a full filesystem scan select <menuchoice><guimenu>Analyzer</guimenu><guimenuitem>Scan Filesystem</guimenuitem></menuchoice> 
    from the menu, or press on the <guibutton>Scan Filesystem</guibutton> toolbar button.</para>

	<para>When the scanning process ends up, you will get the full tree of your filesystem,
	like the one in the next Figure.</para>    

    <!-- ==== Figure ==== -->
      <figure id="baobab-fullscan-fig"> 
	<title>&app; Full filesystem scan</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject>
	    <imagedata fileref="figures/baobab_fullscan.png" format="PNG"/> 
	    </imageobject>
	    <textobject> 
	      <phrase>Shows &app; full filesystem scan window. Contains menubar, display area, scrollbars, and statusbar. </phrase> 
	    </textobject> 
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
    
    	<note><para>When you run a full filesystem scan, 
	<application>&app;</application> window will start drawing the tree as soon 
	as the thread starts scanning the filesystem. If any large partition is mounted 
	on the filesystem, that will be scanned too.</para></note>
    
    <para><application>&app;</application> will display sizes in the 
    directory tree as allocated space. This means that the displayed sizes refer 
    to the actual disk usage and not to the apparent directory size. 
    If you want to view the apparent file size, uncheck <menuchoice><guimenu>View</guimenu><guimenuitem>Allocated Space</guimenuitem></menuchoice> .</para>
    
    <warning><para><application>&app;</application> will not count the /proc dir, nor
    any file size that is not related to a "plain" file, so symlinks, character blocks,
    device blocks will not be part of the directory size.</para></warning>
   
    <para>Hard-links are managed in a different way: this first hardlink is 
    counted as a normal file, while the subsequent links to the same inode device 
    are not counted in the total, but highlighted in the right-hand column of the 
    window.</para>
        </sect2>
	
	<sect2 id="baobab-folderscan">
      <title>Single folder scan</title>

    <para>To start a single folder scan select 
    <menuchoice><guimenu>Analyzer</guimenu><guimenuitem>Scan Folder...</guimenuitem></menuchoice> 
    from the menu, or press on the <guibutton>Scan Folder</guibutton> toolbar button.</para>

	</sect2>

	<sect2 id="baobab-remotescan">
      <title>Remote scan</title>
      
      <para>If you need to scan a remote server-folder, just click on the toolbar 
      icon <guibutton>Scan Remote Folder</guibutton> or select <menuchoice><guimenu>Analyzer</guimenu><guimenuitem>Scan Remote Folder</guimenuitem></menuchoice>
      from the menu and you will get the following dialog box. <application>&app;</application> 
      can connect to a server through ssh, ftp, smb, http and https.</para>
 
     <!-- ==== Figure ==== -->
      <figure id="baobab-remote-fig"> 
        <title>&app; Remote folder scan</title> 
		<screenshot> 
	 	 <mediaobject> 
	  	  <imageobject>
	   	 <imagedata fileref="figures/baobab_remote.png" format="PNG"/> 
	   	 </imageobject>
	   	 <textobject> 
	    	  <phrase>Shows &app; remote folder dialog window. </phrase> 
	   	 </textobject> 
	 	 </mediaobject> 
		</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
   
	</sect2> 

  </sect1>


<!-- ============= Preferences =============================== -->
  <sect1 id="baobab-preferences">
    <title>Preferences</title>
    
    <para>To change the <application>&app;</application> application
    preferences, choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>.</para>
 
   <!-- ==== Figure ==== -->
      <figure id="baobab-preferences-fig"> 
      	<title>&app; Preferences Window</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject>
	    <imagedata fileref="figures/baobab_prefs.png" format="PNG"/> 
	    </imageobject>
	    <textobject> 
	      <phrase>Preferences window </phrase> 
	    </textobject> 
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
  
  <sect2 id="baobab-scan-preferences">
      <title>Select devices to be scanned</title>
  <para>In the first part of the Preferences window, all detected mounted devices 
  are listed. Click on the checkbox to include/exclude the partition into the 
  filesystem scanning operations.  </para>
  <note><para>The device mounted on "/" cannot be excluded from the scan.</para></note>
  </sect2>
 
   <sect2 id="baobab-monitor-preferences">
      <title>Enable monitoring of home</title>
      <para>If this option is checked, <application>&app;</application> will 
      constantly monitor any external changes to home directory and warn 
      the user if a file is added/removed.</para>  
   </sect2>  
	</sect1>
<!-- ================ Treemaps ================================ -->

  <sect1 id="baobab-treemaps"> 
  <title>Treemaps</title>

    <para><guilabel>Treemap</guilabel> concepts have been developed by Ben Shneiderman in the '90s.
    Read his <ulink type="http" url="http://www.cs.umd.edu/hcil/treemap-history/index.shtml">vision on treemaps</ulink>.</para>
    
       <!-- ==== Figure ==== -->
      <figure id="baobab-treemap-fig"> 
        <title>&app; Treemap Window</title>
	<screenshot> 
	  <mediaobject> 
	    <imageobject>
	    <imagedata fileref="figures/baobab_treemaps.png" format="PNG"/> 
	    </imageobject>
	    <textobject> 
	      <phrase>Treemap's theory. Shows 2 treemap diagrams </phrase> 
	    </textobject> 
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
  
    
    <para>Figure shows an example of treemap's theory. Each node 
    (as shown in the tree diagram) has a name (a letter) and an associated size 
    (a number). The size of leaves may represent for instance the size of individual 
    files, the size of non-leaf nodes is the sum of the sizes of its children.</para> 
    
    <para>The treemap is constructed via recursive subdivision of the initial rectangle. 
    The size of each sub-rectangle corresponds to the size of the node. 
    The direction of subdivision alternates per level: first horizontally, 
    next vertically, etcetera. As a result, the initial rectangle is partitioned 
    into smaller rectangles, such that the size of each rectangle reflects the size 
    of the leaf. The structure of the tree is also reflected in the treemap, 
    as a result of its construction. Color and annotation can
	be used to give extra information about the leaves.</para>

	<note><para>Treemaps are very effective when size is the most important feature to be 
	displayed.</para></note>
  </sect1>
</article>
