Merge branch 'bug145-ProvideHelp'

* bug145-ProvideHelp:
  Use "${docdir}/Commands.txt" as help text file
  Add a note that "help file" is updated on startup and REHASH only
  Add doc/Commands.txt which should document all commands
  Implement Help() function parsing and returning the help text
  Document "HelpFile" in sample-ngircd.conf and ngircd.conf.5
  Implement new configuration option "HelpFile"
  IRC_HELP(): Code cleanup
  Refactor Read_Motd() into Read_TextFile()

3 files changed, 226 insertions, 1 deletions

diff --git a/doc/Commands.txt b/doc/Commands.txt
new file mode 100644
index 00000000..e9b78731
--- /dev/null
+++ b/doc/Commands.txt
@@ -0,0 +1,219 @@
+
+                     ngIRCd - Next Generation IRC Server
+                           http://ngircd.barton.de/
+
+               (c)2001-2013 Alexander Barton and Contributors.
+               ngIRCd is free software and published under the
+                   terms of the GNU General Public License.
+
+                              -- Commands.txt --
+
+
+This file lists all commands available on ngIRCd. It is written in a format
+that is human readable as well as machine parseable and therefore can be used
+as "help text file" of the daemon.
+
+In short, the HELP command parses this file as following when a user user
+issues a "HELP <cmd>" command:
+
+ 1. Search the file for a line "- <cmd>",
+ 2. Output all subsequent lines that start with a TAB (ASCII 9) character
+    to the client using NOTICE commands, treat lines containing a single "."
+    after the TAB as empty lines.
+ 3. Break at the first line not starting with a TAB character.
+
+This format allows to have information to each command stored in this file
+which will not be sent to an IRC user requesting help which enables us to
+have additional annotations stored here which further describe the origin,
+implementation details, or limits of the specific command.
+
+A special "Intro" block is returned to the user when the HELP command is
+used without a command name:
+
+
+- Intro
+	This is ngIRCd, a server software for Internet Relay Chat (IRC)
+	networks. You can find more information about ngIRCd on its homepage:
+		<http://ngircd.barton.de>
+	.
+	Use "HELP COMMANDS" to get a list of all available commands and
+	"HELP <command-name>" to get help for a specific IRC command, for
+	example "HELP quit" or "HELP privmsg".
+
+
+General Commands
+~~~~~~~~~~~~~~~~
+
+- AWAY
+
+- CAP
+
+- CHARCONV
+
+- HELP
+	HELP [<command>]
+	.
+	Show help information for a specific IRC <command>. The <command> name
+	is case-insensitive.
+	.
+	Use the command "HELP Commands" to get a list of all available commands.
+
+	The HELP command isn't specified by any RFC but implemented by most
+	daemons. If no help text could be read in, ngIRCd outputs a list of all
+	implemented commands when receiving a plain "HELP" command as well as
+	on "HELP Commands".
+
+	ngIRCd replies using "NOTICE" commands like ircd 2.10/2.11; other
+	implementations are using numerics 704, 705, and 706.
+
+
+- MODE
+
+- NICK
+
+- NOTICE
+
+- PASS
+
+- PING
+
+- PONG
+
+- PRIVMSG
+
+- QUIT
+	QUIT [<quit-message>]
+	.
+	End IRC session and disconnect from the server.
+	.
+	If a <quit-message> has been given, it is displayed to all the
+	channels that you are a member of when leaving.
+
+- USER
+
+- WALLOPS
+
+- WEBIRC
+
+
+Status and Informational Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- INFO
+
+- ISON
+
+- LINKS
+
+- LUSERS
+
+- METADATA
+
+- MOTD
+
+- NAMES
+
+- STATS
+
+- TIME
+
+- TRACE
+
+- USERHOST
+
+- VERSION
+
+- WHO
+
+- WHOIS
+
+- WHOWAS
+
+
+Channel Commands
+~~~~~~~~~~~~~~~~
+
+- INVITE
+
+- JOIN
+
+- KICK
+
+- LIST
+
+- PART
+
+- TOPIC
+
+
+Administrative Commands
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- ADMIN
+	ADMIN [<server>]
+	.
+	Show administartive information about an IRC server in the network.
+	If no server name has been given, the local server will respond.
+
+- CONNECT
+
+- DIE
+
+- DISCONNECT
+
+- GLINE
+
+- KILL
+
+- KLINE
+
+- OPER
+
+- REHASH
+
+- RESTART
+
+
+IRC Service Commands
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- SERVICE
+
+- SERVLIST
+
+- SQUERY
+
+- SVSNICK
+
+
+Server Protocol Commands
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- CHANINFO
+
+- ERROR
+	ERROR [<message> [<> [...]]]
+	.
+	Return an error message to the server. The first parameter, if given,
+	will be logged by the server, all further parameters are silently
+	ignored.
+	.
+	This command is silently ignored on non-server and non-service links.
+
+- NJOIN
+
+- SERVER
+
+- SQUIT
+
+
+Dummy Commands
+~~~~~~~~~~~~~~
+
+- SUMMON
+
+- USERS
+
+- GET
+
+- POST
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2b9b3aab..04f74b60 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,6 +1,6 @@
 #
 # ngIRCd -- The Next Generation IRC Daemon
-# Copyright (c)2001-2012 Alexander Barton (alex@barton.de) and Contributors
+# Copyright (c)2001-2013 Alexander Barton (alex@barton.de) and Contributors
 #
 # 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
@@ -12,6 +12,7 @@
 .tmpl:
 	$(AM_V_GEN)sed \
 	    -e "s@:ETCDIR:@${sysconfdir}@" \
+	    -e "s@:DOCDIR:@${docdir}@" \
 	    <$< >$@
 
 SUFFIXES = .tmpl
@@ -19,6 +20,7 @@ SUFFIXES = .tmpl
 static_docs = \
 	Bopm.txt \
 	Capabilities.txt \
+	Commands.txt \
 	Contributing.txt \
 	FAQ.txt \
 	GIT.txt \
diff --git a/doc/sample-ngircd.conf.tmpl b/doc/sample-ngircd.conf.tmpl
index 997a983d..1c3998ad 100644
--- a/doc/sample-ngircd.conf.tmpl
+++ b/doc/sample-ngircd.conf.tmpl
@@ -33,6 +33,10 @@
 	;AdminInfo2 = Location
 	;AdminEMail = admin@irc.server
 
+	# Text file which contains the ngIRCd help text. This file is required
+	# to display help texts when using the "HELP <cmd>" command.
+	;HelpFile = :DOCDIR:/Commands.txt
+
 	# Info text of the server. This will be shown by WHOIS and
 	# LINKS requests for example.
 	Info = Server Info Text