merge docs into README

5 files changed, 106 insertions, 146 deletions

diff --git a/README b/README
index 10ac4c8..17ceba2 100644
--- a/README
+++ b/README
@@ -16,12 +16,113 @@
 # You should have received a copy of the GNU General Public License
 # along with guppy.  If not, see <http://www.gnu.org/licenses/>.
 
-Website:  http://guppy.uk.to
-Channel: irc://irc.freenode.net/guppy
-
-Feedback means are #guppy at freenode.
+guppy - A free multilingual live chat (IRC) bot. She serves common tasks like calculation, web search, words and domain look-up. guppy is available in English, Russian, Hungarian, and Norwegian.
 
 For more information about the freenode IRC network, supporting free
 and open-source communities since 1998, please visit www.freenode.net.
 
-For installation and usage instructions, please see the INSTALL file.
+= Key features =
+
+- Is available in multiple languages.
+- Communicates with live chat over IRC, which does not require signup.
+- Free software. Released under the GNU Public Licence v2 or later. Requires Python (available under the Python Software Foundation License (PSFL)).
+
+= Extra features =
+
+- Can encrypt the connection using TLS.
+- Can connect using IPv6.
+- Can make simultaneous connections to multiple networks.
+- Can run on UNIX, Windows, Linux, and Mac.
+- Is modular and extensible to easily write a new plugin using provided sample plugins.
+
+= Download =
+
+guppy may be downloaded from the `git://git.gnu.org.ua/guppy.git` git repository.
+
+- HTTP download: coming soon
+- Repository web browser: http://git.gnu.org.ua/cgit/guppy.git/tree/
+
+= Install =
+
+guppy may be installed by launching it and following the first run wizard. Then guppy will exit; launch it again to connect to IRC and get started.
+
+= Usage =
+
+== How to authenticate you with guppy ==
+
+guppy has password authentification exposed as 'passwd' command of the 'auth' plugin. This command needs to be used in a private message.
+
+== How to authenticate guppy with NickServ ==
+
+what guppy does when it has a ns username and password set is:
+'/msg nickserv identify accountname pwd' onconnect
+some networks want '/msg nickserv identify pwd'
+some networks do _not_ accept '/msg nickserv identify accountname pwd'
+
+if this is your case, try setting server password to 'passwordhere' or 'username:passwordhere' like this:
+
+ +verbatim+
+ ns_name =
+ ns_pwd =
+ srpass = yourPasswordHere
+ -verbatim-
+
+= Hack =
+
+Directory structure: guppy comes as the source files, which are passed to the Python to interpret them and run. This has two clear advantages. Firstly, Python is free; you can get it and hack on it and share with friends and it is a friendly platform to be with. Secondly, you get direct access to guppy's own source and can start hacking on it straight away. This is what the guppy directory structure is like:
+
+ +verbatim+
+ conf/
+ dist/
+ extra/
+ guppy
+ irc.py
+ plugins/
+ README
+ -verbatim-
+
+The extra/ directory contains plugins that are either unfinished or broken. The dist/ directory contains installation scripts for supported operating systems.
+
+- Example plugin: extra/example.py
+    - http://git.gnu.org.ua/cgit/guppy.git/plain/extra/example.py
+
+== Debug networking ==
+
+For debugging, to make a unix OS user lose internet connection, run
+
+# iptables -A OUTPUT -o eth0 -m owner --uid-owner 1002 -j DROP
+
+To reset,
+
+# iptables --flush
+
+= Thanks =
+
+Thanks to all the past and current contributors. Listed in alphabetical order:
+
+- Austin (aj00200)
+- aLaserShark
+- Cam
+- crazedpsyc, Archlinux maintainer
+- David Vo (auscompgeek)
+- DrKabob
+- Douglas Freed (dwfreed)
+- FurryHead, core author
+- jim
+- Kays
+- Kudu
+- msemper
+- Nicolas Aragone (Juest), Windows tester
+- Ola Nystrom (olanys)
+- Ricky Nance (RiXtEr)
+- Svetlana Tkachenko (gry), maintainer
+
+= Contact =
+
+Please use the guppy-discuss@gnu.org.ua mailing list:
+
+- http://mail.gnu.org.ua/mailman/listinfo/guppy-discuss
+
+Or #guppy at freenode for live chat:
+
+- irc://chat.freenode.net/guppy
\ No newline at end of file
diff --git a/doc/TODO b/doc/TODO
deleted file mode 100644
index 550983b..0000000
--- a/doc/TODO
+++ /dev/null
@@ -1,38 +0,0 @@
-#
-# Copyright (C) 2010-2016 Svetlana A. Tkachenko <svetlana@members.fsf.org>
-#
-# This file is part of guppy.
-#
-# guppy 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 3 of the License, or
-# (at your option) any later version.
-#
-# guppy 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 guppy.  If not, see <http://www.gnu.org/licenses/>.
-
-== Style guidelines ==
-
-* Don't mix tabs and spaces in one file. It is currently recommended to use 4 spaces for indentation (discussion is welcome as long as we agree to convert existing files to a new style).
-
-== TODO == *OUTDATED*
-
-Deadline: December 10, 2012
-
-[ ] Core fixes
-  [ ] set guppy to reconnect after ping timeouts (currently this works unreliably)
-  [ ] when an exception happens during a xxx plugin load, don't say 'no plugin xxx found' for a next load attempt
-  [ ] handle ssl warnings
-  [ ] fix that guppy freezes after a while of idling in a channel
-  [ ] ircv3 support
-  [ ] optional core fixes
-    [ ] split sent lines if too long
-    [ ] warn when loading a module if it has no docstring
-
-[ ] plugins
-  [ ] create chansever plugin to update autojoin when guppy joins or parts channels
-  [ ] add plugin tags functionality ( ie networking plugins, wikimedia plugins, ...; to group plugins other than alphabetical list )
diff --git a/doc/debug_networking b/doc/debug_networking
deleted file mode 100644
index 2eb6fad..0000000
--- a/doc/debug_networking
+++ /dev/null
@@ -1,24 +0,0 @@
-# Copyright (C) 2010-2016 Svetlana A. Tkachenko
-#
-# This file is part of guppy.
-#
-# guppy 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 3 of the License, or
-# (at your option) any later version.
-#
-# guppy 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 guppy.  If not, see <http://www.gnu.org/licenses/>.
-
-For debugging, to make a unix OS user lose internet connection, run
-
-# iptables -A OUTPUT -o eth0 -m owner --uid-owner 1002 -j DROP
-
-To reset,
-
-# iptables --flush
-
diff --git a/doc/ns_auth b/doc/ns_auth
deleted file mode 100644
index c3f9c55..0000000
--- a/doc/ns_auth
+++ /dev/null
@@ -1,31 +0,0 @@
-#
-# Copyright (C) 2010-2016 Svetlana A. Tkachenko
-#
-# This file is part of guppy.
-#
-# guppy 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 3 of the License, or
-# (at your option) any later version.
-#
-# guppy 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 guppy.  If not, see <http://www.gnu.org/licenses/>.
-
-what guppy does when it has a ns username and password set is:
-'/msg nickserv identify accountname pwd' onconnect
-some networks want '/msg nickserv identify pwd'
-some networks do _not_ accept '/msg nickserv identify accountname pwd'
-
-if this is your case, try setting server password to 'passwordhere' or 'username:passwordhere'
-
-ns_name =
-ns_pwd =
-srpass = yourPasswordHere
-
-^^ like this
-
---gry
diff --git a/doc/wishlist b/doc/wishlist
deleted file mode 100644
index 292f52c..0000000
--- a/doc/wishlist
+++ /dev/null
@@ -1,48 +0,0 @@
-# Copyright (C) 2010-2016 Svetlana A. Tkachenko
-#
-# This file is part of guppy.
-#
-# guppy 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 3 of the License, or
-# (at your option) any later version.
-#
-# guppy 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 guppy.  If not, see <http://www.gnu.org/licenses/>.
-
-Wishlist
-
-Attention - this wishlist is outdated and the homepage is being updated to include a bug tracker!
-
-== Core ==
-  * Implement [[http://ircv3.atheme.org/|IRC "v3"]] compatibility (where reasonable).
-  * <del>Implement ''self.server.mynick'' to reflect nick changes, after which bot nick is not the conf nick.</del> Unneeded?
-  * Adding tags/categories for available commands could increase usability.
-  * Read [[http://tools.ietf.org/html/rfc1459|RFC1459]] and add any issues to 'current'.
-  * jabber suppport
-  * Rate-limit sent lines.
-
-== Plugins ==
-  * An idea was/is to create a plugin for a multi-network relay for linking channels.
-  * Create a patch plugin. User says '!patchadd url comment' and bot adds the information to queue which bot owner can see using '!patchlist' or something like that. Possible shorter command names easier to remember and owner access to delete patches or change comments.
-  * Create an RSS or Atom feed plugin (whichever easier or both).
-  * Create a Trout plugin (similar as smack).
-  * Extend blockbot plugin
-    * to have several levels of reaction to flood.
-    * to kick people when there's too many (like +l but in the bot). Optional feature?
-    * to check for spam strings in part or quit messages.
-    * to kick or ban on join/part or join/quit floods.
-    * to enter emergency mode (+m for flood, +i for join flood, etc).
-  * Add ip tracking to auth plugin (warnings or blocks for people who have an account from an ip but try to authenticate as another user).
-
-== Other ==
-
-  * a cronjob line
-
-== External links ==
-  * [[http://thc.org/root/phun/unmaintain.html|Roedy Green. How To Write Unmaintainable Code - Ensure a job for life ;-)]]
-