Add real manual pages

To some extent they duplicate the README but from a different angle.
This commit is contained in:
Přemysl Eric Janouch 2020-10-25 15:30:06 +01:00
parent cbe4009308
commit 53cc52e320
Signed by: p
GPG Key ID: A0420B94F92B9493
5 changed files with 294 additions and 8 deletions

View File

@ -191,19 +191,21 @@ install (DIRECTORY plugins/zyklonb/
install (DIRECTORY plugins/degesch/ install (DIRECTORY plugins/degesch/
DESTINATION ${CMAKE_INSTALL_DATADIR}/degesch/plugins) DESTINATION ${CMAKE_INSTALL_DATADIR}/degesch/plugins)
# Generate documentation from program help # Generate documentation from text markup
find_program (HELP2MAN_EXECUTABLE help2man) find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor)
if (NOT HELP2MAN_EXECUTABLE) if (NOT ASCIIDOCTOR_EXECUTABLE)
message (FATAL_ERROR "help2man not found") message (FATAL_ERROR "asciidoctor not found")
endif () endif ()
foreach (page zyklonb degesch kike) foreach (page zyklonb degesch kike)
set (page_output "${PROJECT_BINARY_DIR}/${page}.1") set (page_output "${PROJECT_BINARY_DIR}/${page}.1")
list (APPEND project_MAN_PAGES "${page_output}") list (APPEND project_MAN_PAGES "${page_output}")
add_custom_command (OUTPUT ${page_output} add_custom_command (OUTPUT ${page_output}
COMMAND ${HELP2MAN_EXECUTABLE} -N COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
"${PROJECT_BINARY_DIR}/${page}" -o ${page_output} -a release-version=${project_version}
DEPENDS ${page} "${PROJECT_SOURCE_DIR}/${page}.adoc"
-o "${page_output}"
DEPENDS ${page}.adoc
COMMENT "Generating man page for ${page}" VERBATIM) COMMENT "Generating man page for ${page}" VERBATIM)
endforeach () endforeach ()

View File

@ -76,7 +76,7 @@ a package with the latest development version from Archlinux's AUR.
Building Building
-------- --------
Build dependencies: CMake, pkg-config, help2man, awk, sh, liberty (included) + Build dependencies: CMake, pkg-config, asciidoctor, awk, liberty (included) +
Runtime dependencies: openssl + Runtime dependencies: openssl +
Additionally for degesch: curses, libffi, lua >= 5.3 (optional), Additionally for degesch: curses, libffi, lua >= 5.3 (optional),
readline >= 6.0 or libedit >= 2013-07-12 readline >= 6.0 or libedit >= 2013-07-12

127
degesch.adoc Normal file
View File

@ -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)

53
kike.adoc Normal file
View File

@ -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.

104
zyklonb.adoc Normal file
View File

@ -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.