2 files changed, 188 insertions, 0 deletions
diff --git a/doc/konq-plugins/fsview/Makefile.am b/doc/konq-plugins/fsview/Makefile.am
new file mode 100644
index 0000000..23e96f9
--- /dev/null
+++ b/doc/konq-plugins/fsview/Makefile.am
@@ -0,0 +1,6 @@
+SUBDIRS = $(AUTODIRS)
+
+KDE_LANG = en
+KDE_DOCS = konq-plugins/fsview
+
+
diff --git a/doc/konq-plugins/fsview/index.docbook b/doc/konq-plugins/fsview/index.docbook
new file mode 100644
index 0000000..60ceef1
--- /dev/null
+++ b/doc/konq-plugins/fsview/index.docbook
@@ -0,0 +1,182 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
+"dtd/kdex.dtd" [
+<!ENTITY fsview "<application>FSView</application>">
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<article lang="&language;">
+
+<sect1 id="fsview">
+<sect1info>
+
+<authorgroup>
+<author>
+<personname><firstname>Josef</firstname>
+<surname>Weidendorfer</surname></personname>
+<address><email>Josef.Weidendorfer@gmx.de</email></address>
+</author>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS --> 
+</authorgroup>
+
+<date>2006-02-24</date>
+<releaseinfo>3.5.1</releaseinfo>
+
+<abstract>
+<para>The &fsview; Plugin for &konqueror; is another view mode for
+objects of mimetype <literal>inode/directory</literal> for local
+files. It can be viewed as an alternative to the various iconviews and
+listviews for browsing the content of your local file system.</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdeaddons</keyword>
+<keyword>konqueror</keyword>
+<keyword>plugins</keyword>
+<keyword></keyword>
+</keywordset>
+
+</sect1info>
+
+<title>&fsview; - the File System View</title>
+
+<sect2>
+<title>Introduction</title>
+
+<para>The &fsview; Plugin for &konqueror; is another view mode for
+objects of mimetype <literal>inode/directory</literal> for local
+files. It can be viewed as an alternative to the various iconviews and
+listviews for browsing the content of your local file system.</para>
+
+<para>The unique property of &fsview; is its ability to show whole
+nested folder hierarchies using a so-called tree map for graphical
+visualization. Tree maps allow for displaying metrics of objects in
+nested structures: each object is represented by a rectangle whose
+area is proportional to its metric. The sum of the children's metrics must be
+equal to or smaller than the parent object's metric.</para>
+
+<para>For &fsview;, sizes of files and folders are choosen as
+metric, where the the size of a folder is defined to be the sum of the
+sizes of its subitems. This way, big files even deep down in the
+folder hierarchy can be spotted easily be looking for large
+rectangles. So &fsview; can be looked at as a graphical and interactive
+version of the &UNIX; <command>du</command> command.</para>
+
+<para>The integration of &fsview; as part of Konqueror allows it to
+use the standard features like context file menus, and mime type
+sensitive actions. But it was choosen not to implement automatical
+update of file system changes by watching: if you delete a file shown
+in &fsview; outside of &konqueror;, you have to update manually by
+&eg; pressing <keycap>F5</keycap>. The reason for this decision is
+the potentially huge amount of files which would have to be watched
+for changes, and thus, could put an unreasonable pressure on system
+resources for a small feature.</para>
+
+</sect2>
+
+<sect2>
+<title>Visualization Features</title>
+
+<para>This section explains the graphical visualization of &fsview;
+in detail.</para>
+
+<sect3>
+<title>Item Drawing Options</title>
+
+<para>In &fsview;, an item of the tree map visualization is a rectangle
+representing a file or folder of your file system. For easier navigation,
+rectangles have a meaningful coloring and labeling options.</para>
+
+<para>The color of a rectangle, switchable via menu item
+<menuchoice><guimenu>View</guimenu><guisubmenu>Color
+Mode</guisubmenu></menuchoice> can be either
+<guimenuitem>Depth</guimenuitem> for easy detection of the nesting, or
+a color mapping of different file attributes like name, owner, group,
+or mime type.</para>
+
+<para>A rectangle can be labeled with the various attributes
+of the corresponding file or folder. For an attribute, you can
+choose, whether it should be shown at all, only if space is available,
+or if space should be taken from children (thus introducing
+errors to pure tree map drawing constrains). Additionally, you can choose
+the relative location of the label in the rectangle.</para>
+
+</sect3>
+
+<sect3>
+<title>TreeMap Drawing Algorithms</title>
+
+<para>For drawing algorithms in tree maps, the rule that the area
+is proportional to the metric of an item should hold true.
+With the tree map in &fsview;, this goal isn't always met: we draw borders
+to show the nesting of items, and this border takes space for a item
+which is possible lost for the areas of child items. Note that
+less space is lost for the border if the rectangle is quadratic.</para>
+
+<para>Similar, it is good for a better overview to let all rectangles
+at least have its name as label, taking space, too. It is an option to
+always force space for labels, or only to draw labels when empty space
+is available. In the latter case, the tool tips appearing when the
+mouse is kept over an item for some time, can help a lot. They show
+information for the item the mouse is currently over, together with
+its parent relations up to the root item of the tree map.</para>
+
+<para>How the space of an item is split into subareas for children is
+left to the implementation. It is always better to try to split areas
+in such a way that rectangles are as quadratic as possible, both for
+labeling and less space lost by borders. The best methods in this
+regard are <guilabel>Rows</guilabel>, <guilabel>Columns</guilabel>, or
+<guilabel>Recursive Bisection</guilabel>.</para>
+
+<para>You can choose the minimal area of items to be drawn via the
+menu item <menuchoice><guimenu>View</guimenu><guimenuitem>Stop at
+Area</guimenuitem></menuchoice>. Instead, a hash pattern will be drawn
+over the parents area to signal that this space is in fact occupied by
+a child.</para>
+
+</sect3>
+
+</sect2>
+
+<sect2>
+<title>User Interface</title>
+
+<para>&fsview; supports multiple selection of items, similar to the
+iconview and listview. This allows for actions to be done
+simultaneously to a set of files. A simple mouse click always selects
+a single item below the mouse pointer. Use a mouse click in
+combination with pressing the &Shift; key for range selection or the
+&Ctrl; Key for selection toggle. Note that by selecting an item, subitems can no
+longer be selected. Selecting an item will also clear the selection of all its
+parent items before.</para>
+
+<para>There is keyboard navigation available in tree maps: use
+<keycap>Left Arrow</keycap> and <keycap>Right Arrow</keycap> keys to
+move the current item between siblings, and the <keycap>Up
+Arrow</keycap> and <keycap>Down Arrow</keycap> keys to go up and down
+the nesting hierarchy. <keycap>Space</keycap> selects the item, in
+conjunction with &Shift; does range selection, and with the &Ctrl; key
+hold down simultaneously, toggles selection of the current item. Press
+<keycap>Return</keycap> to run the open action onto the current item.</para>
+
+</sect2>
+
+<sect2>
+<title>Credits and License</title>
+
+<para>Originally, &fsview; was meant as a small test application and
+usage tutorial for the TreeMap widget developed within
+<application>KCachegrind</application>.</para>
+
+<para>Copyright by Josef Weidendorfer, licensed using GPL V2.</para>
+
+&underGPL;
+&underFDL;
+
+</sect2>
+
+</sect1>
+</article>