Mercurial > irccd
diff man/irccd.1 @ 845:00a4720c4874
doc: rewrite documentation in manual pages, closes #1674
Get rid of markdown documentation and the custom generator tools, instead use
raw manual pages.
author | David Demelier <markand@malikania.fr> |
---|---|
date | Mon, 08 Jul 2019 16:15:57 +0200 |
parents | |
children | 0028704ab284 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd.1 Mon Jul 08 16:15:57 2019 +0200 @@ -0,0 +1,233 @@ +.\" +.\" Copyright (c) 2013-2019 David Demelier <markand@malikania.fr> +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt IRCCD 1 +.Os +.\" NAME +.Sh NAME +.Nm irccd +.Nd IRC Client Daemon +.\" SYNOPSIS +.Sh SYNOPSIS +.Nm irccd +.Op Fl c Ar file +.Op Fl v +.Nm irccd +.Ar version +.\" DESCRIPTION +.Sh DESCRIPTION +The +.Nm +program is an IRC bot which connects to one or more severs and +dispatches events to plugins. +.Pp +The following options are available: +.Bl -tag -width indent-xxx +.It Fl c Ar file +specify the configuration file. +.It Fl v +be verbose. +.El +.\" PLUGINS +.Sh PLUGINS +The +.Nm +program can runs plugins once IRC events are received. For example, if someone +sends you a private message plugins will be invoked with that event. Both native +plugins written in C++ and Javascript are supported (if enabled at compile +time). +.Pp +The following IRC events are supported: +.Bl -tag -width 12n +.\" onCommand +.It onCommand +This is a special event that does not exist in IRC context. It calls the plugin +special invocation command using +.Ar "!name arguments..." +syntax. The exclamation mark is configured by default to be the command +character prefix, then if the adjacent name is known to be a loaded plugin it is +invoked with the additional arguments. +.Pp +Example: to call the +.Nm hangman +plugin, one may use !hangman to start a game. +.Pp +See also +.Xr irccd.conf 5 +on how to change the command character prefix under a +.Va [server] +section. +.\" onConnect +.It onConnect +When a server successfully connects to an IRC server. +.\" onDisconnect +.It onDisconnect +When a server disconnected from an IRC server both in case of failures or +explicit user disconnection. +.\" onInvite +.It onInvite +Event called when the bot itself has been invited to a channel. +.\" onJoin +.It onJoin +When someone joins a channel. +.\" onKick +.It onKick +When someone has been kicked from a channel, irccd may be included. +.\" onLoad +.It onLoad +This is a special event that does not exist in IRC context. It is invoked when +the plugin is initialized. +.\" onMessage +.It onMessage +Upon private message. +.\" onMe +.It onMe +On action emote, also most known as +.Ar /me +command. +.\" onMode +.It onMode +When a user or channel mode change. +.\" onNames +.It onNames +When a list of nicknames has been received. +.\" onNick +.It onNick +On nick change, irccd may be included. +.\" onNotice +.It onNotice +On private notice. +.\" onPart +.It onPart +When someone leaves a channel. +.\" onReload +.It onReload +This is a special event that does not exist in IRC context. It is invoked when +the user asks to reload a plugin. +.\" onTopic +.It onTopic +When a channel topic has been changed. +.\" onUnload +.It onUnload +This is a special event that does not exist in IRC context. It is invoked when +the user asks to unload a plugin and before exiting. +.\" onWhois +.It onWhois +When a whois information has been received. +.El +.Pp +The following plugins are provided with irccd: +.Pp +.Bl -bullet -compact +.It +ask +.It +auth +.It +hangman +.It +history +.It +joke +.It +links +.It +logger +.It +plugin +.It +roulette +.It +tictactoe +.El +.Pp +See additional documentation in their own manual page in the form +.Xr irccd-plugin-name 7 +where name is the actual plugin name. +.\" TRANSPORTS +.Sh TRANSPORTS +The daemon can be controlled at runtime using the dedicated +.Nm irccdctl +tool or using sockets. +.Pp +Both TCP/IP and UNIX sockets are supported and SSL layer may be enabled over it +for a secure connection. If authentication is desired, it can be enabled too. +.Pp +See also the +.Va [transport] +section in the +.Xr irccd.conf 5 +manual page. +.\" RULES +.Sh RULES +.Nm +supports a feature called rules which allows you to define a fine-grained set of +rules allowed for specific plugins. For instance, you may want to disable some +IRC events for some plugins depending on your set of parameters. This is useful +for plugins that generates huge traffic. +.Pp +Rule events are matched using the same name as plugin events described in the +section above. For example, to disable a private message event you must use the +.Ar onCommand +value. +.Pp +See also the +.Va [rule] +section in the +.Xr irccd.conf 5 +manual page. +.\" DIRECTORIES +.Sh DIRECTORIES +.Nm +uses different types of paths depending on the context. +.Pp +Paths prefixed by (W) means they are only used on Windows, others prefixed by +(U) means they are used on UNIX systems +.Pp +.Ss Configuration +The following directories are searched in the specified order for configuration +files. For example, the files +.Pa irccd.conf +and +.Pa irccdctl.conf +will be searched there. +.Bl -bullet +.It +(W) %APPDATA%/irccd/config +.It +(U) ${XDG_CONFIG_HOME}/irccd +.It +(U) ${HOME}/.config/irccd (if XDG_CONFIG_HOME is not set) +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 7 , +.Xr irccd-templates 7 , +.Xr irccd-ipc 7 , +.Xr irccd-plugin-ask 7 , +.Xr irccd-plugin-auth 7 , +.Xr irccd-plugin-hangman 7 , +.Xr irccd-plugin-history 7 , +.Xr irccd-plugin-joke 7 , +.Xr irccd-plugin-links 7 , +.Xr irccd-plugin-logger 7 , +.Xr irccd-plugin-plugin 7 , +.Xr irccd-plugin-roulette 7 , +.Xr irccd-plugin-tictactoe 7 , +.Xr irccd-test 1 , +.Xr irccd.conf 5 , +.Xr irccdctl 1 , +.Xr irccdctl.conf 5