diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/en/Makefile.am | 11 | ||||
| -rw-r--r-- | doc/en/feedback-mail.png | bin | 0 -> 14538 bytes | |||
| -rw-r--r-- | doc/en/index.docbook | 1954 | ||||
| -rw-r--r-- | doc/en/kdirstat-config-cleanups.png | bin | 0 -> 14165 bytes | |||
| -rw-r--r-- | doc/en/kdirstat-config-tree-colors.png | bin | 0 -> 11280 bytes | |||
| -rw-r--r-- | doc/en/kdirstat-main.png | bin | 0 -> 39583 bytes |
7 files changed, 1967 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..8eb3435 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,2 @@ +SUBDIRS = en + diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am new file mode 100644 index 0000000..bcc478a --- /dev/null +++ b/doc/en/Makefile.am @@ -0,0 +1,11 @@ + +EXTRA_DIST = \ + index.docbook \ + kdirstat-main.png \ + kdirstat-config-cleanups.png \ + kdirstat-config-tree-colors.png \ + feedback-mail.png + +KDE_LANG = en +KDE_DOCS = kdirstat + diff --git a/doc/en/feedback-mail.png b/doc/en/feedback-mail.png Binary files differnew file mode 100644 index 0000000..977910d --- /dev/null +++ b/doc/en/feedback-mail.png diff --git a/doc/en/index.docbook b/doc/en/index.docbook new file mode 100644 index 0000000..6076630 --- /dev/null +++ b/doc/en/index.docbook @@ -0,0 +1,1954 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [ + <!ENTITY kdirstat '<application>KDirStat</application>'> + <!ENTITY kapp "&kdirstat;"><!-- replace |NAMELITTLE| here --> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> + + + <!-- Do not define any other entities; instead, use the entities + from kde-genent.entities and $LANG/user.entities. --> +]> +<!-- kdoctemplate v0.8 October 1 1999 + Minor update to "Credits and Licenses" section on August 24, 2000 + Removed "Revision history" section on 22 January 2001 --> + +<!-- +This template was designed by: David Rugge davidrugge@mindspring.com +with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr +and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de +of the KDE DocBook team. + +You may freely use this template for writing any sort of KDE documentation. +If you have any changes or improvements, please let us know. + +In the future, we may want to change from SGML-based DocBook to XML-based +DocBook. To make this change easier, please be careful : +- in XML, the case of the <tags> and attributes is relevant ; +- also, quote all attributes. + +Please don't forget to remove all these comments in your final documentation, +thanks ;-). +--> + +<!-- ................................................................ --> + +<!-- The language must NOT be changed here. --> + +<book lang="&language;"> + +<!-- This header contains all of the meta-information for the document such +as Authors, publish date, the abstract, and Keywords --> + +<bookinfo> +<title>The KDirStat Handbook</title> + +<authorgroup> +<author> +<firstname>Stefan</firstname> +<surname>Hundhammer</surname> +<affiliation> +<address><email>sh@suse.de</email></address> +</affiliation> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +<copyright> +<year>1999-2005</year> +<holder>Stefan Hundhammer</holder> +</copyright> +<!-- Translators: put here the copyright notice of the translation --> +<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook + and in the FDL itself on how to use it. --> +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Date and version information of the documentation +Don't forget to include this last date and this last revision number, we +need them for translation coordination ! +Please respect the format of the date (DD/MM/YYYY) and of the version +(V.MM.LL), it could be used by automation scripts. +Do NOT change these in the translation. --> + +<date>02/02/2002</date> +<releaseinfo>0.1.01</releaseinfo> + + +<!-- Abstract about this handbook --> + +<abstract> +<para> +&kdirstat; is a graphical disk usage utility, very much like the Unix "du" command, +plus some cleanup facilities to reclaim disk space. +</para> +</abstract> + +<!-- This is a set of Keywords for indexing by search engines. +Please at least include KDE, the KDE package it is in, the name + of your application, and a few relevant keywords. --> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdeutils</keyword> +<keyword>utilities</keyword> +<keyword>file system</keyword> +<keyword>disk usage</keyword> +<keyword>cleanup</keyword> +</keywordset> + +</bookinfo> + +<!-- The contents of the documentation begin here. Label +each chapter so with the id attribute. This is necessary for two reasons: it +allows you to easily reference the chapter from other chapters of your +document, and if there is no ID, the name of the generated HTML files will vary +from time to time making it hard to manage for maintainers and for the CVS +system. Any chapter labelled (OPTIONAL) may be left out at the author's +discretion. Other chapters should not be left out in order to maintain a +consistent documentation style across all KDE apps. --> + + + + +<chapter id="overview"> +<title>Overview</title> + +<!-- The introduction chapter contains a brief introduction for the +application that explains what it does and where to report +problems. Basically a long version of the abstract. Don't include a +revision history. (see installation appendix comment) --> + +<para> +&kapp; is a graphical disk usage utility. It shows you where all your disk +space has gone and tries to help clean it up. +</para> + + +<sect1 id="screenshot"> +<title>Screen Shot</title> + +<para> + +<screenshot> +<screeninfo>The &kapp; main window</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="kdirstat-main.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Main window screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> +</sect1> + + + + +<sect1 id="features"> +<title>Features</title> + + +<sect2><title>Display Features</title> +<itemizedlist> + +<listitem><para> +Graphical and numeric display of used disk space +</para></listitem> + +<listitem><para> +Treemap display of used disk space +</para></listitem> + +<listitem><para> +Files kept apart from directories in separate <Files> items to prevent +cluttering the display +</para></listitem> + + +<listitem><para> +All numbers displayed human readable - e.g., 34.4 MB instead of 36116381 Bytes +</para></listitem> + + +<listitem><para> +Reasonable handling of sparse files - only blocks that are actually allocated +are added up to the total sums. +</para></listitem> + + +<listitem><para> +Reasonable handling of (regular) files with multiple hard links - their size is +divided by their number of hard links, thus evenly distributing their size over +the directories they are linked to -- and, more importantly, not adding the same +file up several times. +</para></listitem> + + +<listitem><para> +Different colors in the directory tree display to keep the different tree +levels visually apart +</para></listitem> + + +<listitem><para> +Display of latest change time within an entire directory tree - you can easily +see what object was changed last and when. +</para></listitem> + +</itemizedlist> +</sect2> + + +<sect2><title>Directory Reading</title> +<itemizedlist> + +<listitem> +<para> +Stays on one file system by default - reads mounted file systems only on +request. +</para> +<para> +You don't care about a mounted /usr file system if the root file +system is full and you need to find out why in a hurry, nor do you want to scan +everybody's home directory on the NFS server when your local disk is full. +</para> +</listitem> + + +<listitem><para> +Network transparency: Scan FTP or Samba directories - or whatever else +protocols KDE support. +</para></listitem> + +<listitem><para> +PacMan animation while directories are being read. +OK, this is not exactly essential, but it's fun. +</para></listitem> + + +</itemizedlist> +</sect2> + + +<sect2><title>Cleaning up</title> +<itemizedlist> + +<listitem><para> +Predefined cleanup actions: Easily delete a file or a directory tree, move it +to the KDE trash bin, compress it to a .tar.bz2 archive or simply open a shell +or a Konqueror window there. +</para></listitem> + + +<listitem><para> +User-defined cleanup actions: Add your own cleanup commands or edit the +existing ones. +</para></listitem> + +<listitem><para> +"Send mail to owner" report facility: Send a mail requesting the owner +of a large directory tree to please clean up unused files. +</para></listitem> + + +</itemizedlist> +</sect2> + + +<sect2><title>Misc</title> +<itemizedlist> + +<listitem><para> +Feedback mail facility: Rate the program and tell the authors your opinion +about it. +</para></listitem> + +</itemizedlist> +</sect2> + +</sect1> + + +<sect1 id="more-screen-shots"> +<title>More Sceen Shots</title> + + +<sect2><title>Configuring cleanup actions</title> +<para> +<screenshot> +<screeninfo>Configuring cleanup actions</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="kdirstat-config-cleanups.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Configure cleanup actions window screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> +</sect2> + + +<sect2><title>Configuring tree colors</title> +<para> +<screenshot> +<screeninfo>Configuring tree colors</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="kdirstat-config-tree-colors.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Configure tree colors window screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> +</sect2> + +<sect2><title>Feedback mail</title> +<para> +<screenshot> +<screeninfo>Feedback mail</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="feedback-mail.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Feedback mail window screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> +</sect2> + +</sect1> +</chapter> + + + + +<chapter id="basic_usage"> +<title>Basic Usage</title> + +<sect1 id="invoking"> +<title>Invoke &kdirstat;</title> + +<para> +Start &kdirstat; from the KDE menu, right-click a directory in a +Konqueror window or type +<userinput>kdirstat</userinput> or +<userinput>kdirstat <directory-name></userinput> in a shell +window or at KDE's <guibutton>Run command</guibutton> prompt +(<keycap>Alt-F2</keycap>). +</para> +</sect1> + +<sect1 id="select_dir"> +<title>Select a Directory</title> + +<para> +&kdirstat; will prompt for a directory if you didn't specify one when starting +it. You can specify local directories as well as URLs of remote locations - +<userinput>kdirstat /usr/lib</userinput> works as well as +<userinput>kdirstat ftp:/ftp.myserver.org/pub</userinput>. +</para> +<para> +In any case, &kdirstat; will start reading that directory. That might take a +while, but you can work with the program during all that time. +</para> +</sect1> + +<sect1 id="find_out_where"> +<title>Find out what Uses up all the Disk Space</title> + +<para> +Look at the "Subtree Total" column or wait until a subtree is finished reading +and look at the graphical percentage bar display to find out what directory +subtee takes up how much disk space. Use the open / close icons (plus and minus +signs or small arrows, depending on how you set up your KDE) or double-click an +item to open or close it. +</para> +<para> +Notice how files at any directory level are kept apart from subdirectories - +there is a separate <Files> entry for them. This way, you can easily tell +how much disk space the files are using up in relation to the subdirectories +and their respective files. +</para> +</sect1> + +<sect1 id="do_something"> +<title>Do Something about it</title> + +<para> +Once you found out where all your disk space goes, do something about it - this +is probably why you are using this program in the first place. You have several +options: +</para> + +<itemizedlist> +<listitem> +<para> +Go to a computer hardware store and buy a new hard disk. +This is probably not what you want. ;-) +</para> +</listitem> + +<listitem> +<para>Tell the owner of that file or directory to please clean up. +You can use &kdirstat; for that: Mark that file or directory (i.e., left-click +on it) and select <guibutton>Send Mail to Owner</guibutton> +from the context menu (right-click), from the tool bar (the envelope icon) or +from the <guibutton>Report</guibutton> menu. +</para> +<para> +A precomposed message will open in your +<link linkend="mail_client">favourite mail client</link>. +You can edit that text before actually sending it. The recipient of +the mail is the user who owns the file or directory you marked - but of course +you can edit that, too in the mail client. +</para> +<para> +The mail will contain those items that are currently displayed open from the +marked item on. If you want to include more items, open the respective +directories; if you want less, close them. Of course you can always delete +lines in the mail client if you find them irrelevant - there is no use +complaining about some 367 byte files along with others that take several +megabytes. +</para> + +</listitem> + +<listitem> +<para> +Invoke a "cleanup" action. There are several predefined ones, and you can +define your own. Use the context menu, the tool bar or the <guibutton>Clean +Up</guibutton> menu to find out which are available. +</para> +<para> +For some cleanup actions you will have to wait until the directory +tree is completely read until you can activate them. If a cleanup action +doesn't get enabled even then, the type of item you selected is inappropriate +for that kind of action: Some actions can only performed on directories, while +others can only be performed on files. Only very few actions work for +<Files> pseudo entries since they don't have a real counterpart in the +file system. +</para> +</listitem> +</itemizedlist> + +</sect1> + +</chapter> + + +<chapter id="treemaps"> +<title>Treemaps</title> + + +<sect1 id="treemap_intro"> +<title>Quick Introduction to Treemaps</title> + + +<sect2 id="what_are_treemaps"> +<title>What is it?</title> + +<para> +The shaded rectangles you can see in the lower half of the &kdirstat; main +window are called a "treemap". This is just another way of displaying items in +a tree that each have a numerical value, such as a file size. +</para> + +<para> +Each rectangle corresponds to a file or directory on your hard disk. The larger +the rectangle (or, rather, the larger its area), the larger the file. +</para> + +</sect2> + + + +<sect2 id="how_to_use_treemaps"> +<title>How to Use Treemaps</title> + +<para> +Look at the largest rectangles. Click on one, and it is selected - both in +the treemap view and above in the tree view (the list above). You can now see +what file or directory that is - both in the tree view above and in the status +line below. +</para> + +<para> +Find the largest rectangles, identify them, ant decide what to do with them: +Keep them, delete them, whatever. Use the cleanup actions like in the tree +view. The right mouse button opens a context menu that contains cleanup actions. +</para> + +<para> +The shading gives hints about which files belong together in directories. The +bright spots indicate about where the center of parent directories is. +</para> + +</sect2> + + + +<sect2 id="treemap_advantages"> +<title>Pros and Cons of Treemaps</title> + +<para> +Treemaps are good for finding single large files, possibly very deeply nested +in the directory hierarchy. They don't help very much if lots of small files +clutter up a directory - use the tree view (the list) above the treemap for +that. +</para> + +<para> +The treemap by itself view doesn't give away very much information other than +relative file sizes. It can tell you where large files are, even if they are +very deeply hidden in subdirectories. You always see all files at once, not +only the relative sizes of subdirectories against each other like in the tree +view. Click on a file to see more details in the tree view above. +</para> + +<para> +Bottom line: Both the treemap and the tree view have their strenghs and +weaknesses. Use a combination of both to make best use of either's benefits. +</para> + +</sect2> + + + +<sect2 id="getting_rid_of_treemaps"> +<title>How to Get Rid of it</title> + +<para> +If you need the screen space for the tree view (the list) or if you find it +takes too long to update the tree view each time you delete a file, you can +drag the splitter between the tree view and the treemap all the way down. The +treemap doesn't get rebuilt below a certain minimum size, thus it doesn't eat +performance any more. Alternatively, uncheck "show treemap" in the "treemap" +menu or simply hit <keycap>F9</keycap>. +</para> + +</sect2> +</sect1> + + + +<sect1 id="treemap_actions"> +<title>Treemap Related Actions</title> + + +<sect2 id="treemap_mouse_actions"> +<title>Mouse Actions in the Treemap</title> + +<itemizedlist> + +<listitem><para> +A single click with the left mouse button selects the clicked file or directory +both in the treemap and in the tree view. +</para></listitem> + +<listitem><para> +A single click with the middle mouse button selects the parent of the clicked +file or directory. +</para></listitem> + +<listitem><para> +A single click with the right mouse button opens the context menu. +</para></listitem> + +<listitem><para> +A double click with the left mouse button zooms the treemap in at the clicked +file or directory: The treemap is redisplayed with the near-topmost ancestor of +the clicked file or directory as the root. +</para></listitem> + +<listitem><para> +A double click with the middle mouse button zooms out after zooming in. +</para> +<para> +If the treemap is not zoomed in at all, it is simply rebuilt to fit into the +available screen space without the need for scrollbars. This is mainly useful +if automatic treemap resizing (the default) is switched off. +</para></listitem> + +<listitem><para> +Dragging the splitter above the treemap not only resizes the treemap subwindow, +it also rebuilds the treemap and makes it fit into the available space. +</para></listitem> + +<listitem><para> +You can drag the splitter all the way down to deactivate the treemap +alltogether. Below a minimum size the treemap will not be updated any more, so +it doesn't cost any performance. +</para></listitem> + +</itemizedlist> + +</sect2> + + +<sect2 id="treemap_menu_actions"> +<title>Treemap Menu Actions</title> + +<para> +Most treemap mouse actions have counterparts in the "treemap" menu. +</para> + +<para> +In addition to that, "show treemap" in the "treemap" menu toggles display of +the treemap subwindow. If disabled, the treemap is really inactive and doesn't +cost any performance. +</para> + +</sect2> +</sect1> + + +<sect1 id="treemap_in_depth"> +<title>More Information about Treemaps</title> + +<sect2 id="simple_treemap_construction"> +<title>How a Simple Treemap is Constructed</title> + +<para> +In its most basic form, construction of a treemap is very easy: +</para> + +<para> +First, you need a tree where each node has an associated value. Directory trees +with their accumulated file sizes are a very natural example. However, the tree +needs to be complete with all accumulated values before anything can be done - +that's why &kdirstat; doesn't display a treemap while directories are being +read. +</para> + +<para> +Decide upon an direcion in which to split the available area initially. Since +normally the treemap subwindow is wider than it is high, we first split +horizontally. +</para> + +<para> +Split the area so each toplevel directory gets an area proportional to its +accumulated size (i.e., its own size plus the size of all its children, +grandchildren etc.). +</para> + +<para> +For each rectangle thus constructed, repeat the process for each directory +level, but change direction for each level. For example, the second level will +be split vertically, the third again horizontally etc. +</para> + +<para> +This basic algorithm as well as the idea of treemaps at all was introduced by +Ben Shneiderman quite some years ago. +</para> + +</sect2> + + + +<sect2 id="squarified_treemaps"> +<title>Squarified Treemaps</title> + +<para> +One major drawback of the simple treemap algorithm is that it usually results +in lots of very thin, elongated rectangles that are hard to point at with the +mouse and hard to compare visually against each other. This is why &kdirstat; +uses "squarified" treemaps as described by Mark Bruls, Kees Huizing, and Jarke +J. van Wijk of the Technical University of Eindhoven in the Netherlands. The +basic idea is to improve the aspect ratio of the resulting rectangles, thus to +make them more "square-like". Even though this doesn't always work out +perfectly, it usually improves things a lot: There are normally very few (if +any) thin, elongated rectangles in such a squarified treemap. +</para> + +</sect2> + + +<sect2 id="cushioned_treemaps"> +<title>The Shading: Cushioned Treemaps</title> + +<para> +Squarifying a treemap comes at a cost: It makes the structure of the underlying +tree even less obvious for the user. Where simple treemaps change direction for +each level of subdivision, sqarified treemaps change direction within each +level. The result are clusters of more or less square-like rectangles. The only +hint about the tree structure that is given is that larger rectangles are near +the left and at the top of each level. +</para> + +<para> +Thus, &kdirstat; uses a technique described by Jarke J. van Wijk and Huub van +de Wetering of the TU Eindhoven, NL: "Cushioned" treemaps. This is the 3D-like +shading you can see in &kdirstat;'s treemaps: It gives each rectangle within +the treemap (each "tile") a cushion-like impression. This is not just for +pretty looks, its main purpose is to group files optically together. +</para> + +</sect2> + + +<sect2 id="treemaps_optimizations"> +<title>&kdirstat;'s own Treemap Improvements</title> + +<para> +The squarification algorithm requires items to be sorted by size. A Linux/Unix +directory tree, however, usually has lots of items; a full-blown Linux +installation can easily consist of 150,000+ (!) files and directories. The best +sort algorithms (heap sort, quick sort) still have a cost in the order of +n*ln(n), i.e. they are proportional to the product of the number of items times +their logarithm. +</para> + +<para> +Likewise, the cushion shading algorithm requires relatively expensive +floating-point arithmetics for each individual pixel of each treemap tile (even +though, by the way, it is very efficient for a 3D-shading algorithm - no +expensive sinus/cosinus etc. calculation required). +</para> + +<para> +On the other hand, most items in large directory trees are so tiny they cannot +be seen at all. &kdirstat; simply omits everything that will result in treemap +tiles less than a predefined (3*3 pixels) size - they are pretty useless for +the purposes of &kdirstat;'s users anyway. Those tiny thingies may end up in +some featureless grey space in the treemap display. +</para> + +<para> +So don't wonder if you click on some grey pixels and &kdirstat; insists they +belong to a rather high-level directory: &kdirstat; simply means to tell you +that those pixels correspond to some small stuff in that directory. Use the +tree view (the list) above the treemap for more detailed information. +</para> + +</sect2> + +<sect2 id="treemaps_credits"> +<title>Credits and Further Reading about Treemaps</title> + +<itemizedlist> + +<listitem><para> +SequoiaView gave the inspiration for treemaps within &kdirstat;. SequoiaView is +a MS Windows (that's the bad part) program created at the TU Eindhoven, NL. It +introduced cushion treemaps and later squarified cushion treemaps. Its purpose +is very close to &kdirstat;'s. If you are looking for a &kdirstat;-like program +on that "other" ;-) platform, go for SequoiaView: + +<ulink url="http://www.win.tue.nl/sequoiaview"> +http://www.win.tue.nl/sequoiaview +</ulink>. + +</para> +<para> +Needless to say, &kdirstat; users should easily be able to simply mount their +MS Windows partitions and use &kdirstat; to clean up those as well. The only +acceptable excuse ;-) for not doing this might be NTFS partitions (no reliable +write access from Linux to those yet) or single-OS MS Windows machines. +</para></listitem> + +<listitem><para> +Ben Shneiderman invented treemaps - a truly intuitive way of visualizing +numerical contents of a tree. For more information, see + +<ulink url="http://www.cs.umd.edu/hcil/treemaps/"> +http://www.cs.umd.edu/hcil/treemaps/ +</ulink>. +</para></listitem> + +<listitem><para> +Jarke J. van Wijk and Huub van de Wetering from the TU Eindhoven, NL wrote a +paper called "Cushion Treemaps: Visualization of Hierarchical Information". It +is available in PDF format at + +<ulink url="http://www.win.tue.nl/~vanwijk/"> +http://www.win.tue.nl/~vanwijk/ +</ulink>. +</para></listitem> + +<listitem><para> +Mark Bruls, Kees Huizing and Jarke J. van Wijk from the TU Eindhoven wrote a +paper called "Squarified Treemaps". It is also available in PDF format at +<ulink url="http://www.win.tue.nl/~vanwijk/"> +http://www.win.tue.nl/~vanwijk/ +</ulink>. +</para></listitem> + +<listitem><para> +Alexander Rawass had written a previous implementation of treemaps for +&kdirstat;. Even that part has been completely replaced for various reasons +(performance, integration into the &kdirstat; main application, memory +consumption, stability, user interface conformance, lack of maintenance), it +had proven that treemaps are a useful addition for a program like &kdirstat;. +</para></listitem> + +<listitem><para> +Frederic Vernier and Laurence Nigay from the University of Grenoble, France +wrote a paper called "Modifiable Treemaps Containing Variable-Shaped Units" +(URL unknown, sorry). They also wrote a MS Windows programm called "parent" +that uses a mixture of treemaps and file lists within individual treemap +tiles. +</para><para> +Personally, I don't like that approach very much - I find that display very +cluttered and confusing (that is why I didn't adopt anything like that for +&kdirstat;). But this is just my personal opinion that others may or may not +share. +</para></listitem> + +</itemizedlist> + +</sect2> +</sect1> +</chapter> + + + +<chapter id="predefined_cleanups"> +<title>Predefined Cleanup Actions</title> + +<para> +&kdirstat; comes with a number of predefined cleanup actions. You can configure +them all to your personal preference, and you can add your own. Here is what +the predefined cleanup actions do: +</para> + +<sect1 id="cleanup_open_in_konqueror"> +<title>Open in Konqueror</title> + +<para> +This opens the selected item in a Konqueror window. +</para> +<para> +You can use Konqueror to delete it (but then, you can also do that more easily +from within &kdirstat;), you can move it to another place or you can examine it +more closely. +</para> +<para> +If the selected item is a known MIME type, this will open the appropriate +application. For example, if you invoke +<guibutton>Open in Konqueror</guibutton> on a PNG image, Konqueror will +immediately start an image viewer and display that image. +</para> +<para> +This is the Swiss army knife of cleanup actions: You can do a lot of different +things with it. Thus, &kdirstat; cannot know if and when it makes sense to +re-read that directory - you will have to do that manually: +Select <guibutton>Refresh selected</guibutton> from the context menu +(right-click) or from the <guibutton>File</guibutton> menu. +</para> +</sect1> + + +<sect1 id="cleanup_open_in_terminal"> +<title>Open in Terminal</title> + +<para> +This opens a terminal window in the directory of the selected item. +</para> + +<para> +Use this to issue a few shell commands in that directory, then simply close +that shell window. You can easily open a new one in a different directory if +you need one, so you might want not to bother to repeatedly type +<userinput>cd</userinput> with lenghty paths - simply close that shell and open +a new one at the new location (type <keycap>Ctrl</keycap>-<keysym>T</keysym>. +</para> +<para> +As with the <guibutton>Open in Konqueror</guibutton> cleanup action described +above, you must manually re-read the directory's contents if you make +changes. Otherwise they will not be reflected in &kdirstat;'s display. +</para> +</sect1> + + +<sect1 id="cleanup_compress"> +<title>Compress</title> + +<para> +This compresses the selected directory to a .tar.bz2 archive. +</para> + +<para> +For example, a subdirectory +<userinput>/work/home/kilroy/loveletters</userinput> will become a compressed +archive <userinput>/work/home/kilroy/loveletters.tar.bz2</userinput>. +The directory is removed once the compressed archive is successfully created +(but of course not if that failed). +</para> +<para> +Any existing archive of the same name will silently be overwritten. +</para> +<para> +Remember that Konqueror and related utilities can use that kind of archive +transparently; there is no need to unpack it if you want to read a file in that +archive. Simply click into the archive in Konqueror. +</para> + +<para> +If you prefer .tgz archives to .tar.bz2, change the command line in the +<link linkend="configuring_cleanups">cleanup settings</link>. With .tar.bz2, +this is +</para> +<para> +<userinput> +cd ..; tar cjvf %n.tar.bz2 %n && rm -rf %n +</userinput> +</para> +<para> +For .tgz archives, change this to +</para> +<para> +<userinput> +cd ..; tar czvf %n.tgz %n && rm -rf %n +</userinput> +</para> +<para> +But you might think twice before doing that: "bzip2" (for .tar.bz2) compresses +a lot more efficient than ordinary "gzip" (for .tgz or .tar.gz), and most +systems support that just as well. It's just a matter of getting used to typing +<userinput>tar cjvf</userinput> rather than <userinput>tar czvf</userinput> for +creating an archive or <userinput>tar xjvf</userinput> rather than <userinput>tar +xzvf</userinput> for unpacking it. +</para> + +</sect1> + + +<sect1 id="cleanup_make_clean"> +<title>make clean</title> + +<para> +This issues a <userinput>make clean</userinput> command in the selected +directory. +</para> +<para> +This is useful if you build software from source frequently. After successfully +installing the software (<userinput>make install</userinput>), there is no +need to keep the built binaries around in the source directory any longer. On +the other hand, people frequently forget to clean up those directories, so you +can do that from within &kdirstat; with a few mouse clicks. +</para> +</sect1> + + +<sect1 id="cleanup_clean_trash"> +<title>Delete Trash Files</title> + +<para> +This deletes files that are usually superfluous, such as editor backup files or +core dumps in the selected directory and in any of its subdirectories. +</para> +<para> +By default, the following types of files are deleted: +</para> +<itemizedlist> +<listitem><para>Object files left over from compiling software: *.o</para></listitem> +<listitem><para>Editor backup files: *~ *.bak *.auto</para></listitem> +<listitem><para>Core dump files: core</para></listitem> +</itemizedlist> + +<para> +Of course, you can <link linkend="configuring_cleanups">configure this</link> +to suit your personal preferences. +</para> + +</sect1> + + +<sect1 id="cleanup_delete_to_trash_bin"> +<title>Delete (to Trash Bin)</title> + +<para> +This invokes the KDE standard "delete" operation, i.e. the selected file or +directory is moved to the KDE trash bin. +</para> +<para> +Even though this doesn't help to reclaim disk space right away, it is a safe +method of deleting. Use this action for anything you want to get rid of and +then review your actions by looking into the KDE trash bin. If you are really +sure, select <guibutton>Empty Trash Bin</guibutton> there. Until that point, +you can always move those items back to where they came from. +</para> +<para> +You might consider not using this cleanup action if you are cleaning up a +directory on a different file system than your home directory: In that case +that "moving to trash" involves copying the items (and then deleting them at +the original location) which might take a while. +</para> +<para> +Notice that when moving an item to trash is not successful, &kdirstat; will +still falsely display that item as deleted even though it's still there. Use +<guibutton>Refresh selected</guibutton> from the context menu to update the +display manually. Read <link linkend="assume_deleted">here</link> why. +</para> +</sect1> + + +<sect1 id="cleanup_hard_delete"> +<title>Delete (no way to undelete!)</title> + +<para> +This is a real delete, not simply moving something to the trash bin. It's +quicker, and disk space is reclaimed immediately, but there is no way to +recover if you made a mistake. You will be prompted for confirmation when you +invoke this. +</para> +<para> +You can <link linkend="confirmation">change the configuration to not prompt for +confirmation</link>, but don't blame me if anything goes wrong after you did that. +</para> +<para> +As with <guibutton>Delete (to Trash Bin)</guibutton>, you will need to manually +re-read a directory if this went wrong (usually due to insufficient permissions) +- &kdirstat;'s display is out of sync with the hard disk if that happens. +Read <link linkend="assume_deleted">here</link> why. +</para> +</sect1> + + +</chapter> + +<chapter id="configuring_cleanups"> +<title>Configuring Cleanup Actions</title> + + +<para> +Select <guibutton>Configure &kdirstat;...</guibutton> from the +<guibutton>Settings</guibutton> menu and switch to the +<guibutton>Cleanups</guibutton> page: +</para> + +<para> +<screenshot> +<screeninfo>Configuring cleanup actions</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="kdirstat-config-cleanups.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Configure cleanup actions window screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + +<sect1 id="config_cleanups_reference"> +<title>Reference</title> + +<para> +Select the cleanup action you want to configure from the list at the left +side. You might need to check <guibutton>Enabled</guibutton> before you can +make any changes. +</para> + +<para> +Enter a title in the <guibutton>Title</guibutton> field. You should mark one of +the characters in the title with an ampersand ('&') to provide a keyboard +shortcut in the menus. +</para> + +<para> +Enter a shell command in the <guibutton>Command line</guibutton> field. The +command will be invoked with <userinput>/bin/sh</userinput>, so you can use +everything the default shell provides - including pipelines, logical 'and' or +'or' ('&&' or '||', respectively) or multiple commands separated by +semicolons. Use '%p' for the full path (or URL) of the currently selected file +or directory or '%n' for the name without path. '%t' will be expanded to the +full path name of the KDE trash directory (usually ${HOME}/Desktop/Trash, but +since this tends to change between different KDE versions it is safer to use +'%t'). +</para> +<para> +&kdirstat; +will always change directory to the selected item, so there is no need to +manually add a <userinput>cd</userinput> command to the command line. +</para> +<para> +Commands are started in the background if possible, so don't add an extra +ampersand '&'. +</para> + +<para> +Check <guibutton>Recurse into subdirectories</guibutton> if the command should +be called for each subdirectory of the selected directory. Whether or not this +is useful depends on the kind of command you entered: A <userinput>make +clean</userinput> command usually takes care of that internally, while it's a +lot easier to use <userinput>rm -f *.bak</userinput> and let &kdirstat; handle +subdirectories rather than using a more complex <userinput>find ... | xargs +...</userinput> command. +</para> + +<para id="confirmation"> +Check <guibutton>Ask for confirmation</guibutton> if you want to prompt the +user for confirmation every time he invokes that cleanup action (but not for +each recursive subdirectory!). But beware: Having to confirm a lot of such +prompts tends to make users unattentive. They begin to blindly confirm +everything out of habit. Thus, use confirmations only when really necessary. +</para> + +<para> +Check the category of objects this cleanup action works for. Not all commands +make sense for both files and directories. <Files> pseudo entries are a +very special case: They don't have a real counterpart on the hard disk. You can +safely check the <Files> category for actions that require changing +directory to somewhere and then execute a command there, but there is no use +trying to delete such a <Files> entry. +</para> + +<para> +Choose between <guibutton>On local machine only ('file:/' protocol)</guibutton> +and <guibutton>Network transparent (ftp, smb, tar, ...)</guibutton>. +Most commands run locally only. There are only a few exceptions: For example, +you can open a remote location in many KDE applications, e.g., Konqueror. +</para> + +<para> +Select a <guibutton>Refresh Policy</guibutton> to tell &kdirstat; how to update +its display after the cleanup action has been invoked: +</para> + +<itemizedlist> + +<listitem> +<para> +<guibutton>No refresh</guibutton>: Don't refresh the display. Either the +cleanup action doesn't change the directory tree anyway or it is unknown when +or how - or you don't care. +</para> +<para> +Cleanup actions with this refresh policy are the only ones that can be invoked +while the respective directory subtree is being read. All others can only be +started once reading is finished. +</para> +</listitem> + +<listitem> +<para> +<guibutton>Refresh this entry</guibutton>: Refresh the directory branch the +cleanup action was selected with. This is the most useful refresh policy for +cleanup actions that delete a number of items from a directory tree, for +example <guibutton>Delete Trash Files</guibutton>. +</para> +<para> +If this refresh policy is selected, the command is not started in the +background: &kdirstat; has to wait for it to finish so the directory display +can be refreshed at the proper time. +</para> +</listitem> + +<listitem> +<para> +<guibutton>Refresh this entry's parent</guibutton>: Similar to +<guibutton>Refresh this entry</guibutton>, but one level higher up. Useful for +cleanup actions that delete the selected item but create a new one on the same +level, for example the <guibutton>Compress</guibutton> standard cleanup: The +original directory is deleted, but a .tar.bz2 file is created instead. +</para> +<para> +If this refresh policy is selected, the command is not started in the +background: &kdirstat; has to wait for it to finish so the directory display +can be refreshed at the proper time. +</para> +</listitem> + +<listitem> +<para id="assume_deleted"> +<guibutton>Asume entry has been deleted</guibutton>: Don't really re-read +anything from disk, but assume the cleanup action deletes the selected +item, thus simply remove that item from the directory tree's representation in +&kdirstat;'s internal data structures. +</para> +<para> +This is much faster than any real refresh, but it might cause the internal data +structures to get out of sync with the hard disk if the cleanup action fails and +doesn't really delete the selected item. In this case, the user will have to +manually re-read that directory branch. +</para> +</listitem> +</itemizedlist> + + +</sect1> + +<sect1 id="config_cleanups_example"> +<title>Examples</title> + +<sect2> +<title>Open in Emacs</title> + +<para> +This is a trivial example that shows you how to add a new cleanup action that +opens a file in Emacs (or any other editor of your choice). +</para> + +<para> +Select one of the unused user-defined cleanup actions from the list. Make sure +<guibutton>Enabled</guibutton> is checked. +</para> + +<para> +Enter <userinput>Open in &Emacs</userinput> in the +<guibutton>Title</guibutton> field. Notice the '&': This marks the letter +'E' as this cleanup action's keyboard shortcut. +</para> + +<para> +Enter <userinput>emacs %p</userinput> in the <guibutton>Command +line</guibutton> field. +</para> + +<para> +Leave both <guibutton>Recurse into subdirectories</guibutton> and +<guibutton>Ask for confirmation</guibutton> unchecked. +</para> + +<para> +Make sure only <guibutton>Files</guibutton> is checked in the <guibutton>Works +for...</guibutton> section and <guibutton>Directories</guibutton> and +<guibutton><Files> pseudo entries</guibutton> are unchecked. If you like +Emacs' "dired" mode very much, you can also leave +<guibutton>Directories</guibutton> checked, but it definitely doesn't make any +sense trying to open an editor with a <Files> entry. +</para> + +<para> +Leave <guibutton>On local machine only</guibutton> selected. If you feel like +experimenting a lot, you can try setting up Emacs so it fetches files from +remote locations, but even then most likely only the 'ftp' protocol will work. +</para> + +<para> +Leave the <guibutton>Refresh Policy</guibutton> at +<guibutton>No refresh</guibutton>. This ensures Emacs is started +in the background and you can continue working with &kdirstat; while Emacs +runs. It wouldn't make too much sense to change the command line to +<userinput>emacs %p &</userinput> and change the refresh policy to, say, +<guibutton>Refresh this entry</guibutton>: The refresh would take place +immediately after Emacs starts, and this is probably not what you want. +</para> + + +</sect2> + +<sect2> +<title>Compress</title> + +<para> +This example explains the predefined <guibutton>Compress</guibutton> cleanup +action in more detail. Remember, this cleanup action makes a compressed +.tar.bz2 archive from a directory. +</para> + +<para> +The <guibutton>Command line</guibutton> for this cleanup action is: +</para> + +<para> +<userinput> +cd ..; tar cjvf %n.tar.bz2 %n && rm -rf %n +</userinput> +</para> + +<para> +<userinput>cd ..</userinput> changes directory one level up. We don't +want to do something in the selected directory, but one level higher. +</para> + +<para> +The semicolon <userinput>;</userinput> tells the shell to execute one more +command - unconditionally, no matter if the previous command succeeded or +failed. +</para> + +<para> +<userinput>tar cjvf %n.tar.bz2 %n &&</userinput> +is where the compressed .tar.bz2 archive is created. "c" is the tar command for +"create", "j" means "use bzip2 compression", "v" is "verbose" (even though this +is strictly spoken unnecessary here), "f" means use the next argument as the +target file name rather than some default tape device (which nowadays nobody +uses any more anyway). "%n.tar.bz2" will be expanded to the name of the +selected directory without path plus "tar.bz2", "%n" will be expanded to +the name without anything else. For a directory +<userinput>/usr/lib/something</userinput> all this will result in a command +</para> +<para> +<userinput>tar cjvf something.tar.bz2 something</userinput> +</para> + +<para> +<userinput>&&</userinput> makes the shell execute the rest only if the +previous command (the <userinput>tar</userinput> command) is executed +successfully. This is used here to make sure the directory only is deleted if +we really have a .tar.bz2 archive with the same contents so we can easily +restore it when necessary. This is crucial in case there insufficient disk +space to create the archive or should we have insufficient permissions to +create the archive. +</para> + +<para> +<userinput>rm -rf %n</userinput> recursively deletes the directory +without asking or complaining. +</para> + +<para> +<guibutton>Works for...</guibutton> is enabled for directories only. Note it +wouldn't be a good idea to enable it for <Files> entries, too: The user +would rightfully expect the .tar.bz2 archive to contain the contents of the +<Files> entry only, i.e. only the files on that directory level. The +command would, however, pack the entire directory tree from the parent level on +into the .tar.bz2 file. +</para> + +<para> +The <guibutton>Refresh Policy</guibutton> is set to +<guibutton>Refresh this entry's parent</guibutton> since not only the selected +item is changed, but its parent also: It loses one child (the directory) but +gets another one (the .tar.bz2 archive). +</para> + +<para> +Please note that <guibutton>Recurse into subdirectories</guibutton> is not +checked here: the <userinput>tar</userinput> command and <userinput>rm +-rf</userinput> take care of any subdirectories. +</para> + + +</sect2> + +</sect1> + +</chapter> + + +<chapter id="feedback_mail"> +<title>Feedback Mail</title> + +<sect1 id="feedback_mail_description"> +<title>Description</title> + +<para> +<guibutton>Send Feedback Mail...</guibutton> from the +<guibutton>Help</guibutton> menu opens this dialog: +</para> + +<para> +<screenshot> +<screeninfo>Feedback mail</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="feedback-mail.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Feedback mail window screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + +<para> +You answer the questions (at least those marked as required) and add your personal +comments (in English, if you can, or in the special case of &kdirstat; +alternatively in German). +</para> + +<para> +Upon clicking on the <guibutton>Mail this...</guibutton> button, your +<link linkend="mail_client">mail client</link> opens with a +<link linkend="mail_example">precomposed mail</link>. +You can review that mail to make sure it doesn't contain anything you +don't like. When you are convinced the mail is okay and doesn't contain +anything you don't like, send it. +</para> + +<para> +With your opinion and your personal comments, you can make a contribution to +the Open Source movement - even if you are not a developer, even if you don't +have a clue how to improve or change the software. Your opinion is important, +even if you decide you don't like the program and send the mail off with "this +program is crap" checked. +</para> + +<para> +Open Source softare lives and breathes with user feedback. If you miss a +feature, tell us about it. If you consider an existing feature confusing, tell +us about it. If you find an application overloaded with features so you can't +find the ones you really need, tell us about it. +</para> + +<para> +On the other hand, if you like the program the way it is and you wouldn't like +to see it changed in any way, tell us about that, too. If you simply want to +thank those who go through the trouble writing all that software, do it. Your +input is appreciated, be it positive or negative. +</para> + +<para> +There is nothing more frustrating for an Open Source software author than that +lingering uncertainty if there is anybody out there who actually uses his +program. He may not get any response from users - does that mean nobody +uses the software, or does it mean it simply runs so good nobody has reason to +complain? You can contribute by telling him he is doing all right and he should +keep up the good work. +</para> + +<para> +In the opposite case, why not tell the author of a particular annoying program +just how annoying it is? This may shake him sober and make him reconsider his +work. +</para> + +<para> +Open Source is one of the world's greatest democracies. Make your vote! +</para> + +</sect1> + + + +<sect1 id="privacy"> +<title>Privacy</title> + +<para> +Your mail sent with <guibutton>Send Feedback Mail...</guibutton> is sent to the +authors of this program, to nobody else. No company or government institution +will get your mail address or any personal data. You might have noticed no +personal data are requested in the feedback form. In particular, you will never +receive spam e-mail of any kind because of sending feedback mail. +</para> + +<para> +We, the authors of this program, loathe spam probably even more than the +average KDE user since we get so much of it - spam robots tend to extract +e-mail addresses from source code and from web pages, so you can be sure we do +our best to make life as hard as we can on the spammers and certainly not help +them in any way. +</para> + +<para> +The purpose of all this feedback mail is to gather information about average +user satisfaction, about average opinions about an application's feature set, +an application's stability and learning curve. It's all about averages, thus no +specific user's data will ever be made available to the public - only +statistical averages over a large number of users, if at all. +</para> + +</sect1> + +<sect1 id="mail_example"> +<title>Feedback Mail Example</title> + +<para> +A typical feedback mail looks about like that: +</para> + +<para> +<screen width="60"> +<userinput>[kde-feedback] KDirStat-2.4.4 user feedback</userinput> + +<userinput><comment></userinput> +<userinput>This is where the personal comments go.</userinput> +<userinput>You may enter virtually any number of lines.</userinput> +<userinput></comment></userinput> + +<userinput>general_opinion="5/8_nice_try"</userinput> + +<userinput>features_liked="stay_on_one_filesys"</userinput> +<userinput>features_liked="feedback"</userinput> +<userinput>features_liked="pacman"</userinput> + +<userinput>stability="5/5_keeps_crashing"</userinput> +<userinput>learning_curve="5/5_still_no_clue"</userinput> +<userinput>recommend="yes"</userinput> +</screen> +</para> + + +<para> +Notice it's all plain ASCII. There is no attachment, no hidden header fields, +no information about your machine or yourself - only what you would send to +anybody else when you send a mail. +</para> + +<para> +By the way, this is also why we kept the format that simple. Many developers +today prefer XML for all kinds of data, but the end user (you) should be able +to read and understand what you send - just so you can make sure you don't send +any information you'd rather keep to yourself. +</para> + +</sect1> + +</chapter> + + +<chapter id="developers_guide"> +<title>Developer's Guide to KDirStat</title> + +<para> +Most of what you can see of &kdirstat; is one separate KDE widget that can be +used in other applications, too. Those parts of &kdirstat; are even licensed +under the LGPL, so you are even allowed to use it in commercial applications. +</para> + +<para> +The &kdirstat; sources are extensively documented. Read the documentation in +the header files for more details or use "kdoc" to generate HTML documentation +from them. +</para> + + +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + + +&reporting.bugs; + + +<qandaset id="faqlist"> + +<qandaentry id="ftp_server"> +<question> +<para> +Can I use &kdirstat; to sum up a directory on an FTP server? +</para> +</question> +<answer> +<para> +Yes. Simply specify the URL at the command line or even in &kdirstat;'s +directory selection box: +<userinput>kdirstat ftp:/ftp.myserver.org/pub</userinput> (command line) or +<userinput>ftp:/ftp.myserver.org/pub</userinput> (directory selection box). +</para> +<para> +&kdirstat; supports all protocols that KDE supports. You can even use the "tar" +protocol (does it make any sense to do that? You decide). The only restriction +is that the protocol needs to support the "list directory" service - which not +all protocols do. +</para> +<para> +If you are unsure about the syntax to use, try it in Konqueror first and look +at Konqueror's URL line. For example, to figure out how to specify a "tar" URL, +click into a "tar" archive in Konqueror and look at the resulting URL to get an +idea of what it looks like. +</para> +</answer> +</qandaentry> + + +<qandaentry id="exact_byte_size"> +<question> +<para> +How do I get the exact byte size of an entry rather than Megabytes or +Kilobytes? +</para> +</question> +<answer> +<para> +Right-click the number in the list. +</para> +</answer> +</qandaentry> + + +<qandaentry id="du_reports_different_total"> +<question> +<para> +Why does the "du" command sometimes report different +sizes than &kdirstat;? +</para> +</question> +<answer> +<para> +There are different kinds of sizes reported by different kinds of system calls +or KDE services: The byte size and the block size. +</para> +<para> +The byte size is the exact number of bytes of a file or directory. This is what +&kdirstat; uses. +</para> +<para> +The block size is the number of disk blocks allocated by a file or +directory. Most "du" commands use that. +Depending on the type of file system, parts of the last block of a +file or directory may be unused, yet reserved for it anyway. If such a file system +uses 1024 byte blocks, a file will at least need those 1024 bytes, no matter if +it is 1024, 200 or even just one byte large. That depends on the file system type +and sometimes even on how this is set up - i.e., this is highly system +specific. +</para> +<para> +&kdirstat; uses the byte size since this the only size that is reliably +returned by all kinds of system calls and KDE services alike. It only really +makes a difference in very pathological situations anyway, for example if you +have subdirectories with a large number of tiny files. +</para> +</answer> +</qandaentry> + + +<qandaentry id="sparse_files"> +<question> +<para> +What does this display mean: +<userinput> +6.3 MB (allocated: 1.3 MB) +</userinput> +</para> +</question> + +<answer> +<para> +This is a so-called "sparse file" (also known as "file with holes"). +This means that the file really is 6.3 MB large, but only 1.3 MB of that are +actually allocated - the rest are just zeroes. +</para> +<para> +This is typical for core dumps (memory images of crashed programs written to a +file named <userinput>core</userinput> or <userinput>core.*</userinput>) +or binary database files: The kernel writes those files in a way so only real +data content is allocated on disk and not the large amount of zeroes. +</para> +<para> +Technically, a sparse file is created with the regular open() system call to +open the file for writing, then using lseek() to extend the file size beyond +its previous size and then writing at least one byte. The area between the old +and the new file size becomes a "hole" in the file - it is not actually +allocated on the disk. Upon reading this area, a value of zero is returned for +each byte read. When bytes are written to that area, file system blocks are +actually allocated, possibly creating two smaller holes before and after the +area written to. +</para> +<para> +Please note that most file utilities do not deal graciously with sparse +files. Those that support them at all normally need special command line +arguments. Otherwise they tend to simply reading all bytes (including all the +zeroes from the holes) and writing them to a new location - which of course +means that the resulting file is no longer sparse, but really occupies all the +space its size indicates. This may mean that you can blow up the above 6.3 MB +core dump file from 1.3 MB disk usage (and 5 MB zeroes in holes) to really +6.3 MB disk usage. +</para> +<para> +GNU file system utilities like +<userinput>tar</userinput> and <userinput>rsync</userinput> at least support +command line options to prevent that. +GNU <userinput>cp</userinput> is a notable exception - it has a heuristic that +seems to work very well. +GUI driven file managers on the other hand tend to simply ignore this - even +the most modern and cool looking ones. +</para> +<para> +If in doubt, check your favourite file tools. Produce a core dump - they are +normally sparse files. The more memory a program uses, the more likely it is to +have large sections of zeroes in its memory image. Try this (in a shell): +<itemizedlist> + +<listitem><para> +Enable core dumps - they are usually disabled in most Linux distributions: +</para> +<para> +<userinput>ulmit -c 128000</userinput> +</para> +<para> +This sets the limit of core dump files to 128000 blocks (512 bytes each), i.e., +to 64 MB. This should be sufficient. +</para></listitem> + +<listitem><para> +Start a program with considerable memory consumption - in the background: +</para> +<para> +<userinput>xmms &</userinput> +</para></listitem> + +<listitem><para> +Make the program dump core: +</para> +<para> +<userinput>kill -ABRT %xmms</userinput> +</para> +<para> +This sends the ABORT signal to this process, terminating it with a core dump. +</para></listitem> + +<listitem><para> +Look at the core dump: +</para> +<para> +<userinput>kdirstat .</userinput> +</para> +<para> +or, for a neutral third-party program (from the Linux coreutils package): +</para> +<para> +<userinput>/usr/bin/stat core*</userinput> +</para> +<para> +(You need to multiply the "blocks" output with 512 to find out allocated disk space) +</para></listitem> + +<listitem><para> +Copy that core dump (e.g. to another directory) and look at it again. You will +be surprised how "heavy" all those zeroes suddenly have become. Try that with +several copy utilities (<userinput>/bin/cp</userinput>, file managers of your +choice). Remember to always use the sparse original, not any blown-up copies! +</para> +<para> +Moving files should always be safe (unless a file manager is really, really +stupid), but copying can easily blow up sparse files to huge assemblies of +meaningless zeroes. +</para></listitem> + +</itemizedlist> +</para> +<para> +Agreed, sparse files are rather uncommon these days, so this is usually not a +problem. Just remember &kdirstat; knows how to deal with them. ;-) +</para> +<para> +Please note that this special handling is only in effect if &kdirstat;'s +optimized read methods for local files are used (you can turn this on and off +in the <guibutton>Settings -> General</guibutton> dialog) - KDE's KIO +methods do not return this kind of information. +</para> +</answer> +</qandaentry> + + +<qandaentry id="hard_links"> +<question> +<para> +What does this display mean: +<userinput> +878.5 KB / 21 Links +</userinput> +</para> +</question> +<answer> +<para> +This means that this file has a number of hard links. &kdirstat; uses only the +respective portion of its size for its statistics - in the above case, 878.5 KB +/ 21 = 41.8 KB. When another link to this file is processed, the next 875.5/21 +KB are added to the total - and so on. +</para> +<para> +The rationale is that is makes no sense to count such a file 21 times with its +full size - this would greatly distort the statistics. For example, look at +<userinput>/usr/lib/locale</userinput> on a (SuSE) Linux system - many files +there have multiple hard links to save disk space. The total sum of that +directory on a SuSE Linux 9.2-i386 system is 40.5 MB -- as opposed to 205.6 MB +that the added-up output of <userinput>/bin/ls -lR</userinput> would suggest +(or &kdirstat; with <guibutton>use optimized local read methods</guibutton> +turned off in the <guibutton>Settings -> General</guibutton> dialog) +- sometimes, as in this example, this really makes a difference! +</para> +<para> +Technical background: In Unix/Linux file systems, files primarily have a +numeric ID, their "i-number", the index of the corresponding "i-node", the file +system's administrative information. Each directory entry of a file really is +no more than a link to that i-node. You can have the very same file under +several distinct names this way - even in different directories. The only +limitation is that this is restricted to one file system (i.e. to one disk +partition) because those i-numbers are unique only per file system. +</para> +<para> +Hard links can also introduce a whole new dimenstion of problems with +applications that create backup copies of working files - they usually only +rename the original file to a backup name and write their content to a new +file. Editors usually work that way. This however means that any additional +hard links to that file now point to the outdated backup copy - which is +normally not what is desired. Only very few applications handle this +reasonably. So the bottom line is: Use hard links only if you know very well +what you are doing. +</para> +<para> +All this is probably why symbolic links have become so much more popular in recent +years: They can also point to different file systems, even (via NFS) to +different hosts in the network. On the downside, symlinks can also be stale - +pointing into nothingness. This cannot happen with hard links: A file is only +really deleted when the last of its links is deleted (this includes open +i-nodes in memory - i.e., processes still having an open file handle to that +i-node). +</para> +<para> +Directories rely completely on hard links (this is also why &kdirstat; does not +attempt to try anything smart with multiple-hard-link directories - it would +make no sense): The ".." entries in each directory pointing to its parent is +nothing else than another hard link to that parent (named ".."), and "." is +nothing else than a hard link to itself. This is also why even a completely +empty directory has a link count of 2 - one for "." in its own directory, one +for its name in its parent directory. +</para> +<para> +Like sparse files above, regular files with multiple hard links are pretty +uncommon these days - but they are still used, and sometimes they can make a +difference, and this is why &kdirstat; has special handling for them. +</para> +<para> +Please note that this special handling is only in effect if &kdirstat;'s +optimized read methods for local files are used (you can turn this on and off +in the <guibutton>Settings -> General</guibutton> dialog) - KDE's KIO +methods do not return this kind of information. +</para> +</answer> +</qandaentry> + + +<qandaentry id="mail_client"> +<question> +<para> +I don't want to use KMail every time I send a mail with &kdirstat;. +How do I tell &kdirstat; to use a different mail client? +</para> +</question> +<answer> +<para> +Start <userinput>kcontrol</userinput> or select +<guibutton>Preferences</guibutton> in the KDE menu, then select +<guibutton>Network</guibutton> -> <guibutton>Email</guibutton> and enter +your favourite mail client in the <guibutton>Preferred Email client</guibutton> +field. +</para> +</answer> +</qandaentry> + + +<qandaentry id="tree_colors"> +<question> +<para> +How do I get rid of those many percentage bar colors? I want them all displayed +in the same color. +</para> +</question> +<answer> +<para> +Select <guibutton>Configure &kdirstat;...</guibutton> from the +<guibutton>Settings</guibutton> menu, switch to the <guibutton>Tree +colors</guibutton> page and drag the slider all the way up. +</para> +</answer> +</qandaentry> + + +</qandaset> + +</chapter> + + +<chapter id="credits"> + +<!-- Include credits for the programmers, documentation writers, and +contributors here. The license for your software should then be included below +the credits with a reference to the appropriate license file included in the KDE +distribution. --> + +<title>Credits and License</title> + +<para> +&kapp; +</para> +<para> +Program copyright 1999-2002 Stefan Hundhammer <email>sh@suse.de</email> +</para> + +<para> +Contributors: +<itemizedlist> +<listitem> + <para>Alexander Rawawss <email>alexannika@users.sourceforge.net</email> + Initial treemaps (those who currently don't work any more) + </para> +</listitem> +</itemizedlist> +</para> + +<para> +Documentation copyright 2002 Stefan Hundhammer <email>sh@suse.de</email> +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove. Commercial development should --> +<!-- replace this with their copyright and either remove it or re-set this.--> + +&underGPL; <!-- GPL License --> + +</chapter> + + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kdirstat"> +<title>How to obtain KDirStat</title> + +<para> +&kdirstat; is part of the KDE project +<ulink url="http://www.kde.org">http://www.kde.org</ulink>. + +&kdirstat; can be found on the &kdirstat; home page at +<ulink url="http://kdirstat.sourceforge.net/">http://kdirstat.sourceforge.net/</ulink> +or at the mirror site at +<ulink url="http://www.suse.de/~sh/kdirstat/">http://www.suse.de/~sh/kdirstat/</ulink> +.</para> +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<itemizedlist> +<listitem> +<para>Linux or any other Unix-type operating system.</para> +<para>As stupid as this sounds: There were quite some people complaining that +they couldn't get &kdirstat; installed on their Win9x system. Many people seem +to believe that if it has windows, it has to run on MS Windows... +</para> +</listitem> + +<listitem><para>KDE 3.x</para></listitem> + +</itemizedlist> + +<para> +All required libraries as well as &kdirstat; itself can be found on +<ulink url="http://kdirstat.sourceforge.net/">The &kdirstat; home page</ulink>. +</para> +</sect1> + + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +<para> +See file "build-howto.html" in the distribution tarball. +</para> + +</sect1> + + +</appendix> + +&documentation.index; +</book> +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: +--> + diff --git a/doc/en/kdirstat-config-cleanups.png b/doc/en/kdirstat-config-cleanups.png Binary files differnew file mode 100644 index 0000000..1c13b8a --- /dev/null +++ b/doc/en/kdirstat-config-cleanups.png diff --git a/doc/en/kdirstat-config-tree-colors.png b/doc/en/kdirstat-config-tree-colors.png Binary files differnew file mode 100644 index 0000000..40ac045 --- /dev/null +++ b/doc/en/kdirstat-config-tree-colors.png diff --git a/doc/en/kdirstat-main.png b/doc/en/kdirstat-main.png Binary files differnew file mode 100644 index 0000000..e1fdcb6 --- /dev/null +++ b/doc/en/kdirstat-main.png |
