Use yelp-tools instead of mate-doc-utils

1 files changed, 443 insertions, 0 deletions

diff --git a/baobab/help/C/index.docbook b/baobab/help/C/index.docbook
new file mode 100644
index 00000000..8c30a5ca
--- /dev/null
+++ b/baobab/help/C/index.docbook
@@ -0,0 +1,443 @@
+<?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 MATE Documentation Project
+  http://developer.mate.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> MATE Documentation Project </publishername> 
+    </publisher> 
+
+   &legal;
+
+   <authorgroup> 
+   <author> 
+		<firstname>Fabio</firstname> 
+		<surname>Marzocca</surname> 
+		<affiliation> 
+	  	<orgname>MATE Documentation Project</orgname> 
+	  	<address> <email>[email protected]</email> </address> 
+		</affiliation> 
+   </author> 
+
+   <author role="maintainer">
+   	<firstname>Fabio</firstname>
+	<surname>Marzocca</surname>
+	<affiliation>
+	  <address><email>[email protected]</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>[email protected]</email> </address> 
+		</affiliation>
+		<contrib>Latin translation</contrib>
+   </othercredit>
+-->
+    </authorgroup>
+
+	<releaseinfo revision="2.30" role="review">
+	</releaseinfo>
+
+    <revhistory>
+      <revision> 
+		<revnumber>&app; Manual 1.0</revnumber> 
+		<date>April 2006</date> 
+		<revdescription> 
+	  		<para role="author">Emmanuele Bassi
+	    		<email>[email protected]</email>
+	  		</para>
+	  		<para role="publisher">MATE 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="help:mate-feedback" type="help">MATE 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 a graphical, menu-driven
+      application to analyse disk usage in any Mate 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 Mate menu <menuchoice><guimenu>Applications</guimenu><guimenuitem>Accessories</guimenuitem></menuchoice>;</para>
+    		</listitem>
+    <listitem><para>from a terminal window;</para>
+    		</listitem>
+    <listitem><para>from Caja "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 Mate 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 Mate 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>
+
+
+</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>
+  <!-- ================ Ringschart ================================ -->
+
+  <sect1 id="baobab-ringschart"> 
+  <title>Ringschart</title>
+
+    <para><guilabel>Ringschart</guilabel> is a graphical
+      representation of the disk usage by a concrete folder. When
+      launching the application, it is notified the usage of
+      the file system as it can be seen in the next figure:</para>
+
+    <!-- ==== Figure ==== -->
+    <figure id="baobab-filesystem_scan"> 
+      <title>&app; showing a ringschart with the file system usage</title>
+      <screenshot> 
+	<mediaobject> 
+	  <imageobject>
+	    <imagedata fileref="figures/baobab_ringschart1.png" format="PNG"/> 
+	  </imageobject>
+	  <textobject> 
+	    <phrase>After launching the application, it is showed the
+	    file system usage. Graphical representation 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 ends up,
+      the <guilabel>Ringschart</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>&app; showing a ringschart 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>Ringschart</guilabel> is composed of a set of 
+      nested rings around a central circle. This circle symbolizes 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, so 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
+      color to ease visualization. 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 appears 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 overlappings.</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>ringschart</guilabel> itself. If you click with the left
+      button of your mouse inside a folder, you'll move deeper by 
+      setting the root of the graphic to that folder. If you press the 
+      middle button (no matter the place as long as you click inside the 
+      <guilabel>ringschart</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 it's own
+      size and its parent's. It's easy to understand that the size of 
+      a folder is equal 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>