Mercurial > irccd
view 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 source
% 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)