summaryrefslogtreecommitdiff
path: root/baobab/help/C/index.docbook
blob: 3e40b41fae054c58c89c879ff2cc1feeca2ff4dd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ 
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "1.10">
  <!ENTITY manrevision "1.10">
  <!ENTITY date "July 2015">
  <!ENTITY app "Disk Usage Analyzer">
]>
<!-- 
      (Do not remove this comment block.)
  Maintained by the MATE Documentation Project
  http://wiki.mate-desktop.org/dev-doc:doc-team-guide
  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 lang="en"> 
      <year>2015</year> 
      <holder>MATE Documentation Project</holder>
    </copyright>
    <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> 
    <publisher> 
      <publishername>GNOME Documentation Project</publishername>
    </publisher> 

   &legal;

   <authorgroup>
      <author role="maintainer" lang="en"> 
	<surname>MATE-Dokumentationsteam</surname> 
	<affiliation> 
	  <orgname>Mate desktop</orgname> 
	</affiliation> 
      </author>
   <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>

	<releaseinfo revision="1.10" role="review">
	</releaseinfo>

    <revhistory>
      <revision> 
		<revnumber>&app; Manual 1.10</revnumber> 
		<date>July 2015</date> 
		<revdescription> 
	  		<para role="author" lang="en">Wolfgang Ulbrich
	  		</para>
	  		<para role="publisher">MATE Documentation Project</para>
		</revdescription> 
      </revision>
      <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="help:mate-user-guide/feedback" type="help">MATE Feedback Page</ulink>. 
      </para>
<!-- Translators may also add here feedback address for translations -->
    </legalnotice> 
  </articleinfo> 

  <indexterm> 
    <primary>Disk Usage Analyzer</primary>
  </indexterm> 

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

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

      <para><application>&app;</application> is a graphical, menu-driven
      application to analyze 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 appear with information about its
      name and size. If there are any subfolders, small gray 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 
      behavior, 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 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>