<?xml version="1.0" encoding="utf-8"?>
<!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_GB">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo> 
    <title>Disk Usage Analyser Manual</title>

    <abstract role="description">
      <para>Disk Usage Analyser 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><copyright><year>2007</year><holder>David Lodge (dave@cirt.net)</holder></copyright> 
<!-- translators: uncomment this:

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

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

     <legalnotice id="legalnotice">
	<para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation Licence (GFDL), Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL at this <ulink type="help" url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS distributed with this manual.</para>
         <para>This manual is part of a collection of GNOME manuals distributed under the GFDL. If you want to distribute this manual separately from the collection, you can do so by adding a copy of the licence to the manual, as described in section 6 of the licence.</para>

	<para>Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and the members of the GNOME Documentation Project are made aware of those trademarks, then the names are in capital letters or initial capital letters.</para>

	<para>DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENCE WITH THE FURTHER UNDERSTANDING THAT: <orderedlist>
		<listitem>
		  <para>DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENCE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS AUTHORISED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND</para>
		</listitem>
		<listitem>
		  <para>UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY CONTRIBUTOR OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.</para>
		</listitem>
	  </orderedlist></para>
  </legalnotice>



   <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>Disk Usage Analyser 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 2.15 of Disk Usage Analyser.</releaseinfo> 
    
    <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the Disk Usage Analyser 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>Disk Usage Analyser</application> is a graphical, menu-driven application to analyse disk usage in any Gnome environment. <application>Disk Usage Analyser</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>Disk Usage Analyser</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>Disk Usage Analyser</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>Disk Usage Analyser</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>If launched from Gnome menu, <application>Disk Usage Analyser</application> starts and remains in a stand-by state, waiting for user action.</para> 
    <para>When you start <application>Disk Usage Analyser</application> from the Gnome Menu, the following window is displayed.</para>

    <!-- ==== Figure ==== -->
      <figure id="baobab-fig"> 
	<title>Disk Usage Analyser Window</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject>
	    <imagedata fileref="figures/baobab_window.png" format="PNG"/> 
	    </imageobject>
	    <textobject> 
	      <phrase>Shows Disk Usage Analyser 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, the <application>Disk Usage Analyser</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>Analyser</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>Disk Usage Analyser Full filesystem scan</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject>
	    <imagedata fileref="figures/baobab_fullscan.png" format="PNG"/> 
	    </imageobject>
	    <textobject> 
	      <phrase>Shows Disk Usage Analyser 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, the <application>Disk Usage Analyser</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>Disk Usage Analyser</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>Disk Usage Analyser</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 hard-link 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>Analyser</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 folder on a remote server, just click on the toolbar icon <guibutton>Scan Remote Folder</guibutton> or select <menuchoice><guimenu>Analyser</guimenu><guimenuitem>Scan Remote Folder</guimenuitem></menuchoice> from the menu and you will get the following dialogue box. <application>Disk Usage Analyser</application> can connect to a server through ssh, ftp, smb, http and https.</para>
 
     <!-- ==== Figure ==== -->
      <figure id="baobab-remote-fig"> 
        <title>Disk Usage Analyser Remote folder scan</title> 
		<screenshot> 
	 	 <mediaobject> 
	  	  <imageobject>
	   	 <imagedata fileref="figures/baobab_remote.png" format="PNG"/> 
	   	 </imageobject>
	   	 <textobject> 
	    	  <phrase>Shows Disk Usage Analyser remote folder dialogue window.</phrase> 
	   	 </textobject> 
	 	 </mediaobject> 
		</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->
   
	</sect2> 

  </sect1>


<!-- ============= Preferences =============================== -->
  <sect1 id="baobab-preferences">
    <title>Preferences</title>
    
    <para>To change the <application>Disk Usage Analyser</application> application preferences, choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>.</para>
 
   <!-- ==== Figure ==== -->
      <figure id="baobab-preferences-fig"> 
      	<title>Disk Usage Analyser 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>Disk Usage Analyser</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>Disk Usage Analyser 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, then vertically, etc. 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. Colour 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>
  <!-- ================ Ringschart ================================ -->

  <sect1 id="baobab-ringschart"> 
  <title>Ring chart</title>

    <para><guilabel>Ring chart</guilabel> is a graphical representation of the disk usage by a concrete folder. When launching the application, the filesystem usage is displayed as can be seen in the next figure:</para>

    <!-- ==== Figure ==== -->
    <figure id="baobab-filesystem_scan"> 
      <title>Disk Usage Analyser showing a ring chart with the file system usage</title>
      <screenshot> 
	<mediaobject> 
	  <imageobject>
	    <imagedata fileref="figures/baobab_ringschart1.png" format="PNG"/> 
	  </imageobject>
	  <textobject> 
	    <phrase>After launching the application, the file system usage is shown. A graphical representation is on the right.</phrase> 
	  </textobject> 
	</mediaobject> 
      </screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->

    <para>When you start scanning a folder, the tree of subfolders is created and listed on the left side. Each row contains information for the name, how much space it is taking up (percentage and size in KB, MB or GB) and the number of items (adding files and directories). When this process is finished, the <guilabel>Ring chart</guilabel> is drawn on the right side. If you stop it before it has been completed, only a partial representation is done based on the directories whose usage was computed.</para>


    <!-- ==== Figure ==== -->
    <figure id="baobab-folder_scan"> 
      <title>Disk Usage Analyser showing a ring chart with the usage of a folder.</title>
      <screenshot> 
	<mediaobject> 
	  <imageobject>
	    <imagedata fileref="figures/baobab_ringschart2.png" format="PNG"/> 
	  </imageobject>
	  <textobject> 
	    <phrase>After scanning a folder.</phrase> 
	  </textobject> 
	</mediaobject> 
      </screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->
    
    <para>The <guilabel>Ring chart</guilabel> is composed of a set of nested rings around a central circle. This circle symbolises the root folder of the partial tree (that is, the folder that the user has selected for scanning). Each ring represents a level in the partial tree, i.e. the subfolders of the root folder will be represented in the first ring, and deeper levels in the tree correspond to outer rings in the chart. Each subfolder is represented by a sector of the ring, its angle being proportional to the size of the folder's contents, and painted with a different colour to ease visualisation. Up to five levels can be drawn; in case that a folder in that last fifth level contains even more subfolders, this situation will be pointed by the presence of a black curve close to the edge of that folder's ring sector. When a folder with no further subfolders is selected to be the root of the partial tree, only the inner circle will be drawn. When the mouse pointer hovers one of the folders in the graphic, it will be highlighted and a tooltip will appear with information about its name and size. If there are any subfolders, small grey tooltips will appear, indicating their names. It's possible that not all of the subfolders' names are displayed, to avoid overlapping.</para>

    <para>You can go up and down the rows in the list (optionally expanding those with subfolders); the graphic representation will change using the selected folder as the root of the partial tree to be represented. The folders can also be navigated from the <guilabel>ring chart</guilabel> itself. If you left-click inside a folder, you'll move deeper by setting the root of the graphic to that folder. If you middle-click anywhere inside the <guilabel>ring chart</guilabel> frame you'll get the opposite behaviour, going back one step in the hierarchy.</para>

    <para>The percentage of its parent's radius that is used by a given folder is directly proportional to the relation between its own size and its parent's. It's easy to understand that the size of a folder is equal to or smaller than its parent's. Although only directories are shown in this graphical representation, files are taken into account to calculate the amount of space occupied by folders.</para>
  </sect1>
</article>
