Released ncdc 0.1 and added a simple user guide

index.cgi

@@ -15,6 +15,7 @@ TUWF::register(
   qr{ncdu/changes}  => \&ncduchangelog,
   qr{ncdu/man}      => \&ncdumanual,
   qr{ncdc}          => \&ncdc,
+  qr{ncdc/guide}    => \&ncdcguide,
   qr{tuwf}          => \&tuwf,
   qr{tuwf/man(?:/(db|misc|request|response|xml))?}
                     => \&tuwfmanual,
@@ -49,6 +50,7 @@ sub home {
    E;
   end;
   h2 'Updates';
+  b '2011-06-20'; txt ' ncdc 0.1 released! And wrote a user guide for it.'; br;
   b '2011-06-11'; txt ' Added NCurses colour experiment at code dump => nc-colour'; br;
   b '2011-06-03'; txt ' Added my latest project: ncdc'; br;
   b '2011-02-07'; txt ' TUWF 0.1 released and now also available on CPAN'; br;
@@ -177,48 +179,54 @@ sub 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
+    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
+     features one would expect from a DC client. The following is a list of
+     features that have been implemented so far:';
+  ul;
+   li 'Connecting to multiple hubs at the same time,';
+   li 'Chatting and private messaging,';
+   li 'Browsing the user list of a connected hub,';
+   li 'Share management (file list generation, hashing, refreshing, etc),';
+   li 'File uploading in active and passive mode,';
+   li 'Connections tab,';
+   li 'Replying to search requests from other clients.';
+  end;
+
+  h2 'Try it out';
+  p;
+   b 'Latest version:'; txt ' 0.1 (';
+   a href => '/download/ncdc-0.1.tar.gz', 'download';
+   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;
+   txt 'Check out the '; a href => '/ncdc/guide', 'user guide'; txt ' to get started.';
+  end;
+
   h2 'Requirements';
   p;
    lit <<'   E;';
     The following libraries are required: ncurses, bzip2, gdbm, glib2 and libxml2.<br />
     These dependencies should be easy to satisfy. Depending on your system, you
     may have all of these installed already.<br />
-    <br />
+    Ncdc has been developed on a recent Arch Linux installation and has been
-    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
     port to other POSIX-like systems.<br />
-    <br />
+    Ncdc is entirely written in C and available under a liberal MIT license.
-    ncdc is entirely written in C and available under a liberal MIT license.
    E;
   end;
 
-  h2 'Current Status';
-  p 'ncdc is currently still in development, and still lacks many of the
-     features one would expect from a DC client. The following is a list of
-     features that have been implemented so far:';
-  ul;
-   li 'Connecting to multiple hubs at the same time,';
-   li 'Chatting and private messaging,';
-   li 'Browsing the user list of a connected hub,';
-   li 'Share management (file list generation, hashing, refreshing, etc),';
-   li 'File uploading in passive mode,';
-   li 'Replying to search requests from other clients.';
-  end;
-
-  h2 'Try it out';
-  p;
-   txt 'The current version might be slightly awkward to use and is not really
-     suited for serious use. Nonetheless, it\'s not entirely useless. You can 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.';
-  end;
-
   h2 'Quick Q&A';
   ul;
    li; txt 'What about other text-mode clients?'; br;
@@ -228,7 +236,10 @@ sub ncdc {
       readline interface is slightly awkward to use.';br;
     a href => 'http://sourceforge.net/projects/nanodc/', 'nanodc';
     txt ' - Can\'t comment much on this, except maybe that rocket science is
-      perhaps easier than getting nanodc to compile.'; br;br;
+      perhaps easier than getting nanodc to compile.'; br;
+    txt 'I believe there was another one which used DCTC as backend. I
+      can\'t find it anymore, but without a doubt it\'s also too old for modern
+      DC networks.'; br;br;
    end;
    li; txt 'Can ncdc connect to ADC hubs?'; br;
     txt 'Not yet. My initial focus is to get a working client for the old NMDC
@@ -255,6 +266,112 @@ sub ncdc {
 }
 
 
+sub ncdcguide {
+  my $s = shift;
+  $s->htmlHeader(title => 'Ncdc User Guide', page => 'ncdc', tab => 'guide');
+  p 'Since the built-in documentation of ncdc is not really complete yet, it
+    may be a bit hard to use for first-timers. This is a short guide to help
+    you get started with ncdc and to make up for the lack of proper
+    documentation. I\'m assuming that you already managed to install a recent
+    version of ncdc.';
+
+  h2 'Starting up';
+  p 'Simply run `ncdc\', and you should see something like the following screenshot:';
+  img src => '/img/ncdcstart.png', style => 'margin: 5px 0 0 10px; border: 1px solid #999', alt => 'Ncdc start-up screen.';
+
+  h2 'Basic settings';
+  p 'When you just started ncdc, the first thing you want to do is to change some basic settings:';
+  pre class => 'code';
+   txt '/set nick '; b 'MyNick';
+  end;
+  p 'And optionally, you may also want to change these:';
+  pre class => 'code';
+   txt '/set description '; b 'ncdc is awesome!'; br;
+   txt '/set connection '; b '10'; br;
+   txt '/set email '; b 'user@example.com';
+  end;
+  p 'What you can use with the \'connection\' setting is a bit vague, but
+    you\'re safe if you just set it to your option speed, in MBit/s. On public
+    hubs, you probably don\'t want to set an email address.';
+  p 'Note: these settings can also be changed on a per-hub basis. More on that below.';
+
+  h2 'Sharing';
+  p 'You can skip this section if you don\'t intent to share any files. To add a directory to your share, use the following command:';
+  pre class => 'code';
+   txt '/share '; b 'Virtual_name /path/to/actual/dir';
+  end;
+  p "And '/path/to/actual/dir' will be shared under the virtual directory
+    'Virtual_name', for which you are free to choose a name. Ncdc will
+    automatically index and hash the files in this directory. You can use
+    '/unshare' to remove a directory from your share and '/refresh' to
+    manually keep the index updated on changes. A refresh is automatically done
+    every hour by default, but can be changed using '/set autorefresh'.";
+
+  h2 'Active vs. passive';
+  p 'By default ncdc will use passive mode. If you are connected directly to
+    the internet or are behind a router that allows port forwarding, you will
+    probably want to enable active mode. To do so, issue the following
+    commands:';
+  pre class => 'code';
+   txt '/set active_ip '; b $s->reqIP; br;
+   txt '/set active_port '; b '34194'; br;
+   txt '/set active '; b 'true';
+  end;
+  p "And make sure the port you specified is properly forwarded.";
+
+  h2 'Connecting to hubs';
+  p "This is where ncdc differs a bit from other DC or even IRC clients. To
+    connect to a hub, you first need to name and open a 'hub tab', after which
+    you can use '/connect' to actually connect to the hub:";
+  pre class => 'code';
+   txt '/open '; b 'ghub'; br;
+   txt '/connect '; b 'dchub://ghub.no-ip.org:411/';
+  end;
+  p "The name you specify with '/open' will be used by ncdc to refer to this
+    hub. After this, you can always reconnect to this hub simply by typing '/open
+    ghub', without having to use the '/connect' again.";
+  p "Some settings can be changed on a per-hub basis, for example your nick.
+    Using the '/set' command on a hub tab will change the setting only for that
+    hub. You can use '/unset' to change a setting back to its global value.";
+
+  h2 'Global keybindings and commands';
+  p "You have probably noticed that '/open' created a new tab, and are probably
+    wondering how to switch between multiple tabs and do other funky stuff. The
+    following ASCII table lists some of the global keybindings you can use:";
+  pre class => 'code';
+   b 'Alt+j'; txt '     open previous tab.'; br;
+   b 'Alt+k'; txt '     open next tab.'; br;
+   b 'Alt+h'; txt '     move current tab left.'; br;
+   b 'Alt+l'; txt '     move current tab right.'; br;
+   b 'Alt+<num>'; txt ' open tab with number <num>.'; br;
+   b 'Alt+c'; txt '     close current tab.'; br;
+   b 'Alt+n'; txt '     open the connections tab.'; br;
+   b 'Ctrl+c'; txt '    quit ncdc.'; br;
+  end;
+  p "Lots of functionality is hidden behind commands and settings, use '/help'
+    to get a list of the commands and '/help <command>' for information about a
+    specific commands. '/set' can be used to get the list of available
+    settings, but these are not documented yet.";
+
+  h2 'User list';
+  p "To open the user list of a hub, use the '/userlist' command or hit Alt+u.
+    Here's a list of the keys you can use:";
+  pre class => 'code';
+   b 'j'; txt '   scroll down.'; br;
+   b 'k'; txt '   scroll up.'; br;
+   b 's'; txt '   order by share size.'; br;
+   b 'u'; txt '   order by username.'; br;
+   b 'o'; txt '   toggle sort OPs before others.'; br;
+   b 'd'; txt '   toggle description column.'; br;
+   b 'e'; txt '   toggle email column.'; br;
+   b 'c'; txt '   toggle connection column.'; br;
+   b 'i'; txt '   toggle information box.'; br;
+   b 'm'; txt '   PM the selected user.'; br;
+  end;
+  $s->htmlFooter;
+}
+
+
 
 
 #    T U W F
@@ -747,6 +864,12 @@ sub htmlHeader {
        a href => 'http://sourceforge.net/tracker/?group_id=200175', 'bug tracker (sf)';
       end;
     }
+    if($o{page} eq 'ncdc') {
+      div id => 'mtabs';
+       a href => '/ncdc',       !$o{tab}           ? (class => 'sel') : (), 'main'; txt ' ';
+       a href => '/ncdc/guide', $o{tab} eq 'guide' ? (class => 'sel') : (), 'user guide'; txt ' ';
+      end;
+    }
     if($o{page} eq 'tuwf') {
       div id => 'mtabs';
        a href => '/tuwf',     !$o{tab}             ? (class => 'sel') : (), 'main'; txt ' ';
@@ -847,7 +970,7 @@ sub css {
   #menu a { line-height: 25px; padding: 5px 8px; margin: 0 2px; color: #ccc; }
   #menu a:hover, #menu a.sel { background-color: #222; text-decoration: none }
   #main { margin: 30px auto 5px auto; background-color: #000; width: 700px; border: 2px solid #666; text-align: left; padding: 5px 10px 10px 10px }
-  #mtabs { margin: 30px 0 -28px 0; } 
+  #mtabs { margin: 30px 0 -28px 0; }
   #mtabs a { background-color: #222; color: #ccc; font-size: 13px; margin: 0 2px; padding: 0 10px 3px 10px; border: 1px solid #666; border-bottom: 2px solid #666 }
   #mtabs a:hover { background-color: #000; text-decoration: none }
   #mtabs a.sel { border-bottom: 2px solid #000; background-color: #000; }
@@ -856,7 +979,8 @@ sub css {
   h2 { font-size: 16px; color: #888; margin-top: 25px; margin-bottom: 1px; }
   b { font-weight: bold; color: #fff }
   ul { margin-left: 20px }
-  pre, code { font: 11px monospace; }
+  pre, code, pre b { font: 11px monospace; }
+  pre b { font-weight: bold }
   pre.code, .pod pre { background: #111; border: 1px dotted #666; margin: 5px 10px; display: block; padding: 5px; }
   .indexgroup ul { margin-left: 5px; list-style-type: none }
   .indexgroup ul ul { margin-left: 20px }