<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY package "kdeutils">
  <!ENTITY kappname "&filelight;">
  <!ENTITY filelight "<application>Filelight</application>">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book id="filelight" lang="&language;">

<bookinfo>
   <title>The &filelight; Handbook</title>
   <authorgroup>
      <author>
         <firstname>Max</firstname>
         <surname>Howell</surname>
         <affiliation><address><email>max.howell@methylblue.com</email></address></affiliation>
      </author>
      <author>
        <firstname>Martin</firstname>
        <surname>Sandsmark</surname>
        <affiliation><address><email>martin.sandsmark@kde.org</email></address></affiliation>
      </author>
      <!-- TRANS:ROLES_OF_TRANSLATORS -->
   </authorgroup>
   <copyright><year>2006</year><holder>Max Howell</holder></copyright>
   <copyright><year>2009</year><holder>Martin Sandsmark</holder></copyright>
   <!-- Translators: put here the copyright notice of the translation -->
   <legalnotice>&FDLNotice;</legalnotice>
   <date>2013-05-25</date>
   <releaseinfo>1.20 (&kde; 4.11)</releaseinfo>
   <abstract><para>&filelight; creates an interactive map of concentric segmented-rings that helps visualize disk usage on your computer.</para></abstract>
   <!-- These may be used by search engines -->
   <keywordset>
      <keyword>KDE</keyword>
      <keyword>Filelight</keyword>
      <keyword>du</keyword>
      <keyword>disk usage</keyword>
   </keywordset>
</bookinfo>


<chapter id="introduction">
   <title>Introduction</title>
   <screenshot>
      <screeninfo>&filelight; 1.20 Screenshot</screeninfo>
      <mediaobject>
         <imageobject><imagedata fileref="radial_map.png" format="PNG"/></imageobject>
         <textobject><phrase>Screenshot</phrase></textobject>
      </mediaobject>
   </screenshot>
   <para>&filelight; allows you to quickly understand exactly where your diskspace is being used by graphically representing your file system as a set of concentric segmented-rings. You can use it to locate hotspots of disk usage and then manipulate those areas using &konqueror;.</para>
</chapter>


<chapter id="configuring">
<title>Configuring &filelight;</title>

<para>The &filelight; settings dialog has two tabs for configuring the &filelight; options. The two tabs are <guilabel>Scanning</guilabel> and <guilabel>Appearance</guilabel>. Below is a description of the settings tabs. The &filelight; settings dialog can be found by clicking <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Filelight</guimenuitem></menuchoice>.</para>

<sect1 id="scanning">
<title>Scanning</title>

<screenshot>
<screeninfo>Scanning Screenshot</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="config_scan.png" format="PNG"/></imageobject>
<textobject><phrase>Screenshot</phrase></textobject>
</mediaobject>
</screenshot>

<para>The scanning tab allows you to configure how &filelight; scans folders. The <guilabel> Do not scan these folders</guilabel> is used to exclude certain folders from your scan. This option is very useful for skipping folders that you may not have permissions to read, or folders that are part of a virtual filesystem, such as /proc. To add a folder to the list, click the <guibutton>Add...</guibutton> button, this will start a dialog where you can choose the folder of your choice from a tree view. To remove a folder simply select the folder of your choice and click the <guibutton>Remove</guibutton> button.</para>
<para>Using <guilabel>Scan across filesystem boundaries</guilabel> allows scans to enter folders that are part of other filesystems. For example, when unchecked, this will usually prevent the contents of <filename class="directory">/mnt</filename> from being scanned if you scan starting from the root folder <filename class="directory">/</filename>. 
A scan of remote filesystems, &eg; NFS or Samba mounts, can generate high network traffic. To prevent scanning them check <guilabel>Exclude remote filesystems</guilabel>. The next option <guilabel>Exclude removable media</guilabel>
prevents &filelight; from scanning removable media (&eg; &CD-ROM;s).</para>
</sect1>

<sect1 id="appearance">
<title>Appearance</title>

<screenshot>
<screeninfo>Appearance Screenshot</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="config_appear.png" format="PNG"/></imageobject>
<textobject><phrase>Screenshot</phrase></textobject>
</mediaobject>
</screenshot>

<para>The <guilabel>Appearance</guilabel> tab allows you to configure the way &filelight; looks.</para>
<para>The <guilabel>Color scheme</guilabel> section is used to choose a color scheme for &filelight;. The color schemes are <guilabel>Rainbow</guilabel>, <guilabel>System Colors</guilabel>, and <guilabel>High Contrast</guilabel>. There is also a <guilabel>Contrast</guilabel> slider to adjust the contrast of the ring segments for easier viewing.</para>
<para>The <guilabel>Use anti-aliasing</guilabel> check box is used to enable the use of anti-aliasing in the &filelight; view. Selected, this option makes the ring segments have a much cleaner look.</para>
<para>The <guilabel>Vary label font sizes</guilabel> check box is useful when you have files or folders with long names. This option will change the size of the font to allow it to fit in the view better. When this option is enabled a <guilabel>Minimum font size</guilabel> spinbox becomes available for choosing the smallest size font to scale to.
<!-- WhatsThisHelp is different, what is correcct? --></para>
<para>The <guilabel>Show small files</guilabel> option is disabled by default as small files tend to clutter the &filelight; view. Enable this option if you would like to have your small files included in the &filelight; view. These files are merged all into a single <quote>multi-segment</quote>.</para>

</sect1>
</chapter>


<chapter id="using">
<title>Using &filelight;</title>

<sect1 id="starting">
<title>Starting &filelight;</title>
<para>&filelight; can be started from the K-Menu, or from the command-line</para>

<sect2 id="starting-from-the-menu">
<title>From the K-Menu</title>
<para>
Open the &kde; program menu by clicking on the
<guiicon>big K</guiicon> icon on your
panel. This will raise the <guimenu>program menu</guimenu>. Move your
cursor up the menu to the <guimenu>Utilities</guimenu> menu item. Choose
<guimenuitem>&filelight;</guimenuitem>.
</para>
</sect2>

<sect2 id="starting-from-the-command-line">
<title>From the Command Line</title>
<para>
You can start &filelight; by typing its name on the command line.
If you give it a folder name, as in the example below, it will scan that folder.
</para>
<informalexample>
<screen>
<prompt>%</prompt><userinput><command>filelight</command> <option><replaceable>/home</replaceable></option></userinput>
</screen>
</informalexample>
</sect2>

</sect1>

<sect1 id="scanning-folders">
<title>Scanning folders</title>
<para>
Scanning a folder shows it's contents as a filemap. To scan a folder, use the scan menu, or type a &URL; straight into the location bar.
</para>
</sect1>

<sect1 id="exploring-filemaps">
<title>Exploring Filemaps</title>
<para>
Once a scan has completed you will be presented with a filemap that represents the folder you scanned. The filemap is a series of segmented-rings that expand from the center. Brightly colored segments are folders, gray segments are files. Segments are sized in proportion to their filesize. Segments can be nested, so for example, <filename class="directory">/home/mxcl</filename> will be one level outwards and within the bounds of the segment representing <filename class="directory">/home</filename>. Segments are labeled and hovering the mouse over segments will give you more details of that segment and its child segments.
</para>
<screenshot>
<screeninfo>Filemap Screenshot</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="radial_map_context_menu.png" format="PNG"/></imageobject>
<textobject><phrase>Screenshot</phrase></textobject>
</mediaobject>
</screenshot>
<para>
You can open folders with your default file manager or &konsole; using the context menu for that segment. A &MMB; click opens files by mimetype, &eg; images with <application>Gwenview</application>. You can right click a segment to get a context menu for the scanned folder with actions to copy the folder path to the clipboard or delete the folder or file. Left clicking segments will re-center the map on that segment.
</para>
</sect1>

</chapter>


<chapter id="commands">
<title>Menu and Command Reference</title>

<variablelist>
<title>The Scan Menu</title>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
</shortcut>
<guimenu>Scan</guimenu>
<guimenuitem>Scan folder..</guimenuitem>
</menuchoice></term>
<listitem><para><action>Offers a folder selection dialog so you can choose a folder to scan.</action></para></listitem>
</varlistentry>
<!--FIXME shortcut not visible in the menu, why?-->
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keysym>Home</keysym></keycombo>
</shortcut>
<guimenu>Scan</guimenu>
<guimenuitem>Scan Home folder</guimenuitem>
</menuchoice></term>
<listitem><para><action>Starts a scan of the user's home folder.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Scan</guimenu>
<guimenuitem>Scan Root folder</guimenuitem>
</menuchoice></term>
<listitem><para><action>Starts a scan of the root folder.</action></para></listitem>
</varlistentry>

<!--not in 4.11 
varlistentry>
<term><menuchoice>
<guimenu>Scan</guimenu>
<guimenuitem>Recent Scans</guimenuitem>
</menuchoice></term>
<listitem><para><action>Provides a list of your most recent scanned folders allowing quick access to these folders.</action></para></listitem>
</varlistentry-->

<varlistentry>
<term><menuchoice>
<shortcut>
<keycap>F5</keycap>
</shortcut>
<guimenu>Scan</guimenu>
<guimenuitem>Rescan</guimenuitem>
</menuchoice></term>
<listitem><para><action>Starts a new scan of the current working folder, this is useful when changes have been made to the filesystem.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
&Esc;
</shortcut>
<guimenu>Scan</guimenu>
<guimenuitem>Stop</guimenuitem>
</menuchoice></term>
<listitem><para><action>Stops the current scan.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>Scan</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits &filelight;.</action></para></listitem>
</varlistentry>

</variablelist>

<variablelist>
  <title>The View Menu</title>
    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo>
    </shortcut>
    <guimenu>View</guimenu>
    <guimenuitem>Zoom In</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Increase the view of the filemap.</action></para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo>
    </shortcut>
    <guimenu>View</guimenu>
    <guimenuitem>Zoom Out</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Decrease the view of the filemap.</action></para>
    </listitem>
    </varlistentry>
</variablelist>

<variablelist>
<title>The Go Menu</title>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Alt;<keycap>Up</keycap></keycombo>
</shortcut>
<guimenu>Go</guimenu>
<guimenuitem>Up</guimenuitem>
</menuchoice></term>
<listitem><para><action>Moves you up one step in the filesystem to the parent folder.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<!--
<shortcut>
<keycombo action="simul">&Alt;<keycap>Left</keycap></keycombo>
</shortcut>
-->
<guimenu>Go</guimenu>
<guimenuitem>Back</guimenuitem>
</menuchoice></term>
<listitem><para><action>Moves you one step back in your browsing history of the filesystem.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<!--
<shortcut>
<keycombo action="simul">&Alt;<keycap>Right</keycap></keycombo>
</shortcut>
-->
<guimenu>Go</guimenu>
<guimenuitem>Forward</guimenuitem>
</menuchoice></term>
<listitem><para><action>Moves you one step forward in your browsing history of the filesystem.</action></para></listitem>
</varlistentry>

</variablelist>

<para>Additionally &filelight; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
menu items, for more information read the sections about the <ulink url="help:/fundamentals/ui.html#menus-settings"
>Settings Menu</ulink> and <ulink url="help:/fundamentals/ui.html#menus-help">Help Menu</ulink>
of the &kde; Fundamentals.
</para>
</chapter>


<chapter id="credits">
   <title>Credits and License</title>
   <sect1 id="kapp">
      <title>&filelight;</title>
      <para>Program copyright 2006 Max B. Howell <email>max.howell@methylblue.com</email></para>
      <para>Program copyright 2008-2013 Martin Sandsmark <email>martin.sandsmark@kde.org</email></para>
      &underGPL;
   </sect1>
   <sect1 id="Documentation">
      <title>Documentation</title>
      <para>Documentation copyright 2003 Max B. Howell <email>max.howell@methylblue.com</email></para>
      <para>Documentation copyright 2009 Martin Sandsmark <email>martin.sandsmark@kde.org</email></para>
      <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
      &underFDL;
   </sect1>
</chapter>


<appendix id="installation">
    <title>Installation</title>

    <sect1 id="getting-kapp">
        <title>How to obtain &filelight;</title>
        &install.intro.documentation;
    </sect1>

    <sect1 id="Compilation">
        <title>Compilation and Installation</title>
        &install.compile.documentation;
    </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:
-->
