<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "docbook/dtd/xml/4.2/docbookx.dtd" [
<!ENTITY appname "Valknut">
<!ENTITY binaryname "valknut">
<!ENTITY currentversion "0.3.10">
]>
<book>
  <bookinfo>
    <title>&appname; Manual</title>
    <author>
      <firstname>Andrew</firstname>
      <surname>Greig</surname>
    </author>
    <author>
      <firstname>Hanspeter</firstname>
      <surname>Niederstrasser</surname>
    </author>
    <edition>$Id: manual.xml,v 1.17 2005/02/13 19:15:43 mayhem Exp $</edition>
    <copyright>
      <year>2003, 2004, 2005</year>
      <holder>Andrew Greig</holder>
    </copyright>
    <copyright>
      <year>2007</year>
      <holder>Andrew Greig, Hanspeter Niederstrasser</holder>
    </copyright>
    <legalnotice><para>You can redistribute and/or modify this document under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.</para>

    <para>For the purpose of applying the GPL to this document, I consider "source code" to refer to the Docbook XML markup.</para></legalnotice>
  </bookinfo>
  <chapter id="introduction">
    <title>Introduction</title>
    <sect1 id="introduction-aboutmanual">
      <title>About this manual</title>
      <para>This manual began life when I was a new &appname; user, trying to fathom the multitudes of options the program had.  As my experience and understanding grew, it dawned on me that I should attempt to write down what I had learned, so others could avoid having such a steep learning experience.  I hoped it would also stop people repeatedly asking the same basic questions on the discussion board :)</para>

      <para>As I'm still not an expert on &appname; this document is nowhere near complete, and is very much a work-in-progress.  Your comments, suggestions and corrections are welcomed, please write to me at <email>agreig at flashmail dot com</email>.</para>

      <para>It is intended that this manual will be kept up-to-date with the latest releases of &appname;.  It is currently being updated for the 0.3.10 release.  The XML source code of this document is under svn, which can be browsed at <ulink url="http://wxdcgui.svn.sourceforge.net/viewvc/wxdcgui/trunk/valknut/valknut/docs/en/manual.xml"></ulink>.</para>
    </sect1>
    <sect1 id="introduction-about">
      <title>About &appname;</title>
      <para>&appname; is a program the uses the Direct Connect protocol.  It is compatible with other DC clients, such as the original DC from Neomodus, DC++ and derivatives.  &appname; also interoperates with all common DC hub software.</para>
      <para>&appname; was written by Mathias K&uuml;ster <email>mathen at users dot berlios dot de </email> and is licensed under the GNU GPL.  It is written in C++ and uses the cross-platform Qt (TM) library for its GUI.  &appname; compiles and runs on Linux, FreeBSD, Mac OS X and Windows.</para>
      <para>Originally, &appname; was called DCGUI, which unfortunately was very similar to the name of another Linux DC client.  It was then renamed to dcgui-qt to avoid confusion.  However, trademark problems relating to the use of 'Qt' in the name forced another name change, to the rather unique &appname;.  Most occurences of the old names have been replaced, but in some places, such as where it would cause too much disruption, the name hasn't been changed.</para>
      <para>Official development of &appname; by Mathias K&uuml;ster stopped after the release of version 0.3.7.  At this time, there were several patches floating around in the forums.  Edward Sheldrake organized them and put together the unofficial release for &appname; 0.3.8 under the project name <ulink url="http://sourceforge.net/projects/wxdcgui/">wxdcgui</ulink>.  As of this writing, work is ongoing to release version 0.3.11 in the summer of 2007.</para>
      <para>The original &appname; web site at <ulink url="http://dcgui.berlios.de/"></ulink> ceased to resolve on April 1, 2007.</para>
    </sect1>
    <sect1 id="introduction-more">
      <title>Finding out more</title>
      <itemizedlist>
        <listitem><para>Homepage: <ulink url="http://wxdcgui.sourceforge.net/"></ulink></para></listitem>
        <listitem><para>Board/Forum: <ulink url="http://sourceforge.net/forum/?group_id=181579"></ulink></para></listitem>
        <listitem><para>Mailing list: <ulink url="http://sourceforge.net/mail/?group_id=181579"></ulink></para></listitem>
      </itemizedlist>
    </sect1>
    <sect1 id="introduction-contributors">
      <title>Contributors</title>
      <para>The following people have helped make this manual possible, by providing information, text or corrections:
      <itemizedlist>
        <listitem><para>Mathias K&uuml;ster wrote the program up to and including version 0.3.7, and is the source of most facts about it.</para></listitem>
        <listitem><para>Edward Sheldrake took over the project from version 0.3.8 onward.</para></listitem>
        <listitem><para>Firechild wrote the original Bookmarks and Profiles sections.</para></listitem>
        <listitem><para>Jason Starr provided several corrections and explanations of program options.</para></listitem>
        <listitem><para>Stefan Huszics corrected my mis-capitalisation of kB, and provided bandwidth figures for some types of internet links.</para></listitem>
        <listitem><para>Hanspeter Niederstrasser rewrote the documentation for building on Mac OS X and updated the manual for releases after 0.3.7.</para></listitem>
      </itemizedlist>
      </para>
    </sect1>
  </chapter>
  <chapter id="getting">
    <title>Getting &appname;</title>
    <sect1 id="getting-packages">
      <title>Precompiled Packages</title>
      <para>Currently, for &appname; 0.3.8 and higher, only the Mac OS X version is available as a precompiled binary package.  It can be downloaded from <ulink url="http://snaggledworks.com/software/valknut/"></ulink>.  If you know of other binary releases for current &appname; please post about it at the SourceForge forum: <ulink url="http://sourceforge.net/forum/forum.php?forum_id=630918">http://sourceforge.net/forum/forum.php?forum_id=630918</ulink>.</para>
      <para>The official (Berlios hosted) &appname; 0.3.7 download page is now defunct.  This was the best place to look for pre-packaged versions of &appname; for various operating systems.</para>
      <para>Debian packages for 0.3.7 are included in the official 'sarge' stable release, and can be installed by running <command>apt-get install valknut</command>.</para>
      <para>Gentoo users can do <command>emerge &binaryname;</command>.</para>
      <para>Contributed binary packages were announced on the now defunct <ulink url="http://dcgui.berlios.de/forum/viewforum.php?f=5">distribution forum</ulink>.</para>
    </sect1>
    <sect1 id="getting-source">
      <title>Source Code</title>
      <para>Released versions of &appname; from 0.3.8 and higher are available at <ulink url="http://sourceforge.net/project/showfiles.php?group_id=181579"></ulink>.</para>
      <para>There are two parts you need, dclib and &binaryname;.</para>
      <important><para>You must compile and install dclib first, otherwise &appname; will fail to compile.</para></important>
      <para>If you really want to be on the bleeding edge you can get the latest SVN version with the following command:
        <screen>
svn co https://wxdcgui.svn.sourceforge.net/svnroot/wxdcgui wxdcgui
        </screen>
      </para>
      <para>This is a generic Subversion checkout command which will pull all modules, tags and/or branches of the project. In most cases, you will want to add '/trunk' to the HTTPS URL above to check out only the trunk (main development line).</para>
    </sect1>
  </chapter>
  <chapter id="compiling">
    <title>Compiling the source code</title>
    <para>Feel free to skip this chapter if you have a precompiled version of &appname;.  However, if you are interested in helping with development or tracking down bugs, read on.</para>
    <sect1 id="compiling-linux">
      <title>Compiling on Linux</title>
      <sect2 id="compiling-linux-prerequisites">
        <title>Development libraries needed</title>
        <itemizedlist>
          <listitem><para>libqt3</para></listitem>
          <listitem><para>pthread</para></listitem>
          <listitem><para>libxml</para></listitem>
          <listitem><para>libbz2 - not strictly required, but without it you won't be able to create or view BZip2-compressed sharelists.</para></listitem>
          <listitem><para>libssl - OpenSSL libraries if you wish to use SSL for transfers.</para></listitem>
        </itemizedlist>

        <para>Debian users may want to do <command>apt-get install libqt3-mt-dev libxml2-dev libbz2-dev libssl-dev</command>.</para>
        <para>Mandrake users would want to install libxml2-devel, libqt3 and libqt3-devel.</para>
      </sect2>
      <sect2 id="compiling-linux-dclib">
        <title>Compiling dclib</title>
        <screen>
make -f Makefile.dist
./configure --enable-debug=full
make
make install           <lineannotation>(you will probably want to run this command as root)</lineannotation>
        </screen>
      </sect2>
      <sect2 id="compiling-linux-&binaryname;">
        <title>Compiling &appname;</title>
        <screen>
make -f Makefile.dist
./configure --enable-debug=full --with-qt-dir=/usr/lib/qt3 --with-libdc=/usr/local  <lineannotation>(modify the --with-qt-dir parameter if your Qt (TM) libraries are in a different place)</lineannotation>
make
make install           <lineannotation>(you will probably want to run this command as root)</lineannotation>
        </screen>
        <para>If you get the following error: <screen>checking for Qt... configure: error: Qt (>= Qt 3.0) (headers and libraries) not found. Please check your installation!</screen> you need to check you have the necessary Qt (TM) libraries installed.  If you are certain you do, this command may work instead: <screen>./configure --with-qt-includes=/usr/include/qt3 --with-libdc=/usr/local</screen>  If you don't have directories such as these you probably haven't installed the development libraries and headers.</para>

        <para>Once &appname; has been successfully compiled and installed you can then run the program by typing <command>/usr/local/bin/&binaryname;</command></para>
      </sect2>
    </sect1>
    <sect1 id="compiling-macosx">
      <title>Compiling on Mac OS X</title>
      <para>There are two ways of running &appname; on OS X: as a native application; or as an X11 application.  The native version fits in more neatly with the standard Mac interface, wheras the X11 version requires you to run X as well.  The X11 version may feel a bit strange to those with a Mac background, but will feel familiar to those with a UNIX background.</para>
      <para>The instructions below are for Mac OS X 10.3 Panther and above and are derived from forum posts by drealynn42, Nyzeta, nieder, and others.</para>
      <para>Users migrating from Linux will note that the build uses dynamic linking.  Because Mac OS X binaries also link to system libraries, it is unwieldly to deal with static and dynamic libraries at the same time.  Furthermore, the native &appname;.app bundles eliminate the need for static linking.  For these reasons, these instructions use only dynamic linking when building &appname;.</para>
      <sect2 id="compiling-macosx-prerequisites">
        <title>Prerequisites</title>
        <para>First, you have to decide whether you wish to use the X11 or the native Aqua version of &appname;.  If building the X11 version, you have to install Apple's X11 and X11-SDK from the system install discs (X11User.pkg is on the System DVD, X11SDK.pkg is on the XCode DVD).  Alternatively, you can also install an X11 system using <ulink url="http://www.finkproject.org">Fink</ulink> (see below).</para>
        <important><para>Do not install both Apple's X11 and Fink's x11/xorg at the same time as this will cause serious issues.  Read <ulink url="http://www.finkproject.org/faq/usage-packages.php?phpLang=en#special-x11-debug">this FAQ entry</ulink> for ways to troubleshoot your X11 installation if you accidentally installed both.</para></important>
	<orderedlist>
          <listitem><para>Install XCode Tools from the CD that came with the OS.  If you don't have the disc, you can download XCode from <ulink url="http://connect.apple.com">Apple</ulink> (free registration required).  Make sure you choose to customize the install, and select all the SDK packages (EXCEPT X11-SDK IF YOU'RE NOT USING APPLE'S X11).</para></listitem>
          <listitem><para>Install Fink and FinkCommander (FinkCommander is optional but provides a graphical interface to Fink). The official Fink website is <ulink url="http://www.finkproject.org/"></ulink>. Follow the installation instructions at <ulink url="http://www.finkproject.org/download/index.php?phpLang=en"></ulink>.</para></listitem>
          <listitem><para>Run FinkCommander. Update the binary and rsync (preferred) or cvs descriptions, then find each of the packages listed below and install them.
            <itemizedlist>
              <listitem><para>bzip2</para></listitem>
              <listitem><para>bzip2-dev</para></listitem>
              <listitem><para>libpng3</para></listitem>
              <listitem><para>libxml2</para></listitem>
              <listitem><para>system-openssl</para></listitem>
              <listitem><para>qt3 if building the X11 version</para></listitem>
              <listitem><para>qt3-dev if building the X11 version</para></listitem>
              <listitem><para>xorg if building the X11 &appname; version and not using Apple's X11 release</para></listitem>
              <listitem><para>qt3mac if building the native Aqua &appname; version</para></listitem>
              <listitem><para>qt3mac-dev if building the native Aqua &appname; version</para></listitem>
            </itemizedlist>
          </para></listitem>

          <listitem><para>Download the dclib and &appname; source code.  Expand the files to somewhere convenient, for example your user directory.</para></listitem>

          <listitem><para>Open /Applications/Utilities/Terminal.app to compile dclib and &appname;.</para></listitem>
        </orderedlist>
      </sect2>
      <sect2 id="compiling-macosx-environment">
        <title>Setting up your system</title>
	<para>To compile &appname; you need to set up your environment correctly so that the compiler can find all your files.  Enter the following lines at the Terminal.app prompt:
	<screen>
export PKG_CONFIG_PATH=/tmp/dcguibuild/lib/pkgconfig:$PKG_CONFIG_PATH
export CFLAGS="-I/sw/lib/system-openssl/include -I/sw/include $CFLAGS "
export LDFLAGS="-L/sw/lib/system-openssl/lib -L/sw/lib $LDFLAGS"
	</screen>
	</para>
      </sect2>
      <sect2 id="compiling-macosx-dclib">
        <title>Compile dclib</title>
        <para><command>cd</command> to the dclib source folder. For example, if you put the <filename>dclib-&currentversion;.tar.bz2</filename> folder in your user directory, enter <command>cd <filename>dclib-&currentversion;</filename></command>. If the folder is within another folder, you will have to enter <command>cd that-folder/dclib-&currentversion;</command>. Then enter the following commands when prompted:</para>
        <screen>
make -f admin/Makefile.common
./configure --prefix=/tmp/dcguibuild
make
make install
        </screen>
	<para>This will finish installing dclib into a temporary directory.  If you plan on using the X11 version of &appname;, it might be better to replace the value after --prefix to <filename>/usr/local</filename> or some other more permanent location.</para>
      </sect2>
      <sect2 id="compiling-macosx-&binaryname;">
        <title>Compile &appname;</title>
	<sect3 id="compiling-macosx-x11">
	  <title>Compile &appname; for X11</title>
	  <para><command>cd</command> to the &appname; folder within the source folder. For example, enter <command>cd &binaryname;-&currentversion;</command>.  Then enter the following commands:
	    <screen>
make -f admin/Makefile.common
./configure --with-libdc=/tmp/dcguibuild --with-ssl-dir=/sw/lib/system-openssl
<lineannotation>-- or if you get an error about qt3 --</lineannotation>
./configure --with-libdc=/tmp/dcguibuild --with-ssl-dir=/sw/lib/system-openssl --with-extra-libs=/sw/lib --with-extra-includes=/sw/include --with-qt-dir=/sw --with-qt-includes=/sw/include/qt
make
make install
	    </screen>
	  </para>
          <para>If you get <screen>checking for X... configure: error: Can't find X includes. Please check your installation and add the correct paths!</screen> and you are using Apple's X11, the X11 SDK was probably not installed correctly. Use your XCode Install CD to install this package then try again.</para>
          <para>The &appname; program is now installed in /usr/local/bin.  Test tha the program compiled successfully by typing <command>/usr/local/bin/&binaryname;</command>.  You may get some warnings, which you can ignore.  The main thing is if the program starts up.</para>
          <para>Keep in mind that this program will only run inside X11, so X11 must be running first.  If you are using Fink's X11 (xorg or xfree86), you can also install the <filename>applex11tools</filename> package to make your X11 installation look nicer.</para>
          <para>If you have previously used the native &appname; 0.2.19 version, you will find this version feels quite different since it is run in X11, but it basically operates the same. All of your files and settings will carry over, so don't worry about losing anything.</para>
	</sect3>
	<sect3 id="compiling-macosx-native">
	  <title>Compile the native Aqua &appname;</title>
          <para><command>cd</command> to the &appname; folder within the source folder. For example, enter <command>cd &binaryname;-&currentversion;</command>.  Then enter the following:</para>
          <screen>
make -f admin/Makefile.common
./configure --with-libdc=/tmp/dcguibuild --with-ssl-dir=/sw/lib/system-openssl --enable-osx --enable-mac
<lineannotation>-- or if you get an error about qt3 --</lineannotation>
./configure --with-libdc=/tmp/dcguibuild --with-ssl-dir=/sw/lib/system-openssl --enable-osx --enable-mac --with-extra-libs=/sw/lib --with-extra-includes=/sw/include/ --with-qt-dir=/sw/lib/qt3mac --with-qt-includes=/sw/lib/qt3mac/include
make
make install-osx-standalone-app
          </screen>
	  <para>You will now have a directory called <filename>&appname;.app</filename> in the location where you are building.  To copy it to your Desktop, enter the following command <command>cp -Rp &appname;.app ~/Desktop</command>.  Once the &appname; application is copied there, you can move it to wherever you want on your computer (such as /Users/(YOURNAME)/Applications) or /Applications.</para>
	  <para>To run the native &appname;, simply double click the &appname; icon.</para>
	</sect3>
      </sect2>
      <sect2 id="compiling-macosx-troubleshooting">
        <title>Troubleshooting</title>
        <para>Upon ./configure, if you get:
          <screen>
checking for xml2-config... /usr/bin/xml2-config
checking for libxml - version >= 2.0.0... *** libxml header files (version 2.5.4) do not match
*** xml2-config (version 2.6.7)
no
configure: error: libxml2 must be installed.
          </screen>
        then there is a problem with the installed xml libraries.  Make sure that <filename>libxml2</filename> and <filename>libxml2-shlibs</filename> are both installed with FinkCommander.  Alternatively, add --disable-xmltest to the ./configure commands above (both for dclib and &appname;) to bypass the check for libxml.</para>
	<sect3 id="compiling-macosx-static">
	  <title>Building a static application on Mac OS X</title>
	  <para>While not necessary, it is possible to build &appname; as a (partial) static application on Mac OS X.  During the compilation of dclib, add the following parameters to the ./configure step: <command>--enable-static --disable-shared</command>.  When compiling &appname;, add the following code to the ./configure step: <command>--enable-link-static</command>.  This will create a &binaryname; executable with dclib built in.  However, all the other required libraries will still be dynamically linked to the executable and will still need to be present when running &appname;.</para>
	</sect3>
      </sect2>
      <sect2 id="compiling-macosx-managed">
        <title>Using a package manager to install &appname;</title>
        <para>&appname; is also available as a package within the Fink distribution.  As of this writing there are no precompiled binaries for &appname; 0.3.8 and higher, but if you wish to install from source, Fink takes care of downloading, building and installing all the necessary dependencies with a single command.  To install the X11 version of &appname; install the package <filename>&binaryname;-x11</filename>.  To install the native Aqua version, install the package <filename>&binaryname;-aqua</filename>.</para>
	<para>Once everything is finished, the X11 version can be run from Terminal.app (or an xterm) with the command <command>/sw/bin/&binaryname;</command> (Notice that it is located in /sw and not /usr/local to avoid conflicts with anything you installed on your own).  The native Aqua version installs an alias in <filename>/Applications/Fink</filename> that can be run by double-clicking it from within Finder.</para>
      </sect2>
    </sect1>
    <sect1 id="compiling-openbsd">
      <title>Compiling on OpenBSD</title>
      <para>The following commands have been used to successfully build &appname; on OpenBSD 3.6.</para>
      <sect2 id="compiling-openbsd-dclib">
        <title>Compiling dclib</title>
        <screen>
gmake Makefile.dist
LDFLAGS="-L/usr/local/lib" CFLAGS="-I/usr/local/include" ./configure
gmake
gmake install
        </screen>
      </sect2>
      <sect2>
        <title>Compiling &appname;</title>
        <screen>
gmake Makefile.dist
export PATH=$PATH:/usr/local/lib/qt3/bin-mt
LDFLAGS="-L/usr/local/lib" CFLAGS="-I/usr/local/include" ./configure --with-qt-libraries=/usr/local/lib/qt3 --with-qt-includes=/usr/local/include/X11/qt3
gmake
gmake install
        </screen>
      </sect2>
    </sect1>
    <sect1 id="compiling-debug">
      <title>Making a Debug build</title>
      <para>If &appname; crashes unexpectedly, then you can help the developers work out why by running a debug build.  The differences from a normal build are:
        <itemizedlist>
          <listitem><para>Add <computeroutput>--enable-debug=full</computeroutput> to the ./configure line for dclib.</para></listitem>
          <listitem><para>Add <computeroutput>--enable-debug=full --enable-link-static</computeroutput> to the ./configure line for &appname;.</para></listitem>
          <listitem><para>Don't run "make install" in the &binaryname; directory, instead run the program from the compilation directory, e.g. <screen>cd &binaryname;; ./&binaryname;</screen></para></listitem>
        </itemizedlist>

        If it crashes you can send Mathias the backtrace output.
      </para>
    </sect1>
    <sect1 id="compiling-bugreport">
      <title>Submitting a bug report</title>
      <para>You need to supply the following information:
        <itemizedlist>
          <listitem><para>Distribution</para></listitem>
          <listitem><para>Qt (TM) version</para></listitem>
          <listitem><para>&appname;/dclib version</para></listitem>
          <listitem><para>If it is a self compiled source or rpm (rpm distribution)</para></listitem>
          <listitem><para>Bug description</para></listitem>
        </itemizedlist>
      </para>
    </sect1>
  </chapter>
  <chapter id="running">
    <title>Running &appname;</title>
    <sect1 id="running-commandline">
      <title>Command-line options</title>
      <para>Usually you can start &appname; without any command-line options and it will work fine.  These options are mainly for testing and debugging use.</para>
      <variablelist>
        <varlistentry>
	  <term><option>--help</option></term>
	  <listitem><para>Show the list of command line options and brief help on what they do.</para></listitem>
	</varlistentry>
        <varlistentry>
          <term><option>--disable-splash</option></term>
          <listitem><para>Startup splash screen is not shown.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--disable-theme</option></term>
          <listitem><para>Turns off theme support.  Could be useful if buggy themes are making &appname; crash.</para></listitem>
        </varlistentry>
	<varlistentry>
	  <term><option>--disable-tray</option></term>
	  <listitem><para>Turns off the tray icon.  Useful if your window manager doesn't support tray icons.</para></listitem>
	</varlistentry>
        <varlistentry>
          <term><option>--check-theme</option></term>
          <listitem><para>Causes the program to display how many themes/styles are available then exit.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--disable-backtrace</option></term>
          <listitem><para>This option is only useful with debug versions of &appname;.  It will cause &appname; to write a core file if it crashes, which can be used as part of a bug report.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>-c <parameter>&lt;configpath&gt;</parameter></option></term>
          <listitem><para>Lets you specify the path where &appname; should find its configuration files.  Useful if you want to have multiple configurations, e.g. for testing.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>-v</option></term>
          <listitem><para>Enables verbose output, which shows all paths added on sharelist creation.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>-vv</option></term>
          <listitem><para>Enables extra verbose output, which shows all files and paths added on sharelist creation.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--trayicon</option></term>
          <listitem><para>Starts the application in tray icon mode, meaning the main window will not be visible.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--socketlog <parameter>&lt;param&gt;</parameter></option></term>
          <listitem><para>Outputs a log of socket data to the file <filename>dcsocket.log</filename>.  Valid values for <parameter>param</parameter> are <parameter>none</parameter>, <parameter>send</parameter>, <parameter>recv</parameter> or <parameter>both</parameter>.</para></listitem>
        </varlistentry>
      </variablelist>
    </sect1>
    <sect1 id="running-environment">
      <title>Environment Variables</title>
      <variablelist>
        <varlistentry>
          <term>http_proxy</term>
          <listitem><para>If set, the HTTP proxy server to use for downloading public hub lists.  Needs to be in the form <parameter>http://&lt;server&gt;[:port]</parameter></para>
            <para>A quick way to run &appname; with a proxy would be to type something like the following into a terminal:
              <screen>
export http_proxy=http://192.168.0.1:8080
&binaryname;
              </screen>
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>
    <sect1 id="running-help">
      <title>Help! It won't run!</title>
      <sect2 id="running-help-mismatchedqt">
        <title>Mismatched Qt (TM) version</title>
        <para>A common problem asked about on the &appname; board is an error on startup that looks like this:</para>
        <screen>
Checking Qt (TM) version ...
Compiled for '3.0.5' using '3.1.2'
Checking Qt (TM) privates ...
&appname;: relocation error: &appname;: undefined symbol: _ZN19QSharedDoubleBufferC1EbbP7QPixmap 
        </screen>

        <para>The second line gives a hint as to what is wrong: the version of Qt (TM) that &appname; was compiled for doesn't match the version that you have on your system.  There are a few ways of correcting this:
          <itemizedlist>
            <listitem><para>If you have installed a precompiled &appname; .rpm or .deb, you may need a different package.  Try to find one that was compiled for the version of Qt (TM) you have.</para></listitem>
            <listitem><para>Alternatively you could install a different version of the Qt (TM) runtime libraries to match what &appname; is expecting.</para></listitem>
            <listitem><para>If you can't find a precompiled version that works on your system, try getting a source package (.src.rpm or deb-src) and compiling that.</para></listitem>
            <listitem><para>If you have compiled &appname; from source, make sure your development Qt (TM) libraries are the same version as your runtime libraries.  It is possible to have multiple versions installed at once, so make sure the right one in being used.</para></listitem>
          </itemizedlist>
        </para>
      </sect2>
      <sect2 id="running-help-segfault">
        <title>Segmentation fault</title>
        <para>If you get something like this:
          <screen>
Checking Qt (TM) version ...
Compiled for '3.0.5' using '3.0.5'
Checking Qt (TM) privates ...
private test ok !
PARITY : 64 64
Signal (11) received, stackdump follows; eax='00000000', ebx='00000000', ecx='00000000', edx='00000000', eip='00000000'
--- retaddr=0x0, ebp=0x0
          </screen>
          it could be a bug, or it could be your configuration files are corrupt.  Try renaming your ~/.dc folder temporarily, then run &appname; again.  If it works fine then it was a problem with the configuration files.  However if it continues to crash, check the <ulink url="http://wxdcgui.sourceforge.net/forum/index.php">&appname; board</ulink> for others having similar problems with that version.  You may want to compile a <link linkend="compiling-debug">debug build</link>.  This will provide more information on the crash, which can help the developers find the cause.</para>
      </sect2>
    </sect1>
  </chapter>
  <chapter id="gettingstarted">
    <title>Getting started</title>
    <para>&appname; can be a bit bewildering the first time you use it, so here is a quick-start guide to get you on your way.</para>
    <sect1 id="gettingstarted-options">
      <title>Set necessary options</title>
      <para>The very first time you run &appname; you will be presented with an options screen before the main program loads.  You need to set a few things before continuing.</para>

      <para>On the Identify tab, fill in the following fields:
        <itemizedlist>
          <listitem><para>Nick: A nickname to identify yourself.</para></listitem>
          <listitem><para>Search Nick: A different nickname.</para></listitem>
          <listitem><para>Speed: Your internet connection speed.</para></listitem>
        </itemizedlist>
      </para>

      <para>On the Transfer tab:
        <itemizedlist>
          <listitem><para>Download Folder: Where you want downloaded files to go.</para></listitem>
          <listitem><para>Share Folders: You need to make some of your files available for others.  Click the "Add" button (the one that looks like a sheet of paper with a green plus symbol) and choose a folder to share.</para></listitem>
          <listitem><para>Click the blue icon with the swirly arrow to update your list of shared files, then click the "Save" button.</para></listitem>
        </itemizedlist>
      </para>
    </sect1>
    <sect1 id="gettingstarted-hub">
      <title>Get a list of hubs and connect to one</title>
      <para>Ok, &appname; is now open fully, but it isn't doing much yet.
        <itemizedlist>
          <listitem><para>Click the "Action" menu, and choose "Hub List".</para></listitem>
          <listitem><para>Click the swirly arrow icon to get a list of hubs.  This may take a minute, so be patient.</para></listitem>
          <listitem><para>The Hub List window should now be full of strangely-named hubs.  Choose one that looks interesting, and has lots of users, and double-click its name.</para></listitem>
          <listitem><para>A new window will open up.  Within a short time you should start seeing messages about connecting.  If nothing happens, or you get disconnected, close the window and try again with another hub.</para></listitem>
        </itemizedlist>
      </para>
    </sect1>
    <sect1 id="gettingstarted-download">
      <title>Find and download files</title>
      <para>If you've made it this far, you're nearly there.  Its time to grab some files.
        <itemizedlist>
          <listitem><para>Click the "Action" menu, and choose "Hub Search".</para></listitem>
          <listitem><para>In the space below the word "Search", type in a word or two, then click "Start".</para></listitem>
          <listitem><para>Click the "Results" tab, and see what turns up.  It may take a minute or two before all the results are in.</para></listitem>
          <listitem><para>Double-click the name of one of the found files to tell &appname; you want to download it.</para></listitem>
          <listitem><para>You might get some messages about multi-download.  Its ok to say Yes to these.</para></listitem>
          <listitem><para>Click the "Action" menu, and choose "Transfer List".  This will show you the progress (if any) of your download.</para></listitem>
        </itemizedlist>
      </para>
    </sect1>
  </chapter>
  <chapter id="options">
    <title>Options</title>
    <sect1 id="options-identify">
      <title>Identify</title>
      <variablelist>
        <varlistentry>
          <term>Nick</term>
          <listitem><para>The name you will be identified by in DC hubs.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term>Search Nick</term>
          <listitem><para>This is the name &appname; will use when it is searching multiple hubs, such as all Public hubs or Bookmarked hubs.  The names of users in a hub must be unique, and since &appname; may search a hub you are already connected to, using a different nick here will avoid a name conflict.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term>Email</term>
          <listitem><para>Your email address, if you want others to know what it is.  Can be blank.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term>Anti-spam</term>
          <listitem><para>If you have provided your email address in the option above, this setting modifies the way it is displayed.  Instead of your address taking the form <computeroutput>yourname@yourisp.com</computeroutput>, it will appear as <computeroutput>yourname at yourisp dot com</computeroutput>.  This is intended to make it difficult for spammers to 'harvest' your address with automated tools.  Usually doesn't hurt to leave this enabled.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term>Photo</term>
          <listitem><para>Allows you to specify an image file as a photo of yourself.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term>Description</term>
	  <listitem><para>Space for you to put a free-form comment.  This is often used to tell others information about your share (e.g. lots of Anime) or your connection (e.g. 256kbit/s upstream).  Make sure you replace the default description with something useful to your fellow users.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term>Add Description Tag</term>
	  <listitem>
            <para>When enabled a 'tag' containing system information will be added to your description.  It is a good idea to turn this on, as it lets others see some basic info on your configuration, saving them from have to ask you for it.  Many hubs require that tags be displayed.</para>
            <para>The tag will be in the format &lt;DCGUI V:<parameter>version</parameter>,M:<parameter>mode</parameter>,H:<parameter>hubs</parameter>,S:<parameter>slots</parameter>,L:<parameter>limit</parameter>&gt; where:
              <itemizedlist>
                <listitem><para><parameter>version</parameter> is the version of &appname; you are running.</para></listitem>
                <listitem><para><parameter>mode</parameter> is A if you are in <link linkend="options-connection-mode-active">active mode</link>, or P if you are in <link linkend="options-connection-mode-passive">passive mode</link>.</para></listitem>
                <listitem><para><parameter>hubs</parameter> is the number of hubs you are currently connected to.</para></listitem>
                <listitem><para><parameter>slots</parameter> is the number of <link linkend="options-transfer-settings-uploadslots">public slots</link> you have set.</para></listitem>
                <listitem><para><parameter>limit</parameter> is the per-transfer <link linkend="options-transfer-settings-uploadrate">upload rate</link> limit, in kB/s.  This will only appear if an upload rate limit has been set.</para></listitem>
              </itemizedlist>
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Away Prefix</term>
          <listitem><para>This string will be put in front of your description and tag when you are in <link linkend="menu-action-awaymode">away mode</link>.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term>Speed</term>
	  <listitem><para>Lets you tell others what sort of internet connection you have, so they can estimate what sort of transfer speed they can get from you.  Be honest, its easy to tell if someone is overstating their bandwidth, and is a kickable offense in many hubs.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term>Away Message</term>
	  <listitem><para>If you are in <link linkend="menu-action-awaymode">away mode</link> and someone tries to send you a Private Message, &appname; will automatically reply with this text.  You could put a friendly message telling people that you are away and when you will be back.</para></listitem>
        </varlistentry>
      </variablelist>
    </sect1>
    <sect1 id="options-transfer">
      <title>Transfer</title>
      <sect2 id="options-transfer-folder">
        <title>Folder</title>
        <variablelist>
          <varlistentry>
            <term>Download Folder</term>
            <listitem><para>Files that are in the process of being download are placed in this folder.  Its a good idea to have a specific directory for this purpose, so you don't clutter up other locations.  It is also recommended that you NOT share this directory, as people don't want your incomplete files.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Move Finished Files to this Folder</term>
            <listitem><para>If you set this to a directory instead of leaving it blank, &appname; will move completely downloaded files from the Download folder to here.  This is useful feature, as it saves you the task of identifying finished files yourself.  You could share this directory if you wanted to quickly propogate you downloads to others.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Share Folders</term>
            <listitem><para>This is the list of folders that you are sharing to the world.  You can share as many folders as you like with the Add button, or unshare a folder by selecting it and pressing Remove.  By default shared folders are listed using their actual name.  If you want to make things neater you can change the alias of a folder, by selecting the folder and clicking the edit button.</para>

            <para>Once you have set up your shares, make sure you press the Rebuild button.  This generates a list of all your shared files for others to browse.  Clicking on the Browse button will show you what this file list looks like.  The Info button tells you the size of your share, and how big the file list is.  The file list is stored in two compressed formats, HE3 and Bzip2.  All clients support HE3, but many modern clients are able to use Bzip2 to produce a smaller file.</para>

            <para>To be a good DC citizen, keep your share tidy and organised as much as you can.  Arrange files into subfolders so they are easier for others to find.  Give files meaningful names so they are easy to identify.  For example, if you have an English-subtitled first episode of the Anime "Now and Then, Here and There", a good filename would be: <filename>Anime/Now and Then, Here and There (eng subbed)/Now and Then, Here and There - 01.avi</filename>.  A bad filename would be: <filename>Stuff/nowandthen1.avi</filename></para>

            <para>The more you share the better DC is for everyone, so share as much as you can.  However, make sure what you are sharing are things people will actually want.  Don't share system files or incomplete downloads.  Don't share your home directory or any directory containing personal information.  Certain hubs have their own specific rules about what are 'useless' files, so make sure you read the rules and follow them.  Many hubs have automated scripts that will kick you if they find files that are against their rules.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Check and recreate sharelist on startup</term>
            <listitem><para>It is good practice to rebuild your sharelist every time you change what files you are sharing.  This option will help you out if you keep forgetting to refresh your share.  It will do an automatic rebuild on startup if it detects there has been a change.  Note that if you have been renaming files the rebuild might not be triggered, so you should do a manual rebuild, either by clicking the button above this option, or typing /refresh in the main chat window.  Also note that if you have a big share you may find this causes slow startup times.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Disable hash list</term>
            <listitem><para>A hash is a way of uniquely identifying a file.  By default &appname; will calculate a hash value for all of your files and include the info in your share list, which will help others identify your files.  However this can be a CPU and disk intensive process that could take several hours, so this option allows you to disable this process.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Recreate every hour</term>
            <listitem><para>&appname; can automatically recreate your sharelist at a set interval.  Select the number of hours to elapse between each refresh, or 0 to disable this feature.</para></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
      <sect2 id="options-transfer-settings">
        <title>Settings</title>
        <variablelist>
          <varlistentry id="options-transfer-settings-savequeue">
            <term>Save queue in minutes</term>
            <listitem><para>The transfer queue is &appname;'s record of what files you are trying to download, and from where.  This is constantly being updated while the program runs, but usually it is only written to disk when you exit the program.  If you often run &appname; for long periods and are concerned about losing the state of your downloads, set this to a number greater than 0.  This will indicate how often &appname; should save its transfer list to disk.  Note you can also manually save the queue by choosing "Save Queue" after right-clicking in the Wait list.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-uploadslots">
            <term>Max Upload Slots</term>
            <listitem><para>Upload slots, often referred to as just 'slots', are how you control the number of people connected to you at one time.  The more slots you have, the more people can download files from you (you are 'uploading' the files to them).  However, each connected person gets a corresponding fraction of your bandwidth, so the more slots you have open, the slower each individual's download will proceed.  It is therefore important to balance the number of slots with the speed of your internet link.</para>
            <para>This option sets the number of 'public' slots, that are available for anyone to use to download from you.  In addition, you can grant individual users that are in addition to the public slots.  So, for example, you could have four public slots, and grant three of your friends a slot, meaning up to seven people could download from you at once.</para>
            <para>There are also several other 'special' slots that are controlled by &appname;.  There are:
              <itemizedlist>
                <listitem><para>Slots for admins to download your share list.  Hub admins are the people who run the hubs your connect to.  Most admins want to be able to check your share list to make sure you are following the rules of their hub.  They can't download your other files this way, they can only get your share list.  There are always three (3) of these slots.</para></listitem>
                <listitem><para>Slots for others to get your share list.  This lets others find what you are sharing even if all your normal slots are full.  This is a helpful feature for other users, unfortunately not all DC clients currently provide this.  There are three (3) of these slots.</para></listitem>
                <listitem><para>Slots for files less that 16kb in size.  Very small files don't take long to download, so slots are made available to make them easy to get.  There are three (3) of these slots.</para></listitem>
              </itemizedlist>
            For the sake of those downloading from you, try to set the number of slots so that transfers run at a decent rate.  Keep in mind that if you grant lots of slots things will slow down for everyone.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-dynamicupload">
            <term>Dynamic Upload Rate</term>
            <listitem><para>The max upload rate setting (below) puts a cap on how fast each upload can go.  However, not all users may be able to upload from you at that rate, meaning some of your bandwidth is not being used.  This feature lets those who are fast downloaders use the 'spare' left over from slow downloaders, while still keeping the overall upload rate within the limits set.</para>
            <para>An example:  if you had 5 slots, limited to 10 kB/s each, and dynamic upload enabled.  If no-one else was downloading from you, a single user could transfer at 50 kB/s.  Without dynamic upload, they would be limited to 10 kB/s, leaving the other 40 kB/s unused.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-uploadrate">
            <term>Max upload rate</term>
            <listitem><para>This sets a limit (in kilobytes per second) on how fast each slot will be allowed to upload from you.  You may want to do this to stop fast uploaders from taking more than a fair share of bandwidth, or to restrict your upstream rate generally.  What you set this to will be shown in your description tag, and enabling it is frowned upon in many hubs.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-downloadrate">
            <term>Max download rate</term>
            <listitem><para>This setting helps &appname; make efficient use of your download bandwidth, but it is not a hard limit.  It works quite differently from the upload rate setting above.</para>
              <para>A value entered here will prevent &appname; from starting more downloads if your overall download rate is already at or above this speed.  This will tend to keep fewer, faster downloads running, instead of dozens of downloads crawling along.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-uploadstouser">
            <term>Max uploads to user</term>
            <listitem><para>If this value is increased from its default of 1, users are permitted to download more than one file from you at a time.  This also means they will be taking up extra slots.  The default is recommended.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-resendtimeout">
            <term>Resend Timeout</term>
            <listitem><para>After &appname; fails to connect to someone (e.g. if all their slots were full) it will wait this many seconds before it tries to connect again.  Best not set this too low, or &appname; will be constantly trying to reconnect, 'hammering' the remote users.  This is unfriendly and wastes computer and network resources.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-responsetimeout">
            <term>Response Timeout</term>
            <listitem><para>If &appname; is trying to connect to a remote user, but doesn't get a response for this many seconds, it will give up and close the connection.  This value needs to be high enough to allow slow or busy clients time to respond to you.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-userquitting">
            <term>User quitting hub</term>
            <listitem><para>It is good manners, and often a hub rule, that you stay in a hub while you are downloading from others in the hub.  These settings help you obey the rules by automatically terminating transfers when a hub is left.</para></listitem>
          </varlistentry>
          <varlistentry id="options-transfer-settings-autosearch">
            <term>Auto-search for new sources</term>
            <listitem><para>If you often leave &appname; running unattended, this setting will help you get your downloads finished.  Under certain conditions, &appname; will automatically search for new download locations for files in your queue.  If it finds any, they will be added to the transfer list.  However, to prevent this putting excessive load on hubs, the following criteria must be met before an auto-search will happen:
              <itemizedlist>
                <listitem><para>20 minutes have passed since the last auto-search</para></listitem>
                <listitem><para>no downloads are currently running</para></listitem>
                <listitem><para>you have a file with priority 0</para></listitem>
                <listitem><para>a hash exists for that file</para></listitem>
                <listitem><para>it is a multi download</para></listitem>
                <listitem><para>any files found must be of equal size</para></listitem>
                <listitem><para>only new sources, i.e. with a different nick, will be added</para></listitem>
              </itemizedlist>
            </para></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
    </sect1>
    <sect1 id="options-connection">
      <title>Connection</title>
      <sect2 id="options-connection-mode">
        <title>Mode</title>
        <sect3 id="options-connection-mode-choosing">
          <title>Active or Passive Mode</title>
	  <para>Active mode should be used when other DC clients can connect directly to you from the internet.  If you are not directly contactable, e.g. because of firewalls or NATs, you will need to use Passive mode instead.  If you're not sure, start off in active mode, and if you can't seem to get any search results or file lists, switch to passive.</para>

          <para>Active mode is preferable because it lets you search and download from every user in a hub.  Passive mode limits you to only Active users, and multi-hub search isn't possible.  If you have control over your firewall, see the firewall section for information on how you can set up active mode.</para>
        </sect3>
	<sect3 id="options-connection-mode-active">
	  <title>Active Mode Settings</title>
          <variablelist>
            <varlistentry>
              <term>IP or Hostname</term>
              <listitem><para>If you are behind a NAT and have forwarded the appropriate ports, enable this setting and enter the public IP address of your router in the space provided.  The test button will confirm the program receives packets sent to that IP.  The 'Get Internet IP' button will work out your public IP address automatically.</para>

              <para>If you have a dynamically assigned public IP, you may want to register a hostname with a dynamic DNS provider, then put this hostname here instead.  This way you won't have to update this setting each time your ISP gives you a different public IP.</para></listitem>
            </varlistentry>

            <varlistentry>
              <term>Network Interface</term>
              <listitem><para>If the computer running &appname; has a publicly accessible IP address, you'll want this option.  Select the network interface that has the public IP by clicking on the 'Get Interface' button and choosing from the list.  As an example, if you connect to the internet via a modem, and you also have a local ethernet network, then the interface you want would likely be ppp0.</para></listitem>
            </varlistentry>

            <varlistentry>
              <term>TCP Listen Port</term>
              <listitem><para>This specifies the port number &appname; will listen on for TCP connections (e.g. for file transfers etc.).  It defaults to 9176, and you can usually leave it at that.  You need to make sure that incoming connections to this port can get through your firewall.</para></listitem>
	    </varlistentry>

            <varlistentry>
              <term>UDP Listen Port</term>
              <listitem><para>Search results will be sent directly to you on this UDP port.  It defaults to 9176.  Make sure your firewall allows through UDP packets destined to this port.</para></listitem>
            </varlistentry>

            <varlistentry>
              <term>Listen on IP</term>
              <listitem><para>If you have multiple IP addresses on one interface, you may need to specify which IP you want &appname; to use here.  Otherwise leave this blank.</para></listitem>
            </varlistentry>
          </variablelist>
        </sect3>
        <sect3 id="options-connection-mode-passive">
          <title>Passive Mode Settings</title>
          <variablelist>
            <varlistentry>
              <term>Send warn message to remote user on active mode request.</term>
              <listitem><para>If you are in passive mode, and a remote user who is also in passive mode tries to download a file from you, the transfer won't work.  Usually the attempt will fail silently, and many users don't realise why they can't get files from you.  This option, if enabled, will send an automated private message to the remote user, telling them that you are in passive mode.</para></listitem>
            </varlistentry>
          </variablelist>
        </sect3>
      </sect2>
      <sect2 id="options-connection-settings">
        <title>Settings</title>
	<variablelist>
          <varlistentry>
	    <term>Reconnect Counter</term>
            <listitem><para>If a hub disconnects you, &appname; will try to automatically reconnect.  This can be useful if a hub briefly goes down (e.g. its owner reboots their computer) as &appname; will reconnect and continue.  This counter sets how many times it will try before it gives up.  You can set it to 0 to turn it off, so that &appname; will only reconnect when told to manually.  Don't set it too high, else if you are banned from a hub (it happens) &appname; will waste lots of time trying to reconnect over and over.</para></listitem>
          </varlistentry>
          <varlistentry>
	    <term>Reconnect Timeout</term>
            <listitem><para>How long &appname; will wait between attempts to reconnect to a hub.  Don't set it too low or you will use up all your connection attempts before giving transient problems a chance to get sorted out.</para></listitem>
          </varlistentry>
          <varlistentry>
	    <term>Allow Force Move</term>
            <listitem><para>Many hubs will redirect you to another hub in some situations (e.g. if they are full).  This is known as a force move.  If you disable this option, a redirect will be treated as a failure to connect, so &appname; will try to connect to the hub again.</para></listitem>
          </varlistentry>
          <varlistentry>
	    <term>Ignore private address space connections</term>
            <listitem><para>Certain IP address are only intended for use on private networks, but not on the internet.  Enabling this option will prevent people with private addresses (e.g. the people on your LAN) from connecting to you.</para></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
    </sect1>
    <sect1 id="options-gui">
      <title>GUI</title>
      <sect2 id="options-gui-general">
        <title>General</title>
        <variablelist>
          <varlistentry>
            <term>Language File</term>
            <listitem><para>If English isn't your preferred language, you can have the text in &appname; translated.  Use this option to choose the appropriate language file to use.  You will need to restart &appname; for this to take effect.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Theme</term>
            <listitem><para>You can change the appearance of the buttons, dialogs and windows in &appname; all at once by choosing a different theme.  Click the test button to see what a theme looks like.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Units</term>
            <listitem><para>Numeric values are used heavily in &appname;, for things like file sizes and transfer rates.  When this setting is on Auto, these numbers will be shown in whatever unit is most appropriate.  If you prefer to have all values in the same unit, choose that instead.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Application Font</term>
            <listitem><para>Lets you choose the font style and size that will be used.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Data Folder</term>
            <listitem><para>Where &appname; should find other files it needs, such as emoticon images and language translation files.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Show Status Messages</term>
            <listitem><para>Status messages are short lines of information &appname; prints in chat windows, such as <computeroutput>&lt;&appname;&gt; Connected</computeroutput> when you connect to a hub, and in response to <link linkend="chatcommands">chat commands</link>.  Disabling this option will stop these messages from appearing.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Query on Exit</term>
            <listitem><para>When activated, &appname; will ask you to confirm you really want to quit when you try to close the program.  Helps to stop you exiting unintentionally and stuffing up all your transfers.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Query on File Delete</term>
            <listitem><para>When enbaled, this option will make &appname; prompt you for confirmation whenever you delete a file from your queue.</para></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
      <sect2 id="options-gui-transfer">
        <title>Transfer</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/transfer_view.png" format="PNG"></imagedata>
          </imageobject>
        </mediaobject>
        <para>The transfer view can show up to eight pieces of information for each file being transferred.  You will probably want display only some of this data, so you can see the state of your transfers without getting information overload.</para>
        <variablelist>
          <varlistentry>
            <term>Chunk Percent</term>
            <listitem><para>&appname; doesn't try and download a whole file in one piece, instead it downloads 'chunks' of about 1MB at a time.  Enabling this option will display a percentage that indicates how much of the current chunk is complete.  On fast connections this value tends to change rapidly, as chunks are completed and new ones started.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>File Percent</term>
            <listitem><para>What percentage of the file has been downloaded.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Chunk Size</term>
            <listitem><para>Displays the position, in bytes, of the start of the chunk, the current position in the chunk, and the end of the chunk.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>File Size</term>
            <listitem><para>Shows the number of bytes downloaded against the size of the whole file.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Download Rate Single</term>
            <listitem><para>How fast this individual transfer is progressing.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Remaining Time Single</term>
            <listitem><para>How long before this individual transfer will be completed at the current rate.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Download Rate Multi</term>
            <listitem><para>If you are using multi-downloads, the above 'single' options won't show realistic figures for the whole file.  This option displays the overall download rate of all running sources for a file.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Remaining Time Multi</term>
            <listitem><para>Similarly, this shows the amount of time remaining to download the whole file at the combined multi-download rate.</para></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
      <sect2 id="options-gui-chat">
        <title>Chat</title>
        <variablelist>
          <varlistentry>
            <term>Open Private Chat Window</term>
            <listitem><para></para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Use tab for every chat window</term>
            <listitem><para></para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Enable emoticons in chat</term>
            <listitem><para>When this option is enabled, certain combinations of characters will be replaced by emoticon images.  For example :( will be replaced with a small picture of a sad face.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Show send button</term>
            <listitem><para>After typing in a message you can send it by pressing enter, or if this option is enabled there will be a button you can click to send the message.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Forward private to public chat</term>
            <listitem><para>When enabled, private chat text will also appear in main chat.  No-one else can see it, it just saves you having to switch chat windows.  It may make conversations hard to follow.  Make sure you switch back to the private window before replying.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Show joins and parts</term>
            <listitem><para>When this option is on, notification messages will appear in main chat when users enter or leave the hub.  Useful on quiet hubs, however can result in a constant flood of messages on large/busy hubs.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Ignore messages to offline users</term>
            <listitem><para>If you try and send a message to someone who has gone offline, and this option is enabled, &appname; will refuse to send the message and print a warning.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Ignore messages from offline users</term>
            <listitem><para>Sometimes you receive messages from users who aren't in the user list, e.g. hub security scripts or bots.  Turning on this option will stop these messages being displayed.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Max paragraphs</term>
            <listitem><para></para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Hide popups of more than x lines</term>
            <listitem><para></para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Send message with</term>
            <listitem><para>The default key to send a chat message is the Enter key.  You can start a new line in your chat without sending the message by pressing Ctrl+Enter.  If you prefer different behaviour, this option will let you specify what key combination should be used to send a message.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Browser</term>
            <listitem><para>When you click on a URL that is displayed in a chat window, &appname; will attempt to open it in a web browser.  You can specify the browser to use here.  If the program is in your path you can just give its name e.g. <computeroutput>mozilla</computeroutput> or you can browse for the full path e.g. <computeroutput>/usr/bin/mozilla</computeroutput></para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Color</term>
            <listitem><para>The text in the chat windows can be given different colours, based on the source of the message.  You could make your messages stand out from other chat text, or use light coloured text so it is legible against a dark background.  You can set the colour of a type of text by double-clicking on its name and choosing from the palette.</para></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
      <sect2 id="options-gui-client">
        <title>Client</title>
        <variablelist>
          <varlistentry>
            <term>Show client windows minimized</term>
            <listitem><para></para></listitem>
          </varlistentry>
          <varlistentry>
            <term>User-List right alignment</term>
            <listitem><para>When selected, the user list will appear on the right hand side of the hub window, with the chat on the left.  Otherwise the chat will be on the right, and the userlist on the left.  Note that this only takes effect when you connect to a hub, the windows for hubs you are already connected to don't change.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Auto Away Mode</term>
            <listitem><para>Will automatically put you into away mode if you are idle for more than the set number of seconds.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Columns</term>
            <listitem><para>Lets you select which information is shown in the user list.  Does not affect already connected hub windows.</para></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
    </sect1>
    <sect1 id="options-sound">
      <title>Sound</title>
      <para>You can choose to have sounds played when various events happen in &appname;.  Sounds are disabled by default.</para>
      <variablelist>
        <varlistentry>
          <term></term>
          <listitem><para></para></listitem>
        </varlistentry>
      </variablelist>
    </sect1>
    <sect1 id="options-log">
      <title>Log</title>
      <variablelist>
        <varlistentry>
          <term>Logfile</term>
          <listitem><para>&appname; can write a log of its activity, such as files successfully downloaded.  To enable logging, select this option and specify a file that &appname; should log information to.  Useful for debugging.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Timestamp Private Chat</term>
          <listitem><para>If enabled, each message in private chat will have the time it was sent displayed beside it.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Timestamp Hub Chat</term>
          <listitem><para>If enabled, each message in the main hub chat will have a timestamp displayed beside it.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Chat Logging</term>
          <listitem><para>Various options to configure when and how &appname; logs chat conversations.</para></listitem>
        </varlistentry>
      </variablelist>
    </sect1>
    <sect1 id="options-hublists">
      <title>Hub Lists</title>
      <variablelist>
        <varlistentry>
          <term>Store local</term>
          <listitem><para>Whether &appname; should keep a local copy of the hub list.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Reload every hour</term>
          <listitem><para>If this is set to a value greater that zero, then &appname; will automatically reload the hub list after that many hours have passed.  This way your hublist will always be up-to-date.  Only use this option when you really need to, as it will produce extra traffic on the servers providing the hub lists.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Source URLs</term>
          <listitem><para>These URLs are where &appname; gets its list of public hubs from.  You can add and remove sources of hub lists, or un-tick a list to prevent it being used.</para></listitem>
        </varlistentry>
      </variablelist>
    </sect1>
    <sect1 id="options-security">
      <title>Security</title>
      <sect2 id="options-security-flood">
        <title>Flood Protection</title>
        <para>These options are to protect you from antisocial people who like to fill the chat screen with the same message over and over, otherwise known as flooding.</para>
        <variablelist>
          <varlistentry>
            <term>Don't Display messages after X retry</term>
            <listitem><para>If the same message appears this many times, &appname; will automatically hide any more copies of it.  This greatly reduces the impact of flooders.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Kick the user for flooding.</term>
            <listitem><para>If you are an operator, you have the ability to kick people off the hub.  This option will automatically kick users who are flooding the chat.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Kick Message</term>
            <listitem><para>This is the reason that will be given if a person is kicked by &appname; for flooding the chat.</para></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
      <sect2 id="options-security-ssl">
        <title>Transfer Cert/Key</title>
        <para>These options are to do with SSL transfers [FIXME]</para>
      </sect2>
    </sect1>
  </chapter>
  <chapter id="hublist">
    <title>Hub List</title>
    <para>You can open the hub list window by clicking the toolbar icon, or by choosing <menuchoice><shortcut><keysym>Ctrl+U</keysym></shortcut><guimenu>Action</guimenu><guimenuitem>Hub List</guimenuitem></menuchoice> from the menu.</para>

    <para><screenshot><graphic fileref="images/hublist/expanded.png"></graphic></screenshot>  The first toolbar lets you reload or update the list of hubs, and apply filters.  The second lets you enter the address of a hub manually.  If you know the address of a hub enter it into the box and click the connect button <inlinegraphic fileref="images/hublist/button_connect.png"></inlinegraphic>.</para>

    <sect1 id="hublist-publichubs">
      <title>Getting a list of public hubs</title>
      <para>Before you can do anything with DC you need to connect to at least one hub.  This window will give you a list of public hubs for you to browse through.  You can connect to a hub simply by double-clicking its name in the list.</para>
      <para>However, when you first run &appname; there are no hubs listed here. You need to click on the Reload Public Hublist button <inlinegraphic fileref="images/hublist/button_reload.png"></inlinegraphic> to get the list.  The list is obtained from special locations that provide this service, see <xref linkend="options-hublists"></xref> for information about the source urls.  A progress bar will appear at the right of the second toolbar while the reload is happening.</para>

      <para>Public hubs are usually run by generous users on their personal computers, which tends to mean they come and go fairly frequently. If you find that hubs in your list no longer exist when you try to connect to them, its probably time to update your list.  Clicking the Update Public Hublist button <inlinegraphic fileref="images/hublist/button_update.png"></inlinegraphic> will do that.</para>
    </sect1>
    <sect1 id="hublist-filters">
      <title>Using Filters</title>
      <para>At the of writing there are over 3000 public DC hubs available.  To make it easier for you to find hubs that are of interest to you, you can filter the list to only show certain hubs.</para>

      <sect2 id="hublist-filters-creating">
        <title>Creating a filter</title>
        <para>If you were a fan of Anime (Japanese animation) you might want to only see hubs that are anime-related.  You would do this as follows:
        <orderedlist>
          <listitem><para>Click the Add Filter button <inlinegraphic fileref="images/hublist/button_add_filter.png"></inlinegraphic></para></listitem>
          <listitem><para>Enter a name for the filter in the <guilabel>Filter</guilabel> field.</para></listitem>
          <listitem><para>Enter the word 'anime' in the <guilabel>Contains</guilabel> field.</para></listitem>
          <listitem><para>Tick the box next to <guilabel>Description</guilabel>.  You should now have a window that looks something like this: <screenshot><graphic fileref="images/hublist/edit_filter_anime.png"></graphic></screenshot></para></listitem>
          <listitem><para>Click the Save button.</para></listitem>
          <listitem><para>From the Filter drop-down list. choose your new filter 'anime'</para></listitem>
        </orderedlist>

        The hub list will now only show hubs that contain the word 'anime' in their description.  <graphic fileref="images/hublist/expanded_with_anime_filter.png"></graphic>  The tab at the top of the window shows how many out of all the hubs are being displayed.  In this case only 244 of 3247 public hubs matched the filter.  You can browse through the list and double-click a hub to connect to it.</para>
      </sect2>
      <sect2 id="hublist-filters-editing">
        <title>Editing a filter</title>
        <para>Often, the best hubs are those that have the most people connected to them.  We can refine our filter to only display hubs that have at least a minimum number of users.  Click the edit filter button <inlinegraphic fileref="images/hublist/button_edit_filter.png"></inlinegraphic> to display the settings of the filter.  Set the value in the <guilabel>Min. User</guilabel> field to a decent number e.g. 200, then click <guibutton>Save</guibutton>.  The hublist now displays only hubs with 200 or more users that have the word 'anime' in the description.</para>

        <para>You can also modify a filter so it looks for matching words in the hub name or the hub address.  If you tick more than one option, then the words can appear in any of the selected fields.</para>
      </sect2>
      <sect2 id="hublist-filters-deleting">
        <title>Deleting a filter</title>
        <para>If you no longer need a particular filter you can delete it.  Choose the filter you want to delete from the list of filters so it is the active filter.  Then click the Delete Filter button <inlinegraphic fileref="images/hublist/button_delete_filter.png"></inlinegraphic></para>
      </sect2>

      <sect2 id="hublist-filters-default">
        <title>Viewing all public hubs</title>
        <para>If you would like to revert back to viewing all the available public hubs, choose the 'Default' filter from the list.  Note that you can't edit or delete the Default filter.</para>
      </sect2>
    </sect1>
    <sect1 id="hublist-bookmarks">
      <title>Bookmarks</title>
      <para>Bookmarks let you easily keep track of your favourite hubs.  The public server list is not always reliable, so bookmarking hubs you find interesting is a good thing to do.  To access your Bookmarks, open the Hub List window and click on the Bookmarks tab.</para>

      <sect2 id="hublist-bookmarks-creating">
        <title>Creating a Bookmark</title>
        <para>There are several ways to create a Bookmark:
          <itemizedlist>
            <listitem><para>From the public hub list: Right-click the hub you want, and select "Add Bookmark".</para></listitem>
            <listitem><para>From a Hub Search: Right-click a search result, and select "Add Bookmark".</para></listitem>
            <listitem><para>From the bookmarked hubs list: Right-click anywhere on the Bookmarks list, and select "Add". With this method, you'll have to manually enter the hub name, host (server), and description.</para></listitem>
            <listitem><para>From within the hub: type /fav in the chat window.</para></listitem>
          </itemizedlist>
        </para>
      </sect2>

      <sect2 id="hublist-bookmarks-editing">
        <title>Editing a Bookmark</title>
        <para>You can change any Bookmark name, server, or description by right-clicking the Bookmark and selecting "Edit".</para>
      </sect2>

      <sect2 id="hublist-bookmarks-deleting">
        <title>Deleting a Bookmark</title>
        <para>You can delete a Bookmark by selecting it, right-clicking and selecting "Remove".</para>

        <para>You can also delete multiple bookmarks by selecting more than one and removing in the same manner.</para>
      </sect2>

      <sect2 id="hublist-bookmarks-connecting">
        <title>Connecting to a Bookmarked hub</title>
        <para>You can connect to a Bookmark hub in the same manner as connecting to a server in the Public list. Simply double-click it, or right-click and select "Connect".</para>
      </sect2>

      <sect2 id="hublist-bookmarks-update">
        <title>Updating Servers</title>
        <para>If you find you cannot connect to a Bookmarked hub for an extended period (hubs are run on people's home computers usually and may have some down times by default), right-click the Bookmark and select "Update Server".</para>

        <para>This is useful should the hub have changed their server name/location, as it will update your Bookmark to the new location.</para>

        <para>You can also update all Bookmarked servers at once with right-click "Update All Servers".</para>
      </sect2>
    </sect1>
    <sect1 id="hublist-profiles">
      <title>Profiles</title>
      <para>You can specify certain options, such as your nickname and description, on a per-hub basis by using Profiles.  Other possibilities include making certain hubs connect automatically when you start &appname;, and hubs requiring authentication be set up so you login automatically without having to enter your password each time.</para>

      <para>Profile are managed in the Bookmarks tab in the Hub List window.</para>

      <sect2 id="hublist-profiles-creating">
        <title>Creating a Profile</title>
        <orderedlist>
          <listitem><para>In the Bookmarks window, right click on the hub you want to set a profile for and select "Edit".</para></listitem>
          <listitem><para>In the hub settings window, tick the "Profile" box then click the "Profile" button.</para></listitem>
          <listitem><para>If you are going to use a nickname different from your default one on this hub, enter it in the space labelled "Nick"</para></listitem>
          <listitem><para>If this profile is going to be used for a hub where a password is required, enter the password. Otherwise leave it blank.</para></listitem>
          <listitem><para>Fill in the other options as required if your default settings aren't sufficient for this hub.</para></listitem>
          <listitem><para>If you want the hub to open automatically when you start &appname;, mark the "Auto Connect" box.</para></listitem>
          <listitem><para>You can specify that &appname; should use SSL when connecting to this hub by selecting the "Secure Socket Layer" option.</para></listitem>
          <listitem><para>Click "OK" when finished.</para></listitem>
        </orderedlist>
      </sect2>

      <sect2 id="hublist-profiles-managing">
        <title>Managing Hub Profiles</title>
        <para>To check what profiles are set, right-click anywhere on the list of Bookmarks, and select "Profile editor".  Select the hub from the drop-down list at the top, and the profile settings for that hub will be displayed for editing.  Select "OK" when finished, and most settings will take effect immediately.  You can also edit profile settings by following the instructions in "Creating a Profile" above.</para>
      </sect2>
    </sect1>
  </chapter>
  <chapter id="transfer">
    <title>Transfer List</title>
    <sect1 id="transfer-transfer">
      <title>Transfer</title>
      <para>Shows transfers that are in progress.</para>
    </sect1>
    <sect1 id="transfer-wait">
      <title>Wait</title>
      <para>Lists the users you are waiting to get files from.</para>
    </sect1>
    <sect1 id="transfer-files">
      <title>Files</title>
      <para>Lists the files you are waiting to download.</para>
    </sect1>
    <sect1 id="transfer-slots">
      <title>Slots</title>
      <para>Shows what download slots you have granted to other users.</para>
    </sect1>
    <sect1 id="transfer-log">
      <title>Log</title>
      <para>Shows detailed information on the connection and transfer process.</para>
    </sect1>
  </chapter>
  <chapter id="search">
    <title>Hub Search</title>
    <para>This is one of the most powerful parts of &appname; and you will spend a lot of time using it.  To get the most out of the DC network you need to know how to search effectively.</para>
    <sect1 id="search-mechanics">
      <title>Mechanics of searching</title>
      <para>When you open the Hub Search window, type in a query and click 'Search', the following happens:
        <itemizedlist>
          <listitem><para>Your search query is sent to the hubs you are connected to.</para></listitem>
          <listitem><para>Each hub passes the query onto each client connected to it.</para></listitem>
          <listitem><para>If a client has files that match the query, they send a response:</para>
            <itemizedlist>
              <listitem><para>If you are in active mode, the client sends the response directly to you.</para></listitem>
              <listitem><para>If you are in passive mode, the client sends the response to the hub, which then passes it onto you.</para></listitem>
            </itemizedlist>
          </listitem>
          <listitem><para>&appname; sorts out the responses and displays them.</para></listitem>
        </itemizedlist>
      </para>
      <para>If you are in passive mode you won't see search results from others in passive mode, as you won't be able to get their files anyway.  You will find a lot more files if you are active!</para>
      
      <para>By default &appname; stops waiting for responses after two minutes.  This is usually heaps of time for all the results to trickle in.  You can stop it sooner by clicking on the 'Stop' button.</para>
      
      <para>Most clients have a maximum number of responses they will give to one query, commonly about 10.  If you search for common words this prevents hundreds or thousands of matches coming back from each client.</para>

      <para>Each search puts a load on the hubs and every client connected to it.  Searches happen regardless of slots.  The 'Spy' function shows the amount of searches you are seeing - its a lot!  Searching can be abused, often called search-spam.  Some hubs kick clients doing lots of rapid searches.</para>
    </sect1>
    <sect1 id="search-wisely">
      <title>Searching wisely</title>
      <para>The words you search for have a huge impact on what results you will get.  Similar files often have very different names, so your search string have to be generic enough to catch relevant files, while not including too many irrelevant ones.</para>
      <sect2 id="search-wisely-strings">
        <title>Choosing search strings</title>
        <para>
          <itemizedlist>
            <listitem><para>Try not to use too many common words.  Searching for 'anime mp3' on an anime hub will give you ridiculous numbers of files of all sorts.  You usually want to be more specific.</para></listitem>
            <listitem><para>Be careful about file extension that have differnt forms, e.g. mpg vs mpeg.  If you put 'mpg' in your search string you may miss files with the alternate extension.</para></listitem>
            <listitem><para>Don't put leading zeroes e.g. searching for episode 01 wont find files called episode 1.</para></listitem>
          </itemizedlist>
        </para>
      </sect2>
      <sect2 id="search-wisely-filesize">
        <title>Limiting file sizes</title>
        <para>Often there are multiple versions of popular media files, for example an episode of show that has been encoded into an avi of different quality.  If you prefer only high-quality avis, you could set the search filter of files at least 200MB, for example.</para>
      </sect2>
      <sect2 id="search-wisely-where">
        <title>Where to search</title>
        <para>Selecting which hubs will give you the best search results the fastest.</para>
      </sect2>
      <sect2 id="search-wisely-clones">
        <title>Finding extra sources</title>
        <para></para>
      </sect2>
    </sect1>
    <sect1 id="search-results">
      <title>Managing search results</title>
      <para>sorting and grouping</para>
      <para>filtering</para>
      <para>browsing files of those that matched search</para>
      <para>searching for clones</para>
    </sect1>
  </chapter>
  <chapter id="windows">
    <title>Hub Windows</title>
    <para>This is where you see the hub chat, and the list of users.</para>
  </chapter>
  <chapter id="spy">
    <title>Spy</title>
    <para>When you enable the spy function, any search requests you receive will be displayed in this window.  This can give you an idea of what other people are searching for.  If you are on several large hubs you may be surprised by the sheer volume of search requests &appname; has to handle.</para>
  </chapter>
  <chapter id="users">
    <title>Users</title>
    <para>Also called Friends, if you mark a user as a friend they will appear here, along with an icon indicating if they are online.</para>
  </chapter>
  <chapter id="menu">
    <title>Menu Options</title>
    <sect1 id="menu-file">
      <title>File menu</title>
      <sect2 id="menu-file-options">
        <title>Options</title>
        <para>Opens the configuration window.</para>
      </sect2>
      <sect2 id="menu-file-quickoptions">
        <title>Quick Options</title>
        <para>Choice of download mode: Ask, Single or Multi</para>

        <para>Multi-download is where &appname; downloads portions of a single file from multiple people at the same time.  This feature can greatly speed up the rate your downloads are completed.  All you have to do is enable this option, and find more than one source for files.  The 'search for clones' option makes this easy.</para>

        <para>Note that files less than one megabyte in size are never downloaded this way.  &appname; gets the first megabyte from each source and compares them to make sure the files are the same.  If they are, a message 'hash ok' appears in the log window, and &appname; then reconnects and retrieves a chunk of the file that it doesn't have.  Right-clicking on a file in the transfer window and selecting 'File Info' will show you which bits of the file have been received.</para>
      </sect2>
      <sect2 id="menu-file-filelist">
        <title>Filelist browser</title>
        <para>Allows you to browse the downloaded filelists of others.</para>
      </sect2>
      <sect2 id="menu-file-filelistlocal">
        <title>Filelist browser local</title>
        <para>Displays your own shared files and directories.</para>
      </sect2>
      <sect2 id="menu-file-plugins">
        <title>Reload Plugins</title>
        <para>Reloads any <link linkend="plugins">plugins</link> &appname; is using.</para>
      </sect2>
      <sect2 id="menu-file-exit">
        <title>Exit</title>
        <para>Causes &appname; to close.</para>
      </sect2>
    </sect1>
    <sect1 id="menu-view">
      <title>View menu</title>
      <sect2 id="menu-view-tabbar">
        <title>Tabbar</title>
        <para>The tab bar sits just below the menu, and lets you switch quickly between open hubs.  This option toggles the display of the tab bar on and off.</para>
      </sect2>
      <sect2 id="menu-view-toolbar">
        <title>Toolbar</title>
        <para>Toggles display of the toolbar on and off.  The toolbar provides shortcuts to the most-used parts of the program.</para>
      </sect2>
      <sect2 id="menu-view-statusbar">
        <title>Statusbar</title>
        <para>This option toggles the display of the status bar on and off.  The status bar appears at the very bottom the main &appname; window.  It lists summary information about your slots and transfers.  From left to right the information listed is:
          <variablelist>
            <varlistentry>
              <term>SL:</term>
              <listitem><para>Slots: &lt;number used&gt;/&lt;number total&gt; &lt;used admin slots&gt;/&lt;used user slots&gt;/&lt;used special slots&gt;.  See <xref linkend="options-transfer-settings-uploadslots"></xref> for more info. </para></listitem>
            </varlistentry>
            <varlistentry>
              <term>UL:</term>
              <listitem><para>Upload rate</para></listitem>
            </varlistentry>
            <varlistentry>
              <term>DL:</term>
              <listitem><para>Download rate</para></listitem>
            </varlistentry>
            <varlistentry>
              <term>RX:</term>
              <listitem><para>Bytes you have received with &appname; since its first run.</para></listitem>
            </varlistentry>
            <varlistentry>
              <term>TX:</term>
              <listitem><para>Bytes you have sent with &appname; since its first run.</para></listitem>
            </varlistentry>
            <varlistentry>
              <term>Available disk space</term>
              <listitem><para>How much space is available on the partition where downloaded files are being saved.</para></listitem>
            </varlistentry>
            <varlistentry>
              <term>L: or S: or H:</term>
              <listitem><para>Share list creation status (only displayed during share list updates).  L: shows what percentage of the share list is complete, S: shows what percentage of the search index is complete, H: shows what percentage of the hash calculation is complete.</para></listitem>
            </varlistentry>
          </variablelist>
        </para>
      </sect2>
      <sect2 id="menu-view-dock">
        <title>Dock</title>
        <para>Toggles dock mode on and off.  Turning on dock mode shrinks &appname; down into an icon in the system tray or notification area of your window manager.  Clicking the icon is another way of shrinking/unshrinking the program.</para>
      </sect2>
    </sect1>
    <sect1 id="menu-action">
      <title>Action menu</title>
      <sect2 id="menu-action-awaymode">
        <title>Away Mode</title>
        <para>Choice of Normal or Away</para>
      </sect2>
    </sect1>
  </chapter>
  <chapter id="plugins">
    <title>Plugins</title>
    <sect1 id="plugins-intro">
      <title>What are plugins?</title>
      <para>A &appname; plugin is a small piece of code that adds some extra function to the program.  This allows other developers to write programs that can access &appname;'s internal state, without them having to modify the &appname; source.  Currently the only plugin is one which allows you to control &appname; over http.</para>
    </sect1>
    <sect1 id="plugins-getting">
      <title>Getting and compiling plugins</title>
      <para>This section is no longer valid as it points to a non-existent URL.</para>
      <para>Plugins aren't included in the core &appname;/dclib distribution, you have to get them seperately.  You can find the source for released plugins on the developers page at <ulink url="http://developer.berlios.de/project/showfiles.php?group_id=370"></ulink> or check out the module from cvs:
      <screen>
cvs -d:pserver:anonymous@cvs.dcgui.berlios.de:/cvsroot/dcgui login
cvs -z3 -d:pserver:anonymous@cvs.dcgui.berlios.de:/cvsroot/dcgui co plugin
      </screen></para>

      <para>Compilation is similar to the rest of &appname;:
        <screen>
make -f Makefile.dist
./configure
make
make install    <lineannotation>(as root)</lineannotation>
        </screen>
      </para>
    </sect1>
    <sect1 id="plugins-http">
      <title>HTTP plugin</title>
      <para>The http plugin allows you to control &appname; via a web browser.  This could be really useful if you don't always have physical access to the machine running the client, and a graphical remote control method like <ulink url="http://www.realvnc.com/">VNC</ulink> is not suitable.</para>

      <para>Currently the http plugin allows you to see the current state of &appname;, display and cancel transfers and connect to hubs.  There is no way at the moment to search or browse filelists, or add new downloads.</para>

      <para>By default, the http plugin listens on port 1480 and only accepts connections from localhost.  Connecting to <ulink url="http://localhost:1480/"></ulink> will present you with a login prompt.  The default username is "dcgui" and the password is "admin".  Once you are logged in you can change the password and security settings.  The configuration of the plugin is stored in <computeroutput>~/.dc/plugin/http.xml</computeroutput></para>
    </sect1>
  </chapter>
  <chapter id="networking">
    <title>Networking issues</title>
    <sect1 id="networking-ackprio">
      <title>Why do my downloads slow to a crawl when I am uploading?</title>
      <para>This is a common problem in the P2P community, and is not unique to &appname;.   It is due to the behaviour of the TCP protocol on heavily loaded links.  When you are downloading a file, your computer continuously sends 'acknowledgements' or ACKs to the source computer, telling it 'I got those last few bits, send some more'.  When you are also uploading flat-out, the acknowledgements take longer to send because they have to queue up behind the data you are uploading.  The slower the ACKs are sent, the slower your peers will send you data, thus the slower your download rate.</para>

      <para>There are two ways of avoiding this problem.  The first would be to set an <link linkend="options-transfer-settings-uploadrate">upload rate limit</link> in &appname; to just below your actual maximum upload speed.  This will allow a bit of breathing space for those ACK packets to fit into.  Unfortunately, most hub operators have an irrational fear of upload limiters, and will kick you from the hub if you use them.</para>

      <para>The second method works the same way, by artificially limiting your upload speed, and giving priority to ACK packets.  However this time it is done outside of &appname;, either by your operating system or an external program.  In some ways this is better solution, as it is transparent to &appname;, and can let you manage your bandwidth across other network applications as well.</para>

      <para>The Linux kernel comes with packet filtering and quality-of-service features.  You can make it prioritise acknowledgement packets, letting them "jump the queue" so your downloads and uploads both run as fast as they can.  See <ulink url="http://www.lartc.org/"></ulink> for full details, including the 'Wondershaper' script.  An alternate script with a similar aim is at <ulink url="http://www.digriz.org.uk/jdg-qos-script/"></ulink></para>

      <para>OpenBSD users have the powerful <command>pf</command> utility.  See <ulink url="http://www.benzedrine.cx/ackpri.html"></ulink> for a guide to ACK prioritisation.</para>

      <para>MacOS X users might find this article about <command>throttled</command> lets them do almost the same thing. <ulink url="http://wincent.org/article/articleview/161/1/25/"></ulink></para>

      <para>Windows users may want to try the shareware program Netlimiter, from <ulink url="http://www.netlimiter.com/"></ulink></para>
    </sect1>
    <sect1 id="networking-ports">
      <title>What port(s) does &appname; use?</title>
      <para>Unless you have an unusual situation, there is no need to change the port &appname; runs on away from the default 9172.  Sure, DC++ and other clients use other ports, so what?  It make no functional difference if you are on a different port, the programs tell each other what port they are on and it all works fine.  In addition, you really shouldn't try to run &appname; on ports less than 1024, as this requires that you run the program as root, which is *never* a good idea.</para>
    </sect1>
    <sect1 id="networking-firewall">
      <title>How do I configure my firewall so I can be in Active mode?</title>
      <para>There is no one answer to this, as there as so many different types of firewall in use.  The basic aim is to get TCP and UDP traffic for port 9172 (by default) to reach the computer running &appname;.  If the firewall is on the machine running &appname; then you just need to permit that traffic.  If the firewall is a separate device, and is doing NAT, the traffic needs to be forwarded to the &appname; machine.</para>

      <para>Here are some suggested firewall rules for those with a Linux iptables-based firewall.  There is NO GUARANTEE that these rules will work, or that they won't leave your systems wide open.  Make sure you know what you are doing before playing with firewall rules, and test afterwards.  Use these suggestions AT YOUR OWN RISK.</para>
      <para>The following assumptions are made:
        <itemizedlist>
          <listitem><para>your default INPUT and FORWARD policy is DENY, your default OUTPUT policy is ACCEPT</para></listitem>
          <listitem><para>$IPTABLES is the iptables command</para></listitem>
          <listitem><para>$PUBLICIP is your public IP address</para></listitem>
          <listitem><para>$PRIVATEIP is the internal IP of your firewall</para></listitem>
          <listitem><para>$EXTIF is your external network device, e.g. ppp0, eth1</para></listitem>
          <listitem><para>$INTIF is your the internal network device, e.g. eth0</para></listitem>
          <listitem><para>$MYPC is the private IP address of the computer running &appname; behind a NAT</para></listitem>
        </itemizedlist>
      </para>

      <para>Machine running &appname; has a public IP address, e.g. a dialup modem connection.
        <screen>
$IPTABLES -A INPUT -i $EXTIF -d $PUBLICIP -p tcp --dport 9176 -j ACCEPT
$IPTABLES -A INPUT -i $EXTIF -d $PUBLICIP -p udp --dport 9176 -j ACCEPT
        </screen>
      </para>
      <para>Machine running &appname; is behind a NATing Linux firewall.
        <screen>
$IPTABLES -t nat -A PREROUTING -d $PUBLICIP -p tcp --dport 9176 -j DNAT --to $MYPC
$IPTABLES -t nat -A PREROUTING -d $PUBLICIP -p udp --dport 9176 -j DNAT --to $MYPC
$IPTABLES -A FORWARD -o $INTIF -d $MYPC -p tcp --dport 9176 -j ACCEPT
$IPTABLES -A FORWARD -o $INTIF -d $MYPC -p udp --dport 9176 -j ACCEPT
        </screen>
      If you have other machines on your LAN wanting to connect to the NATed machine running &appname;, you need some trickery so the replies come back via the firewall.  Add this line after the four above:
        <screen>
$IPTABLES -t nat -A POSTROUTING -d $MYPC -s 192.168.1.0/24 -p tcp --dport 9176 -j SNAT --to $PRIVATEIP
        </screen>
      </para>
    </sect1>
  </chapter>
  <chapter id="faqs">
    <title>FAQs</title>
    <sect1 id="faqs-dcplusplus">
      <title>Why doesn't &appname; do &lt;favourite feature&gt;, like DC++ does?</title>
      <para>&appname; isn't a clone, imitation or port of DC++ or other DC clients.  It is an independent program that has been written from scratch.  Certainly there are similarities between these programs, because they are all trying to do the same job, and good features tend to be implemented in all clients eventually.  However that doesn't mean a feature will be added just because some other program does it.  Feature requests and suggestions are welcomed, but keep in mind that the developers are trying to make the best DC client they can, not just an imitation of another program.</para>
    </sect1>
    <sect1 id="faqs-debugoutput">
      <title>&appname; prints a whole lot of stuff to the console while its running.  What does it all mean?</title>
      <para>[FIXME - I don't feel qualified to answer this]</para>
    </sect1>
    <sect1 id="faqs-ssl">
      <title>SSL Transfer mode</title>
      <para></para>
    </sect1>
    <sect1 id="faqs-dc">
      <title>Where can I find out more about Direct Connect?</title>
      <para>Direct Connect is a program originally written by NeoModus <ulink url="http://www.neo-modus.com/"></ulink>.  Many other programs have been written that use the same protocol.  See <ulink url="http://sourceforge.net/docman/?group_id=36589"></ulink> for some details of the DC protocol.</para>
    </sect1>
  </chapter>
  <appendix id="shortcuts">
    <title>Keyboard Shortcuts</title>
    <itemizedlist>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+O</keysym></shortcut><guimenuitem>Options</guimenuitem></menuchoice></para></listitem>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+Q</keysym></shortcut><guimenuitem>Exit</guimenuitem></menuchoice></para></listitem>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+U</keysym></shortcut><guimenuitem>Hub List</guimenuitem></menuchoice></para></listitem>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+T</keysym></shortcut><guimenuitem>Transfer List</guimenuitem></menuchoice></para></listitem>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+S</keysym></shortcut><guimenuitem>Hub Search</guimenuitem></menuchoice></para></listitem>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+P</keysym></shortcut><guimenuitem>Spy</guimenuitem></menuchoice></para></listitem>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+F</keysym></shortcut><guimenuitem>Users</guimenuitem></menuchoice></para></listitem>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+N</keysym></shortcut><guisubmenu>Away Mode</guisubmenu><guimenuitem>Normal</guimenuitem></menuchoice></para></listitem>
      <listitem><para><menuchoice><shortcut><keysym>Ctrl+A</keysym></shortcut><guisubmenu>Away Mode</guisubmenu><guimenuitem>Away</guimenuitem></menuchoice></para></listitem>
    </itemizedlist>
  </appendix>
  <appendix id="chatcommands">
    <title>Chat commands</title>
    <para>These commands can be typed into any chat window.  &appname; intercepts the command and acts on it, the command itself is not sent to the hub.</para>
    <variablelist>
      <varlistentry>
        <term><command>/dchelp</command></term>
        <listitem><para>prints a list of the chat commands that are recognised by &appname;.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/clear</command></term>
        <listitem><para>clears all text from the chat window.  Works in public and private chat.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/mode</command></term>
        <listitem><para>shows the mode you are currently in (active or passive)</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/refresh</command></term>
        <listitem><para>rebuilds your share list.  It is good to do this every time you change your share.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/ts</command></term>
        <listitem><para>Toggles on or off the display of timestamps next to chat messages.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/dcgui or /adv</command></term>
        <listitem><para>Sends an advertisement for &appname; to the hub.  Don't use too heavily :)</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/join &lt;address&gt;</command></term>
        <listitem><para>Disconnects from this hub and connect you to the hub address specified instead.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/msg &lt;nick&gt; &lt;message&gt;</command></term>
        <listitem><para>Sends the private message to the person specified</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/away &lt;message&gt;</command></term>
        <listitem><para>Lets you specify a message that someone will see if they send you a private message while you are in away-mode.  If the message is blank, then the auto-response is disabled.</para></listitem>
      </varlistentry>
      <varlistentry> 
        <term><command>/bye &lt;message&gt;</command></term>
        <listitem><para>Disconnect from the hub.  If you wish you can provide a signoff message.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/uptime</command></term>
        <listitem><para>Shows you how long &appname; has been running.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/ls &lt;nick&gt;</command></term>
        <listitem><para>Downloads the share list of the user specified.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><command>/grant &lt;nick&gt;</command></term>
        <listitem><para>Grant the user a slot, which is valid for a single download.</para></listitem>
      </varlistentry>
      <varlistentry> 
        <term><command>/grantp &lt;nick></command></term>
        <listitem><para>Grant the user a permanent slot, which is valid indefinitely.</para></listitem>
      </varlistentry>
      <varlistentry> 
        <term><command>/friend &lt;nick&gt;</command></term>
        <listitem><para>Add the user to your friends list.</para></listitem>
      </varlistentry>
      <varlistentry> 
        <term><command>/fav</command></term>
        <listitem><para>Creates a bookmark for the hub.</para></listitem>
      </varlistentry>
      <varlistentry> 
        <term><command>/info</command></term>
        <listitem><para>Shows information about a user.  Only works in private chat.</para></listitem>
      </varlistentry>
      <varlistentry> 
        <term><command>/now</command></term>
        <listitem><para>Displays the current local time in the chat.  Useful for letting others know what time it is where you are.</para></listitem>
      </varlistentry>
      <varlistentry> 
        <term><command>/raw</command></term>
        <listitem><para>Send raw message.</para></listitem>
      </varlistentry>
    </variablelist>
  </appendix>
  <appendix id="configfiles">
    <title>Configuration files</title>
    <para>The first time it runs &appname; creates a directory called .dc in your home directory.  You won't be able to see it with a normal <command>ls</command> but it is there.  In that directory will appear the files listed below, for those of you who are curious.  Most of the files are in XML format, so are quite informative to read.  Like all good *nix programs, if you remove the .dc directory &appname; starts afresh like it had never been run.</para>

    <para>Not all of these files will always exist, as some are only created when you use certain features.  For example, if you haven't created any profiles, you won't have a <filename>dcprof.cfg</filename>.  You may see startup messages such as <computeroutput>warning: failed to load external entity "/home/username/.dc/dcprof.cfg"</computeroutput>.  These are just notices, it doesn't indicate a problem.</para>

    <variablelist>
      <varlistentry>
        <term><filename>MyList.DcLst</filename></term>
        <listitem><para>This is your share list, compressed using HE3.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>MyList.bz2</filename></term>
        <listitem><para>This is your share list, compressed using Bzip2.  It is usually smaller than the HE3 version.  You can look at it by using utilities such as bzless or bzcat.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>dcbookhub.cfg</filename></term>
        <listitem><para>The hubs you have bookmarked are stored here.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>dcgui.cfg</filename></term>
        <listitem><para>Configuration settings to do with the graphical interface and how it is displayed.  Set from the GUI and Sound tabs under Options.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>dchub.cfg</filename></term>
        <listitem><para>The list of all the public hubs &appname; knows of.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>dchubfilter.cfg</filename></term>
        <listitem><para>The hub-list filters you have set up.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>dclib.cfg</filename></term>
        <listitem><para>All the basic, non-gui related options.  Set from the Options menu of the program.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>dcprof.cfg</filename></term>
        <listitem><para>Your hub profiles, e.g. passwords for registration-required hubs.  Yes the passwords are stored in plain text.  If you are security conscious you should us unimportant passwords or don't save them in your profile.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>dctra.cfg</filename></term>
        <listitem><para>Your transfer queue, including file information (e.g. sizes, hashes, chunks), download sources and hubs.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>database.bin, filebase.bin, pathbase.bin</filename></term>
        <listitem><para>These three files make up a binary database of your fileshare.  This is used internally by &appname; as it is faster and more memory efficient than text files.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>searchbase.bin, searchfileindex.bin, searchindex.bin</filename></term>
        <listitem><para>These files are a binary database of keywords from your shared files.  &appname; uses this to quickly respond to file searches with minimum overhead.</para></listitem>
      </varlistentry>
    </variablelist>
  </appendix>
  <appendix id="connectionspeeds">
    <title>Connection speeds and transfer rates</title>

    <para>DC is all about sharing files, and the most important thing to many is how fast they can do this.  The main factor influencing this is what sort of internet connection you have.  In this document (and in the DC community) upload and download rates are often mentioned.  However if you are new to this you might not know what rate you have.</para>

    <para>The speed of a data link is usually given in kilobits per second, abbreviated as kb/s or kbps.  A '56k' modem is called that because its maximum downstream rate is 56 kilobits per second.  A 'half meg' DSL connection would have a downstream speed of half a megabit per second, or 500 kilobits per second.  It is helpful to others if you know, or can find out, what type and speed of connection you have.</para>

    <para>Many internet links are asymmetric, that is they have two different speeds, one for transfers from the internet to you (downstream) and one for transfers from you to the internet (upstream).  The upstream rate is usually less than the downstream, because that is the most efficient arrangement for tasks like web surfing or checking email.  Unfortunately its the wrong way round for file sharing applications, like DC.</para>

    <para>When it comes to transferring files, people are more interested in the speed they will see on their screen while they are downloading.  This is usually given in kilobytes per second, or kB/s.  Note the capitalisation of the letter B, this is important as it means Bytes insted of bits.  To work this out for your link, divide your link speed by eight.  Thus a 768kb/s link will let you download at 96kB/s, and a 33.6kb/s analogue modem will have a rate slightly over 4kB/s.  Note that when someone asks for your rate, they generally are interested in your upstream rate, which is the one that affects their downloads.</para>

    <para>kilo (k) = 1000 (one thousand) times, Mega (M) = 1000000 (one million) times, Giga (G) = 1000000000 (one billion) times. [FIXME - correct me if I'm wrong, but in this context 'kilo'=10^3, not 2^10]</para>

    <table id="connectionspeeds-table">
      <title>Examples of common connection types and speeds</title>
      <tgroup cols="3">
        <thead>
          <row>
            <entry>Connection type</entry>
            <entry>Downstream speed</entry>
            <entry>Upstream speed</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>56k modem</entry>
            <entry>56kbps (7kB/s)</entry>
            <entry>33kbps (4kB/s)</entry>
          </row>
          <row>
            <entry>64k ISDN</entry>
            <entry>64kbps (8kB/s)</entry>
            <entry>64kbps (8kB/s)</entry>
          </row>
          <row>
            <entry>128k ISDN</entry>
            <entry>128kbps (16kB/s)</entry>
            <entry>128kbps (16kB/s)</entry>
          </row>
          <row>
            <entry>256/64 ADSL (entry-level in Australia)</entry>
            <entry>256kbps (32kB/s)</entry>
            <entry>64kbps (8kB/s)</entry>
          </row>
          <row>
            <entry>512/128 ADSL</entry>
            <entry>512kbps (64kB/s)</entry>
            <entry>128kbps (16kB/s)</entry>
          </row>
          <row>
            <entry>512/256 ADSL (entry-level in UK)</entry>
            <entry>512kbps (64kB/s)</entry>
            <entry>256kbps (32kB/s)</entry>
          </row>
          <row>
            <entry>768/256 ADSL</entry>
            <entry>768kbps (96kB/s)</entry>
            <entry>256kbps (32kB/s)</entry>
          </row>
          <row>
            <entry>1024/256 ADSL</entry>
            <entry>1024kbps (128kB/s)</entry>
            <entry>256kbps (32kB/s)</entry>
          </row>
          <row>
            <entry>Cable</entry>
            <entry></entry>
            <entry></entry>
          </row>
          <row>
            <entry>Satellite</entry>
            <entry>[FIXME - include comment regarding latency]</entry>
            <entry></entry>
          </row>
          <row>
            <entry>Chello</entry>
            <entry></entry>
            <entry></entry>
          </row>
          <row>
            <entry>2Mbit Leased Line</entry>
            <entry>2Mbps (250kB/s)</entry>
            <entry>2Mbps (250kB/s)</entry>
          </row>
          <row>
            <entry>T1</entry>
            <entry>1.536 Mbps (192kB/s)</entry>
            <entry></entry>
          </row>
          <row>
            <entry>T3</entry>
            <entry>28 times T1 speed i.e. 43.008 Mbps (5.376MB/s)</entry>
            <entry></entry>
          </row>
          <row>
            <entry>10Mbit Ethernet</entry>
            <entry>10Mbps (1.25MB/s)</entry>
            <entry>10Mbps (1.25MB/s)</entry>
          </row>
          <row>
            <entry>100Mbit Ethernet</entry>
            <entry>100Mbps (12.5MB/s)</entry>
            <entry>100Mbps (12.5MB/s)</entry>
          </row>
          <row>
            <entry>Gigabit Ethernet</entry>
            <entry>1000Mbps (125MB/s)</entry>
            <entry>1000Mbps (125MB/s)</entry>
          </row>
          <row>
            <entry>OC-1</entry>
            <entry>51.840 Mbps (6.48MB/s)</entry>
            <entry></entry>
          </row>
          <row>
            <entry>OC-3/12/48/192</entry>
            <entry>3/12/48/192 times OC-1</entry>
            <entry></entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </appendix>
  <appendix id="glossary">
    <title>Glossary</title>
    <para>ACK - Acknowledgement</para>
    <para>NAT - Network Address Translation</para>
    <para>DSL - Digital Subscriber Line</para>
  </appendix>
</book>

