add a man page

4 files changed, 151 insertions, 179 deletions

diff --git a/CREDITS b/CREDITS
new file mode 100644
index 0000000..fc70fcd
--- /dev/null
+++ b/CREDITS
@@ -0,0 +1,35 @@
+#
+# Copyright (C) 2018 Svetlana 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/>.
+
+Many people have contributed to guppy.
+
+- Austin (aj00200), blockbot plugin author
+- aLaserShark
+- Cam
+- crazedpsyc, Archlinux maintainer
+- David Vo (auscompgeek)
+- DrKabob
+- Douglas Freed (dwfreed)
+- FurryHead, core author
+- jim
+- Kays, sed plugin author
+- Kudu
+- msemper
+- Nicolas Aragone (Juest), Windows tester
+- Ola Nystrom (olanys)
+- Ricky Nance (RiXtEr)
+- Svetlana Tkachenko (Sveta), maintainer
\ No newline at end of file
diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index b79e4ae..0000000
--- a/INSTALL
+++ /dev/null
@@ -1,97 +0,0 @@
-#
-# Copyright (C) 2010-2016 Svetlana A. Tkachenko <svetlana@members.fsf.org>
-# Copyright (C) 2016 Nicolas Aragone <niquito.larigone@gmail.com>
-#
-# 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/>.
-
-1) Download
-
-Use your operating system installer to download Guppy on these systems:
-
-* Archlinux
-* Windows (coming soon)
-
-Alternatively, use wget to download guppy over http, or use git.
-
-git clone git://git.gnu.org.ua/guppy.git in a empty folder
-*(for more information about git read docs/git)
-
-TortoiseGit GUI (Windows):
-a) create a empty folder
-b) right click the folder and click clone
-c) input git://git.gnu.org.ua/guppy.git as the clone URL (if you copied it you should have it filled for you)
-
-2) Directory structure
-
-After downloading guppy, the directory structure will be similar to something like this:
-
-    dist/
-    extra/
-    example.conf
-    guppy
-    INSTALL
-    irc.py
-    plugins/
-    README
-
-The extra/ directory contains plugins that are either unfinished or very specific, you will usually not need them. (You can put them in plugins/ before running the install script, if you need them, but do please read them first if you decide to do so.)
-
-The dist/ directory contains installation scripts for supported operating systems. (Arch)
-
-3) Configuration
-
-Run the guppy executably once to launch the installer script.
-
-   (generic) python guppy
-   (linux)$ ./guppy
-   (windows) double click _winguppy.bat (make sure you have python 3 installed and available in PATH)
-
-It will prompt you with a list of plugins. Choose carefully, the default is minimal!
-
-
-      __ _ _   _ _ __  _ __  _   _
-     / _` | | | | '_ \| '_ \| | | | http://repo.or.cz/w/guppy.git/summary
-    | (_| | |_| | |_) | |_) | |_| | irc://irc.freenode.net/guppy
-     \__, |\__,_| .__/| .__/ \__, | http://guppy.uk.to
-     |___/      |_|   |_|    |___/  
-     
-    Settings directory: <guppy path>/conf/
-    No configuration file found, running makeconf
-    What IRC network do I connect to (just the name)? []: Freenode
-    What is the IRC network address (eg. irc.example.org)? []: chat.freenode.net
-    What channels to automatically join (comma-separated, no spaces)? []: #guppy
-    What nickname should I use? []: GuppyBot
-    ...
-
-After the configuration, you will need to start it again; guppy is not a daemon/background/service script.
-
-4) Running in background
-
-You can start it in a persistent shell like screen or tmux:
-
-   $ screen -U ./guppy
-
-or
-
-   $ tmux ./guppy
-
-  In windows you can minimize it or hide it with a tool like nircmd
-
-5) Authentication
-
-Once the bot joins the channel, Anyone who uses the nicks listed in owners can control the bot, if you loaded auth plugin, you can optionally set up a password. Use the "passwd" command in PM with the bot to set a new password.
-
-    <user> passwd lam3r lam3r
-    <bot> Password successfully changed.
\ No newline at end of file
diff --git a/README b/README
index bef776e..91aacaf 100644
--- a/README
+++ b/README
@@ -16,16 +16,14 @@
 # You should have received a copy of the GNU General Public License
 # along with guppy.  If not, see <http://www.gnu.org/licenses/>.
 
-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.
+guppy is a multilingual internet relay chat (IRC) bot. It provides automated functions to an IRC live chat environment, such as mathematics, word lookup, and games.
 
-For more information about the freenode IRC network, supporting free
-and open-source communities since 1998, please visit www.freenode.net.
+guppy is in Python 3. It has an extensible event-driven plugins API. A sample plugin is included in the `extra/example.py` file.
 
-= Key features =
+guppy documentation is available in English, Russian, Hungarian, and Norwegian.
 
-- 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)).
+For more information about the freenode IRC network, supporting free
+and open-source communities since 1998, please visit www.freenode.net.
 
 = Extra features =
 
@@ -42,86 +40,16 @@ 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
-
-== Create a patch ==
-
-The best way to submit a patch is by attaching a patch to a bug report. A formatted patch is created using a "git format-patch" command which takes a revision Id from "git log" as a first argument.
-
-
+Please find usage instructions in the guppy man page:
 
-= Thanks =
+- man/guppy.1
+- http://git.gnu.org.ua/cgit/guppy.git/plain/man/guppy.1
 
-Thanks to all the past and current contributors. Listed in alphabetical order:
+= Authors =
 
-- 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
+Please see the CREDITS file.
 
 = Contact =
 
diff --git a/man/guppy.1 b/man/guppy.1
new file mode 100644
index 0000000..39a7596
--- /dev/null
+++ b/man/guppy.1
@@ -0,0 +1,106 @@
+.TH GUPPY 1
+.SH NAME
+guppy \- start a multilingual IRC bot
+.SH SYNOPSIS
+.B guppy
+[\fB\-h\fR]
+[\fB\-c\fR]
+[\fB\-v\fR]
+.SH DESCRIPTION
+.B guppy
+starts a multilingual internet relay chat (IRC) bot. It provides automated functions to an IRC live chat environment, such as mathematics, word lookup, and games.
+.PP
+guppy is in Python 3. It has an extensible event-driven plugins API. A sample plugin is included in the `extra/example.py` file.
+.PP
+guppy documentation is available in English, Russian, Hungarian, and Norwegian.
+
+.PP
+.SH "SETUP"
+
+.PP
+See the file README for installation instructions.
+.PP
+Once guppy is installed, it can be run using "python guppy" (generic) or "./guppy" (on unix based systems) or by double-clicking _winguppy.bat (on DOS systems).
+.PP
+On the first run guppy launches the configuration generation wizard. It prompts you for the network address, nick, and list of plugins to load. By default only a few plugins are enabled. The wizard shows an alphabetically sorted list of available plugins.
+.PP
+      __ _ _   _ _ __  _ __  _   _
+.br
+     / _` | | | | '_ \| '_ \| | | | http://repo.or.cz/w/guppy.git/summary
+.br
+    | (_| | |_| | |_) | |_) | |_| | irc://irc.freenode.net/guppy
+.br
+     \__, |\__,_| .__/| .__/ \__, | http://guppy.uk.to
+.br
+     |___/      |_|   |_|    |___/
+.br
+Settings directory: <guppy path>/conf/
+.br
+No configuration file found, running makeconf
+.br
+What IRC network do I connect to (just the name)? []: Freenode
+.br
+What is the IRC network address (eg. irc.example.org)? []: chat.freenode.net
+.br
+What channels to automatically join (comma-separated, no spaces)? []: #guppy
+.br
+What nickname should I use? []: GuppyBot
+.br
+...
+
+.PP
+After writing the configuration file, guppy exits.
+
+.PP
+.SH "USAGE"
+.PP
+Once the configuration file has been generated, you can run guppy to connect to IRC.
+.PP
+guppy stores its configuration settings and plugin data in a 'conf' subdirectory. guppy's configuration file is 'main.conf'. In addition, plugins may use their own configuration files. You can edit guppy configuration using your favourite editor, or by starting guppy with the \fB-c\fP command line option.
+.PP
+guppy directory contains 'conf', 'dist', 'extra', and 'plugins' directories. The extra/ directory contains plugins that are either unfinished or broken. The dist/ directory contains installation scripts for supported operating systems. The 'irc.py' file contains an IRC client implementation. 'guppy' contains the guppy command line interface and a plugin manager.
+.PP
+To recognize you, guppy has password authentification exposed as 'passwd' command of the 'auth' plugin. This command needs to be used in a private message. It provides access to privileged commands provided by this and other plugins, such as restarting guppy, joining channels, and loading other plugins.
+.PP
+To authenticate with NickServ, guppy sends it a private message. If NickServ is not present at the IRC network that you are using, server password (srpass) may be an alternative option if accepted by the IRC server.
+.PP
+To edit or add a plugin, edit it and put it into the 'plugins' directory. Then you need to load it if it is not loaded by the current configuration already. To do this, either modify the configuration file, or load the 'pluginloader' plugin and then use the 'load' command on IRC. The 'pluginloader' plugin also provides a 'reload' command.
+.PP
+.SH Debug networking
+.PP
+To debug connectivity issues, it may be necessary to mimic a unix OS user losing internet connection. This can be achieved by creating a new OS user to run guppy with. Then the iptables command may disable networking for the new user, assuming their uid is 1002:
+.PP
+# iptables -A OUTPUT -o eth0 -m owner --uid-owner 1002 -j DROP
+.PP
+To reset,
+.PP
+# iptables --flush
+.PP
+.SH OPTIONS
+.TP
+.BR \-h ", " \-\-help
+Shows a help message and exits.
+.TP
+.BR \-c ", " \-\-makeconf
+Generates a new configuration file.
+.TP
+.BR \-v ", " \-\-version
+Displays version information and exits.
+
+.PP
+.SH "REPORTING BUGS"
+Please report guppy bugs to <guppy-discuss@gnu.org.ua> or submit them online
+.PP
+Online bug tracker: <https://puszcza.gnu.org.ua/bugs/?func=additem&group=guppy>
+.PP
+The best way to submit a patch is by attaching a formatted patch to a bug report. A formatted patch is created using "git format-patch" command or an equivalent.
+.PP
+.SH COPYRIGHT
+.PP
+Copyright (C) 2018 Svetlana Tkachenko
+.br
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+