diff options
| -rw-r--r-- | CMakeLists.txt | 16 | ||||
| -rw-r--r-- | README.adoc | 2 | ||||
| -rw-r--r-- | degesch.adoc | 127 | ||||
| -rw-r--r-- | kike.adoc | 53 | ||||
| -rw-r--r-- | zyklonb.adoc | 104 |
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. |