Add real manual pages

To some extent they duplicate the README but from a different angle.

5 files changed, 294 insertions, 8 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 7da0cd8..7911d5c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -191,19 +191,21 @@ install (DIRECTORY plugins/zyklonb/
 install (DIRECTORY plugins/degesch/
 	DESTINATION ${CMAKE_INSTALL_DATADIR}/degesch/plugins)
 
-# Generate documentation from program help
-find_program (HELP2MAN_EXECUTABLE help2man)
-if (NOT HELP2MAN_EXECUTABLE)
-	message (FATAL_ERROR "help2man not found")
+# Generate documentation from text markup
+find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor)
+if (NOT ASCIIDOCTOR_EXECUTABLE)
+	message (FATAL_ERROR "asciidoctor not found")
 endif ()
 
 foreach (page zyklonb degesch kike)
 	set (page_output "${PROJECT_BINARY_DIR}/${page}.1")
 	list (APPEND project_MAN_PAGES "${page_output}")
 	add_custom_command (OUTPUT ${page_output}
-		COMMAND ${HELP2MAN_EXECUTABLE} -N
-			"${PROJECT_BINARY_DIR}/${page}" -o ${page_output}
-		DEPENDS ${page}
+		COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
+			-a release-version=${project_version}
+			"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			-o "${page_output}"
+		DEPENDS ${page}.adoc
 		COMMENT "Generating man page for ${page}" VERBATIM)
 endforeach ()
 
diff --git a/README.adoc b/README.adoc
index 4d1df62..5c3eb6c 100644
--- a/README.adoc
+++ b/README.adoc
@@ -76,7 +76,7 @@ a package with the latest development version from Archlinux's AUR.
 
 Building
 --------
-Build dependencies: CMake, pkg-config, help2man, awk, sh, liberty (included) +
+Build dependencies: CMake, pkg-config, asciidoctor, awk, liberty (included) +
 Runtime dependencies: openssl +
 Additionally for degesch: curses, libffi, lua >= 5.3 (optional),
                           readline >= 6.0 or libedit >= 2013-07-12
diff --git a/degesch.adoc b/degesch.adoc
new file mode 100644
index 0000000..63e46b4
--- /dev/null
+++ b/degesch.adoc
@@ -0,0 +1,127 @@
+degesch(1)
+==========
+:doctype: manpage
+:manmanual: uirc3 Manual
+:mansource: uirc3 {release-version}
+
+Name
+----
+degesch - an experimental IRC client
+
+Synopsis
+--------
+*degesch* [_OPTION_]...
+
+Description
+-----------
+*degesch* is a scriptable IRC client for the command line.  On the first run
+it will welcome you with an introductory message.  Should you ever get lost,
+use the */help* command to obtain more information on commands or options.
+
+Options
+-------
+*-f*, *--format*::
+	Format IRC text from the standard input, converting colour sequences and
+	other formatting marks to ANSI codes retrieved from the *terminfo*(5)
+	database:
++
+```
+printf '\x02bold\x02\n' | degesch -f
+```
++
+This feature may be used to preview server MOTD files.
+
+*-h*, *--help*::
+	Display a help message and exit.
+
+*-V*, *--version*::
+	Output version information and exit.
+
+Key bindings
+------------
+Most key bindings are inherited from the frontend in use, which is either GNU
+Readline or BSD editline.  A few of them, however, are special to the IRC client
+or assume a different function.  This is a list of all local overrides and
+their respective function names:
+
+*M-p*::
+	Go up in history for this buffer (normally mapped to *C-p*).
+*M-n*::
+	Go down in history for this buffer (normally mapped to *C-n*).
+*C-p*, *F5*: *previous-buffer*::
+	Switch to the previous buffer in order.
+*C-n*, *F6*: *next-buffer*::
+	Switch to the next buffer in order.
+*M-TAB*: *switch-buffer*::
+	Switch to the last buffer, i.e., the one you were in before.
+*M-0*, *M-1*, ..., *M-9*: *goto-buffer*::
+	Go to the N-th buffer (normally sets a repeat counter).
+	Since there is no buffer number zero, *M-0* goes to the tenth one.
+*M-!*: *goto-highlight*::
+	Go to the first following buffer with an unseen highlight.
+*M-a*: *goto-activity*::
+	Go to the first following buffer with unseen activity.
+*PageUp*: *display-backlog*::
+	Show the in-memory backlog for this buffer in the backlog helper,
+	which is almost certainly the *less*(1) program.
+*M-h*: *display-full-log*::
+	Show the log file for this buffer in the backlog helper.
+*M-H*: *toggle-unimportant*::
+	Hide all join, part and quit messages, as well as all channel mode changes
+	that only relate to user channel modes.  Intended to reduce noise in
+	channels with lots of people.
+*M-e*: *edit-input*::
+	Run an editor on the command line, making it easy to edit multiline
+	messages.  Remember to save the file before exit.
+*M-m*: *insert-attribute*::
+	The next key will be interpreted as a formatting mark to insert:
+	*c* for colours (optionally followed by numbers for the foreground
+	and background), *i* for italics, *b* for bold text, *u* for underlined,
+	*x* for struck-through, *v* for inverse text and *o* resets all formatting.
+*C-l*: *redraw-screen*::
+	Should there be any issues with the display, this will clear the terminal
+	screen and redraw all information.
+
+Additionally, *C-w* and *C-u* in editline behave the same as they would in
+Readline or the "vi" command mode, even though the "emacs" mode is enabled
+by default.
+
+Bindings can be customized in your _.inputrc_ or _.editrc_ file.  Both libraries
+support conditional execution based on the program name.  Beware that it is easy
+to make breaking changes.
+
+Environment
+-----------
+*VISUAL*, *EDITOR*::
+	The editor program to be launched by the *edit-input* function.
+	If neither variable is set, it defaults to *vi*(1).
+
+Files
+-----
+*degesch* follows the XDG Base Directory Specification.
+
+_~/.config/degesch/degesch.conf_::
+	The program's configuration file.  Preferrably use internal facilities, such
+	as the */set* command, to make changes in it.
+
+_~/.local/share/degesch/logs/_::
+	When enabled by *behaviour.logging*, log files are stored here.
+
+_~/.local/share/degesch/plugins/_::
+_/usr/local/share/degesch/plugins/_::
+_/usr/share/degesch/plugins/_::
+	Plugins are searched for in these directories, in order.
+
+Bugs
+----
+The editline (libedit) frontend is more of a proof of concept that mostly seems
+to work but exhibits bugs that are not our fault.
+
+Reporting bugs
+--------------
+Use https://git.janouch.name/p/uirc3 to report bugs, request features,
+or submit pull requests.
+
+See also
+--------
+*less*(1), *readline*(3) or *editline*(7)
diff --git a/kike.adoc b/kike.adoc
new file mode 100644
index 0000000..e97cba2
--- /dev/null
+++ b/kike.adoc
@@ -0,0 +1,53 @@
+kike(1)
+=======
+:doctype: manpage
+:manmanual: uirc3 Manual
+:mansource: uirc3 {release-version}
+
+Name
+----
+kike - an experimental IRC daemon
+
+Synopsis
+--------
+*kike* [_OPTION_]...
+
+Description
+-----------
+*kike* is a basic IRC daemon for single-server networks, suitable for testing
+and private use.  When run without a configuration file, it will start listening
+on the standard port 6667 and the "any" address.
+
+Options
+-------
+*-d*, *--debug*::
+	Do not daemonize, print more information on the standard error stream
+	to help debug various issues.
+
+*-h*, *--help*::
+	Display a help message and exit.
+
+*-V*, *--version*::
+	Output version information and exit.
+
+*--write-default-cfg*[**=**__PATH__]::
+	Write a configuration file with defaults, show its path and exit.
++
+The file will be appropriately commented.
++
+When no _PATH_ is specified, it will be created in the user's home directory,
+contrary to what you might expect from a server.
+
+Files
+-----
+*kike* follows the XDG Base Directory Specification.
+
+_~/.config/kike/kike.conf_::
+_/etc/xdg/kike/kike.conf_::
+	The daemon's configuration file.  Use the *--write-default-cfg* option
+	to create a new one for editing.
+
+Reporting bugs
+--------------
+Use https://git.janouch.name/p/uirc3 to report bugs, request features,
+or submit pull requests.
diff --git a/zyklonb.adoc b/zyklonb.adoc
new file mode 100644
index 0000000..d02368f
--- /dev/null
+++ b/zyklonb.adoc
@@ -0,0 +1,104 @@
+zyklonb(1)
+==========
+:doctype: manpage
+:manmanual: uirc3 Manual
+:mansource: uirc3 {release-version}
+
+Name
+----
+zyklonb - an experimental IRC bot
+
+Synopsis
+--------
+*zyklonb* [_OPTION_]...
+
+Description
+-----------
+*zyklonb* is a modular IRC bot with a programming language-agnostic plugin
+architecture based on co-processes.
+
+Options
+-------
+*-d*, *--debug*::
+	Print more information to help debug various issues.
+
+*-h*, *--help*::
+	Display a help message and exit.
+
+*-V*, *--version*::
+	Output version information and exit.
+
+*--write-default-cfg*[**=**__PATH__]::
+	Write a configuration file with defaults, show its path and exit.
++
+The file will be appropriately commented.
+
+Commands
+--------
+The bot accepts the following commands when they either appear quoted by the
+*prefix* string on a channel or unquoted as a private message sent directly
+to the bot, on the condition that the sending user matches the *admin*
+regular expression or that it is left unset:
+
+*quote* [_message_]::
+	Forwards the message to the IRC server as-is.
+*quit* [_reason_]::
+	Quits the IRC server, with an optional reason string.
+*status*::
+	Sends back a report about its state and all loaded plugins.
+*load* _plugin_[, _plugin_]...::
+	Tries to load the given plugins.
+*unload* _plugin_[, _plugin_]...::
+	Tries to unload the given plugins.
+*reload* _plugin_[, _plugin_]...::
+	The same as *unload* immediately followed by *load*.
+
+Plugins
+-------
+Plugins communicate with the bot over their standard input and output streams
+using the IRC protocol.  (Caveat: the standard C library doesn't automatically
+flush FILE streams for pipes on newlines.)  A special *ZYKLONB* command is
+introduced for RPC, with the following subcommands:
+
+*ZYKLONB get_config* _key_::
+	Request the value of the given configuration option.  If no such option
+	exists, the value will be empty.  The response will be delivered in
+	the following format:
++
+```
+ZYKLONB :value
+```
++
+This is particularly useful for retrieving the *prefix* string.
+
+*ZYKLONB print* _message_::
+	Make the bot print the _message_ on its standard output.
+
+*ZYKLONB register*::
+	Once a plugin issues this command, it will start receiving all of the bot's
+	incoming IRC traffic, which includes data from the initialization period.
+
+All other commands will be forwarded directly to the IRC server.
+
+Files
+-----
+*zyklonb* follows the XDG Base Directory Specification.
+
+_~/.config/zyklonb/zyklonb.conf_::
+	The bot's configuration file.  Use the *--write-default-cfg* option
+	to create a new one for editing.
+
+_~/.local/share/zyklonb/_::
+	The initial working directory for plugins, in which they may create private
+	databases or other files as needed.
+
+_~/.local/share/zyklonb/plugins/_::
+_/usr/local/share/zyklonb/plugins/_::
+_/usr/share/zyklonb/plugins/_::
+	Plugins are searched for in these directories, in order, unless
+	the *plugin_dir* configuration option overrides this.
+
+Reporting bugs
+--------------
+Use https://git.janouch.name/p/uirc3 to report bugs, request features,
+or submit pull requests.