microdc2 - Introduction
======================

microdc is a command-line based Direct Connect client that uses the GNU
Readline library for user interaction. It was developed from ground up and
does not depend on any other program. Despite the command-line user
interface, microdc was designed to be user friendly and simple to use.

microdc is currently in late beta state - there may be many bugs not yet
discovered. It also lacks some features that other clients support, such as
file hashing, multiple hub connections, and hub list support.

microdc is free software - it is licensed under the terms of the GNU
General Public License (GPL). It is written in C by Oskar Liljeblad, and is
designed to compile and run on modern POSIX compatible systems such as
Linux.

Features
========

The features of microdc include:

 * Nearly full support of the original Direct Connect protocol.
 * GNU Readline support.
 * Sensible tab-completion of commands, user names, local files, remote
   files, connection names and many other things.
 * One process per connection for optimal transfer rates.
 * Small memory footprint (I think).

There are many features that I would like to implement. See the TODO
document in the source code tarball for details. If you would like to
develop or contribute to microdc, you are more than welcome. Please contact
me - see the Feedback section below for contact information.

Copyright and License
=====================

microdc is copyright (C) 2004, 2005 Oskar Liljeblad

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 51
Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

The source code of this project may contain files from other projects, and
files generated by other projects, including:

 * GNU Autoconf (http://www.gnu.org/software/autoconf/)
 * GNU Automake (http://sources.redhat.com/automake/)
 * GNU gettext (http://www.gnu.org/software/gettext/)
 * Gnulib (http://www.gnu.org/software/gnulib/)
 * Autoconf Macro Archive (http://ac-archive.sourceforge.net/)

Such files are licensed under the terms of the GNU General Public License
or a license compatible with the GNU GPL (as listed on
http://www.gnu.org/licenses/license-list.html). See each file for copyright
details.

The translations in the po directory may contain translations from other
projects, including:

 * GNU C Library (http://www.gnu.org/software/libc/libc.html)
 * GNU Core Utilities (http://www.gnu.org/software/coreutils/)

See the specific message file (PO file) for copyright of those messages.

Requirements
============

The following programs are required to build microdc:

 * GNU C Compiler (gcc), version 3.0 or later

   microdc makes use of some gcc 3.x features such as declarations in the
   middle of a block and always inlined functions. The GNU C Compiler is
   part of the GNU Compiler Collection which can be downloaded from
   http://gcc.gnu.org/. In Debian and many other distributions the package
   is called gcc.

 * make, a modern implementation

   The make program is required to build microdc. microdc uses Makefiles
   generated by GNU Automake. The recommended make is GNU Make which can be
   downloaded from http://www.gnu.org/software/make/. In Debian and many
   other distributions the package is called make.

The following libraries are required to run microdc:

 * GNU Readline Library, version 4.0 or later

   microdc uses Readline for user input. GNU Readline can be downloaded
   from http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html. Libraries
   such as libedit and libeditline do not support the necessary completion
   features of GNU Readline, and can as such not be used with microdc. In
   Debian woody the required package is libreadline4 (libreadline4-dev
   during build). In testing and later, the recommended package is
   libreadline5 (and libreadline5-dev when building).

Building
========

To build the microdc executable, simply run

   ./configure
   make

If you want to install microdc on your system, run make install. This will
copy the executable, manual page and locale files to the appropriate
directories.

For more information regarding configure and make, see the INSTALL
document.

Usage and Customization
=======================

microdc is usually started like this:

   microdc

(Some command line options are available - run microdc --help to get a
list.) Once started, a prompt is displayed and microdc is ready for your
command. You can get a list of commands by pressing tab on the empty prompt
or by issuing the help command. The help command can also be used to get
information on a specific command:

   help exit

The first thing you would do is setting share and download directory:

   set sharedir /path/to/files/i/want/to/share
   set downloaddir /path/where/i/want/downloaded/files/saved

If you are not behind a firewall that prevents you from receiving
connections from the outside world, you can use the set active command to
enable active mode. Set the desired port to listen on client connections on
using listenport, then enable active mode:

   set listenport 10101
   set active 1

If you omit the set listenport command, a random free port will be picked
for you. There are many commands to change your settings, some of them are:

   set nick my_neat_nickname
   set description "I have nothing to share"
   set email i.m.living@off.the.example.net
   set speed 56Kbps

Next you must connect to a hub. Use the connect command to do this:

   connect my.favorite.hub.example.com:43912

The port part (":43912") is optional.

Once connected, you can chat a little:

   say "Hello all, I'm using this new DC client called microdc!"
   msg some_operator "Please don't ban me, microdc is still in development!"

Note that the double quotes aren't strictly necessary in this case, but if
you don't use them all consecutive whitespace will be translated to a
single space (e.g. "foo   bar" becomes "foo bar"). Semicolon (;) and number
sign (#) will also have special meanings, just like in the shell. Semicolon
is used to separate multiple commands on one line, and number sign as the
first character of a word will introduce comments. <p>You can get a list of
users online:

   who

Or you can browse other people's files:

   browse some_user

The first time you issue the browse command, the user's file list will be
downloaded and saved to the listing directory, which is usually
/tmp/microdc.PID. This can be changed with the set listingdir command. The
listing files will be removed when you exit microdc. Note that the prompt
will change when the file list has been downloaded and processed. The
following commands are available when browsing:

   cd some/dir
   pwd
   ls some/dir/or/file
   ls -l some/dir/or/file
   get some/dir/or/file

The cd command changes directory, pwd prints the current directory, ls
lists files and get downloads or queues files for download. (Tab completion
is supported for remote file listings when browsing, so I recommend using
that.) Once finished browsing the user, enter browse with no arguments to
stop browsing that user:

   browse

Downloads will start as soon as you enter the get command. A list of user
connections can be retrieved using the transfers command:

   transfers

This command will list all connections along with their names and current
status. You can disconnect a connection using the cancel command:

   cancel my_friend|UL

Use the search command to search for files:

   search favorite open source program

The names of the files returned will contain all of the words specified
with the search command. At the moment it is not possible to specify file
type, or minimum or maximum size. The review the results of a search
operation, use the results command:

   results 1

If you omit the search index to the results command, it will list all
issued searches.

Once finished playing around with microdc, quit with exit:

   exit

If you want to execute some commands on start up (such as setting your
nickname or active setting), you can place them in .microdc/config in your
home directory. This directory also holds the history file
(.microdc/history).

One last thing: If your find that microdc is being banned from hubs, try
change the client tag with the tag command, e.g.:

   set tag ++ V:0.401

References
==========

Note that this list of references is not complete.

Protocol references:

 * Direct Connect protocol reference
   (http://www.lwave.ca/shasta/protocol.html)

 * Direct Connect protocol reference (alternate version)
   (http://wza.digitalbrains.com/DC/doc/Introduction.html)

 * DC++ Wiki (http://dcplusplus.sourceforge.net/wiki/)

 * DC++ $UserIp2 extension (http://dc.ade.se/userip/)

Homepage
========

Web site and file area for microdc is hosted on Savannah:

   http://www.nongnu.org/microdc/

The latest version of microdc should always be available on this site.

Feedback
========

Please send bug reports, suggestions, ideas or comments in general to the
mailing list:

   microdc-devel@nongnu.org (http://lists.nongnu.org/mailman/listinfo/microdc-devel)

The author of microdc and this document, Oskar Liljeblad, can be contacted
by e-mail on the following address:

   oskar@osk.mine.nu (mailto:oskar@osk.mine.nu)

If you would like to get involved with this project, please don't hesitate
to write to the mailing list or the author (me)! All contributions are
welcomed.

Known bugs and missing features
===============================

There is no support for multiple share directories at this time, but
microdc will follow symbolic links when scanning for files to share. This
way you can share files on multiple drives and have full control of the
share directory layout.

You might get this error when connected and logging in to a hub:

   Cannot send to hub - Connection reset by peer

This means that the hub has disconnected you, and that microdc did not yet
receive the reason. This happens on some hubs with bots that can disconnect
you.

When there are more than a screen-full of completion matches, readline will
display a question "Display all N possibilities? (y or n)". No hub input
can be processed until this question is answered due to the internal design
of microdc.

Weird things may happen to the prompt when resizing the window. I am
currently investigating this problem.

Things to do
============

Please see the TODO document.

-