Mercurial > irccd
diff doc/src/irccd.md @ 607:bb9771fb5f44
Docs: rework documentation
- Change directories,
- Remove handwritten manual pages.
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 08 Dec 2017 20:11:22 +0100 |
parents | |
children | 168ea30142d9 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/src/irccd.md Fri Dec 08 20:11:22 2017 +0100 @@ -0,0 +1,193 @@ +% irccd +% David Demelier +% 2017-12-08 + +The `irccd` program is an IRC bot which connects to one or more severs and +dispatches events to plugins. + +# Synopsis + + $ irccd [options...] + +# Options + +The following options are available: + + - `-c, --config file`: specify the configuration file, + - `-f, --foreground`: do not run as a daemon, + - `-v, --verbose`: be verbose, + - `--version`: show the version. + +# Paths + +Irccd uses different types of paths depending on the context. + + - Configuration + - Plugins + +Paths prefixed by (W) means they are only used on Windows, others prefixed by +(U) means they are used on Unix systems + +# Configuration + +The following directories are searched in the specified order for configuration +files. For example, the files `irccd.conf` and `irccdctl.conf` will be searched +there. + + - \(W) `%APPDATA%/irccd/config` + - \(U) `${XDG_CONFIG_HOME}/irccd` + - \(U) `${HOME}/.config/irccd` (if `XDG_CONFIG_HOME` is not set) + - `installation-directory/etc` + +Examples: + + - `/home/john/.config/irccd/irccd.conf` + - `/usr/local/etc/irccd.conf` + - `C:/Program Files/irccd/etc/irccd.conf` + - `C:/Users/john/AppData/irccd/config` + +# Plugins + +These directories are searched in the following order to load plugins when they +are not specified by full paths. + + - current working directory + - \(W) `%APPDATA%/irccd/share/plugins` + - \(U) `${XDG_DATA_HOME}/irccd/plugins` + - \(U) `${HOME}/.local/share/irccd/plugins` (if `XDG_DATA_HOME` is not set) + - \(W) `installation-directory/share/plugins` + - \(U) `installation-directory/share/irccd/plugins` + +Examples: + + - `/home/john/.local/share/irccd/plugins/ask.js` + - `/usr/local/share/irccd/plugins/ask.js` + - `C:/Users/john/AppDAta/irccd/share/plugins/ask.js` + - `C:/Program Files/irccd/share/plugins/ask.js` + +# Templates and formatting + +Plugins can be configured using a powerful template syntax, this allows editing +the plugin messages to override them. + +The syntax is `?{}` where `?` is replaced by one of the token defined below. +Braces are mandatory and cannot be ommited. To write a literal template +construct, prepend the token twice. + +## Availables templates + +The following templates are available: + + - `%`, date and time (see [Time](#time)), + - `#{name}`, name will be substituted from the keywords + (see [Keywords](#keywords)), + - `${name}`, name will be substituted from the environment variable + (see [Environment variables](#environment-variables)), + - `@{attributes}`, the attributes will be substituted to IRC colors + (see [Attributes](#attributes)), + +## Time + +When you can use patterns, the date and time may be used just like `strftime(3)` +so for the hours and minutes, you can use **%H:%M**. + +## Environment variables + +If supported, you can use environment variables like **${HOME}**. Please note +that braces are mandatory. + +## Attributes + +The attribute format is composed of three parts, foreground, background and +modifiers, each separated by a comma. + +Note: attributes and colors are not supported by all IRC clients. + +Warning: do not use colors and attributes outside IRC (e.g. for storing text in + files) because escape codes are only valid in IRC context. + +### Available colors + + - white, + - black, + - blue, + - green, + - red, + - brown, + - purple, + - orange, + - yellow, + - lightgreen, + - cyan, + - lightcyan, + - lightblue, + - pink, + - grey, + - lightgrey. + +### Available attributes + + - bold, + - italic, + - strike, + - reset, + - underline, + - underline2, + - reverse. + +## Keywords + +Keywords are arbitrary names that are replaced depending on the context. They +are usually available to configure plugins. + +### Predefined keywords + +Here's the list of keywords that a lot of plugins uses: + + - **#{channel}**, the channel name, + - **#{command}**, the command to invoke the plugin, e.g. `!ask`, + - **#{message}**, a message (depending on context), + - **#{origin}**, the full user, e.g. `markand!~mkd@localhost`, + - **#{nickname}**, the short nickname, + - **#{plugin}**, the plugin name, + - **#{server}**, the current server name, + - **#{topic}**, the topic, + - **#{target}**, a target, e.g. a person who gets kicked. + +Warning: these keywords can be overriden by plugins. + +## Examples + +### Valid constructs + + - `#{target}, welcome`: if target is set to "irccd", becomes "irccd, welcome", + - `@{red}#{target}`: if target is specified, it is written in red. + +### Invalid or literals constructs + + - `##{target}`: will output "#{target}", + - `##`: will output "##", + - `#target`: will output "#target", + - `#{target`: will throw an error. + +### Colors & attributes + + - `@{red,blue}`: will write text red on blue background, + - `@{default,yellow}`: will write default color text on yellow background, + - `@{white,black,bold,underline}`: will write white text on black in both bold + and underline. + +### In the logger plugin + +For instance, using the **logger** plugin, it's possible to customize the +pattern to use when someone joins a channel like that: + + #{origin} joined #{channel} + +The keyword **#{origin}** will be substituted to the nickname and **#{channel}** +to the channel name. + +# See also + + - irccd.conf(5) + - irccdctl(1)