Ncdc 0.5 & 0.6 update + larger user guide

...I should perhaps commit more often.

dat/ncdc-changelog

@@ -1,3 +1,25 @@
+0.6 - 2011-08-08
+  - Added file searching, through a /search command
+  - Added tab to display the search results
+  - Listen for incoming messages on UDP in active mode
+  - Allow specifying a hub address with /open
+  - Fixed case-sensitivity of shared files
+  - Various bugfixes and other improvements
+
+0.5 - 2011-08-02
+  - Downloaded files are now TTH-checked
+  - Added download queue priorities
+  - Download queue items are automatically disabled on error
+  - Improved error handling and reporting for downloads
+  - Added download_slots setting
+  - Use a separate thread to load other users' file list
+  - Improved /gc to also clean up download queue related data
+  - Decreased memory usage for large file lists
+  - Improved error handling with sendfile()
+  - Fixed downloading in passive mode on ADC hubs
+  - Fixed adding a dir to the download queue while connected to the user
+  - Fixed segfault when the userlist is open while disconnecting from a hub
+
 0.4 - 2011-07-23
 	- Added file downloading support.
 	  WARNING: Downloaded files are not TTH checked at this moment.

index.cgi

@@ -15,6 +15,7 @@ TUWF::register(
   qr{ncdu/changes}  => \&ncduchangelog,
   qr{ncdu/man}      => \&ncdumanual,
   qr{ncdc}          => \&ncdc,
+  qr{ncdc/faq}      => \&ncdcfaq,
   qr{ncdc/guide}    => \&ncdcguide,
   qr{ncdc/changes}  => \&ncdcchangelog,
   qr{tuwf}          => \&tuwf,
@@ -51,6 +52,8 @@ sub home {
    E;
   end;
   h2 'Updates';
+  b '2011-08-08'; txt ' ncdc 0.6 released & user guide updated'; br;
+  b '2011-08-02'; txt ' ncdc 0.5 released!'; br;
   b '2011-07-23'; txt ' ncdc 0.4 released!'; br;
   b '2011-07-15'; txt ' ncdc 0.3 released!'; br;
   b '2011-06-27'; txt ' ncdc 0.2 released!'; br;
@@ -182,16 +185,15 @@ sub ncdc {
   $s->htmlHeader(title => 'NCurses Direct Connect', page => 'ncdc');
   p;
    lit <<'   E;';
-    <b>2003 called. They wanted me to write a text-mode alternative to DC++.</b><br />
     Ncdc is a modern and lightweight direct connect client with a friendly
     ncurses interface.
    E;
   end;
 
   h2 'Current Status';
-  p 'Ncdc is currently still in development, and still lacks many of the
+  p 'Ncdc is currently still in development, and therefore lacks a few features
-     features one would expect from a DC client. The following is a list of
+    one would expect from a full-blown DC client. The following is a list of
-     features that have been implemented so far:';
+    features that have been implemented so far:';
   ul;
    li 'Connecting to multiple hubs at the same time,';
    li 'Chatting and private messaging,';
@@ -201,20 +203,18 @@ sub ncdc {
    li 'File uploading in active and passive mode,';
    li 'Connections and download queue management,';
    li 'File list browsing,';
-   li 'Single-source file downloading.';
+   li 'Single-source and TTH-checked file downloading,';
+   li 'Searching for files.';
   end;
 
   h2 'Try it out';
   p;
-   b 'Latest version:'; txt ' 0.4 (';
+   b 'Latest version:'; txt ' 0.6 (';
-   a href => '/download/ncdc-0.4.tar.gz', 'download';
+   a href => '/download/ncdc-0.6.tar.gz', 'download';
    txt ' - '; a href => '/ncdc/changes', 'changes';
    txt ' - '; a href => '/download/ncdc.md5', 'md5';
    txt ' - '; a href => '/download/ncdc.sha1', 'sha1';
    txt ')'; br;
-   txt 'The current version might be slightly awkward to use and still lacks
-     many features. Nonetheless, it\'s already quite useful as a chat program
-     and upload server.'; br;
    txt 'You can also get the latest development version of ncdc from ';
    a href => 'http://g.blicky.net/ncdc.git/', 'this git repository';
    txt '. The README includes instructions to build ncdc.'; br;
@@ -229,43 +229,94 @@ sub ncdc {
     These dependencies should be easy to satisfy. Depending on your system, you
     may have all of these installed already.<br />
     Ncdc has been developed on a recent Arch Linux installation and has been
-    tested on FreeBSD 8.2 and Debian Squeeze. It should be fairly trivial to
+    tested on FreeBSD 8.2 and Debian Squeeze. I have also received reports from
-    port to other POSIX-like systems.<br />
+    people who successfully used it on Mac OS X, Ubuntu and CentOS. It should
+    be fairly trivial to port to other POSIX-like systems.<br />
     Ncdc is entirely written in C and available under a liberal MIT license.
    E;
   end;
+  $s->htmlFooter;
+}
 
-  h2 'Quick Q&A';
+
-  ul;
+sub ncdcfaq {
-   li; txt 'What about other text-mode clients?'; br;
+  my $s = shift;
-    a href => 'http://corsair626.no-ip.org/microdc/', 'microdc2';
+  $s->htmlHeader(title => 'Ncdc Q&A', page => 'ncdc', tab => 'faq');
-    txt ' - A rather nice client, yet not exactly there. It\'s limited to
+  p 'On this page I collect several questions that people may have and try to
-      connecting to a single hub, hasn\'t been updated since 2006, and the
+    answer them. If you have a question that is not covered here, don\'t hesitate
-      readline interface is slightly awkward to use.';br;
+    to ask!';
-    a href => 'http://sourceforge.net/projects/nanodc/', 'nanodc';
+  div class => 'pod';
-    txt ' - Can\'t comment much on this, except maybe that rocket science is
+
-      perhaps easier than getting nanodc to compile.'; br;
+  h2 'What about other text-mode clients?';
-    txt 'LDCC - Uses DCTC as backend and an interface based on TurboVision.
+  p;
-      All mentioned projects are dead: neither LDCC, DCTC nor TurboVision are
+   a href => 'http://corsair626.no-ip.org/microdc/', 'microdc2';
-      seeing any recent development.'; br;br;
+   txt ' - A rather nice client, yet not exactly there. It\'s limited to
-   end;
+     connecting to a single hub, hasn\'t been updated since 2006, and the
-   li; txt 'Can ncdc use the hash data or configuration from an existing DC++ installation?'; br;
+     readline interface is slightly awkward to use.'; br;
-    txt 'No, ncdc uses its own configuration and hash storage directory.
+   a href => 'http://sourceforge.net/projects/nanodc/', 'nanodc';
-      However, on popular demand I could write a conversion utility to transfer
+   txt ' - Can\'t comment much on this, except maybe that rocket science is
-      the hash data from other clients to ncdc\'s format.'; br;br;
+     perhaps easier than getting nanodc to compile.'; br;
-   end;
+   txt 'LDCC - Uses DCTC as backend and an interface based on TurboVision.
-   li; txt 'What protocol features does ncdc support?'; br;
+     All mentioned projects are dead: neither LDCC, DCTC nor TurboVision are
-    txt 'For ADC: Only BASE, RF, TIGR and BZIP so far. For NMDC:'; br;
+     seeing any recent development.';
-    txt 'Hub: NoGetINFO and NoHello.'; br;
-    txt 'Client: MiniSlots, XmlBZList, ADCGet, TTHL and TTHF.'; br;
-    txt q|That is pretty much everything you'd expect any modern client to
-      have. Note that ncdc does not support some of the older protocol
-      features, like $Get, $GetZBlock, $CHUNK, $Cancel or non-XML file lists. I
-      am not aware of an other up-to-date client that still uses any of these
-      features.|;
-   end;
   end;
 
+  h2 'Why did you start from scratch? Why not use the DC++ core?';
+  p;
+   lit <<'   E;';
+    There are many reasons why I chose not to use code from existing projects,
+    but all of them boil down to the following two: 1) I am a control freak,
+    and 2) personal preferences.<br />
+    That is the short answer. The long answer will require a full article,
+    and I don't feel like writing that much at this point. &gt;_&gt;
+   E;
+  end;
+
+  h2 'Can ncdc use the hash data or configuration from an existing DC++ installation?';
+  p 'No, ncdc uses its own configuration and hash storage directory.
+     However, on popular demand I could write a conversion utility to transfer
+     the hash data from other clients to ncdc\'s format.';
+
+  h2 'Does ncdc support TLS?';
+  p;
+   lit <<'   E;';
+    Not natively, at this moment at least. As a temporary solution, it is
+    possible to use <a href="http://www.stunnel.org/">stunnel</a> to connect to
+    TLS-enabled hubs. I have tested this to work for ADC, but have no
+    experience with TLS on NMDC hubs. This trick does not allow encrypted
+    client-to-client connections, so your file transfers will remain
+    unencrypted.<br />
+    The following example stunnel configuration is what I use to connect to the
+    DC Development hub:</p>
+    <pre>[dcdev]<br />client = yes<br />accept = 127.0.0.1:16591<br />connect = devpublic.adcportal.com:16591</pre>
+    <p>The URL `adc://127.0.0.1:16591/' can then be used to connect to the hub
+    from within ncdc.
+   E;
+  end;
+
+  h2 'Does ncdc support UPnP?';
+  p;
+   lit <<'   E;';
+    Again, not natively. However, it is possible to use <a
+    href="http://www.howtoforge.com/administrating-your-gateway-device-via-upnp">this
+    script</a> and manually keep a port open using a cron job. I have no
+    experience with this myself, though. I just run ncdc directly on my router. :-)
+   E;
+  end;
+
+  h2 'What protocol features does ncdc support?';
+  p;
+   lit <<'   E;';
+    For ADC: Only BASE, RF, TIGR and BZIP so far.<br />
+    For NMDC: NoGetINFO, NoHello, MiniSlots, XmlBZList, ADCGet, TTHL and TTHF.<br />
+    That is pretty much everything you'd expect any modern client to have. Note
+    that ncdc does not support some of the older protocol features, like $Get,
+    $GetZBlock, $CHUNK, $Cancel or non-XML file lists. I am not aware of an
+    other up-to-date client that still uses any of these features.
+   E;
+  end;
+
+  end 'div';
   $s->htmlFooter;
 }
 
@@ -321,7 +372,7 @@ sub ncdcguide {
    txt '/set active_port '; b '34194'; br;
    txt '/set active '; b 'true';
   end;
-  p "And make sure the port you specified is properly forwarded.";
+  p "And make sure the port you specified is properly forwarded for both TCP and UDP.";
 
   h2 'Connecting to hubs';
   p "This is where ncdc differs a bit from other DC or even IRC clients. To
@@ -377,6 +428,75 @@ sub ncdcguide {
    b 'm'; txt '   PM the selected user.'; br;
    b 'b'; txt '   browse the selected users\' list.'; br;
   end;
+
+  h2 'Searching';
+  p "To search for files to download, use the '/search' command:";
+  pre class => 'code';
+   lit '/search <b>gentoo</b>';
+  end;
+  p style => 'font-size: 9px; padding-left: 25px; padding-bottom: 3px',
+    "My apologies for using such a generic search term as example. It just
+    happens to be one that doesn't advocate piracy yet gives some results on
+    most hubs.";
+  p "See '/help search' for more options. A new tab will be opened with the
+    search results, where the following keys can be used:";
+  pre class => 'code';
+   b 'j/k'; txt ' the usual down/up keys.'; br;
+   b 'b'; txt '   browse users\' file list.'; br;
+   b 'd'; txt '   add selected file to download queue.'; br;
+   b 'f'; txt '   find user in the user list.'; br;
+   b 'h'; txt '   show/hide hub column.'; br;
+   b 'u'; txt '   order by username.'; br;
+   b 's'; txt '   order by file size.'; br;
+   b 'l'; txt '   order by available slots.'; br;
+   b 'n'; txt '   order by file name.'; br;
+  end;
+
+  h2 'Browsing file lists';
+  p "If you were paying attention to the previous sections, you would have
+    noticed that three ways to open a file list have been mentioned: The global
+    Alt+o key to open your own, the 'b' key in the user list to browse a users'
+    list, and a similar 'b' key for the search results. There is a fourth
+    method, and that is the '/browse' command, see '/help browse' for details
+    on that one.  Regardless of how you open a file list, the following keys
+    are available while browsing one:";
+  pre class => 'code';
+   b 'j/k'; txt ' the usual down/up keys. (this is getting boring)'; br;
+   b 'l'; txt '   open selected directory.'; br;
+   b 'h'; txt '   open parent directory.'; br;
+   b 'd'; txt '   add selected file to download queue.'; br;
+  end;
+
+  h2 'Download queue management';
+  p "Both the the search results and the file list browser have a 'd' key to
+    add a file to the download queue. Any queud files will be downloaded
+    automatically and this process will usually not require any further input.
+    Nonetheless, there is a download queue manager which can be accessed with
+    the global Alt+q key. The following keys can be used on this tab:";
+  pre class => 'code';
+   b 'j/k'; txt ' again, the down/up keys.'; br;
+   b 'f'; txt '   find user in the user list.'; br;
+   b 'd'; txt '   remove selected file from the queue.'; br;
+   b 'c'; txt '   find the related download connection in the connection list.'; br;
+   b '+'; txt '   increase download priority.'; br;
+   b '-'; txt '   decrease download priority.'; br;
+  end;
+  p "A little note on the download priorities: if you see that an item has
+    'ERR' as priority, this means that something went wrong while downloading.
+    In these cases you have two choices: remove the item from the queue ('d'
+    key), or tell ncdc to try it again by clearing the error status (that is,
+    by increasing the priority. That is, the '+' key.).";
+
+  h2 'Connection management';
+  p 'Last but not least, you can also monitor your currently active uploads and
+    downloads with the connections tab, which can be accessed with Alt+n. Keys:';
+  pre class => 'code';
+   b 'j/k'; txt ' guess.'; br;
+   b 'd'; txt '   disconnect selected connection.'; br;
+   b 'i'; txt '   toggle information box.'; br;
+   b 'f'; txt '   find user in the user list.'; br;
+   b 'q'; txt '   find item in the download queue.'; br;
+  end;
   $s->htmlFooter;
 }
 
@@ -884,6 +1004,7 @@ sub htmlHeader {
     if($o{page} eq 'ncdc') {
       div id => 'mtabs';
        a href => '/ncdc',         !$o{tab}             ? (class => 'sel') : (), 'main'; txt ' ';
+       a href => '/ncdc/faq',     $o{tab} eq 'faq'     ? (class => 'sel') : (), 'Q&A'; txt ' ';
        a href => '/ncdc/guide',   $o{tab} eq 'guide'   ? (class => 'sel') : (), 'user guide'; txt ' ';
        a href => '/ncdc/changes', $o{tab} eq 'changes' ? (class => 'sel') : (), 'changelog'; txt ' ';
       end;