Mercurial > irccd

comparison doc/src/irccd.md @ 607:bb9771fb5f44

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
606:4f5f306d13ac 607:bb9771fb5f44
1 % irccd
2 % David Demelier
3 % 2017-12-08
4
5 The `irccd` program is an IRC bot which connects to one or more severs and
6 dispatches events to plugins.
7
8 # Synopsis
9
10 $ irccd [options...]
11
12 # Options
13
14 The following options are available:
15
16 - `-c, --config file`: specify the configuration file,
17 - `-f, --foreground`: do not run as a daemon,
18 - `-v, --verbose`: be verbose,
19 - `--version`: show the version.
20
21 # Paths
22
23 Irccd uses different types of paths depending on the context.
24
25 - Configuration
26 - Plugins
27
28 Paths prefixed by (W) means they are only used on Windows, others prefixed by
29 (U) means they are used on Unix systems
30
31 # Configuration
32
33 The following directories are searched in the specified order for configuration
34 files. For example, the files `irccd.conf` and `irccdctl.conf` will be searched
35 there.
36
37 - \(W) `%APPDATA%/irccd/config`
38 - \(U) `${XDG_CONFIG_HOME}/irccd`
39 - \(U) `${HOME}/.config/irccd` (if `XDG_CONFIG_HOME` is not set)
40 - `installation-directory/etc`
41
42 Examples:
43
44 - `/home/john/.config/irccd/irccd.conf`
45 - `/usr/local/etc/irccd.conf`
46 - `C:/Program Files/irccd/etc/irccd.conf`
47 - `C:/Users/john/AppData/irccd/config`
48
49 # Plugins
50
51 These directories are searched in the following order to load plugins when they
52 are not specified by full paths.
53
54 - current working directory
55 - \(W) `%APPDATA%/irccd/share/plugins`
56 - \(U) `${XDG_DATA_HOME}/irccd/plugins`
57 - \(U) `${HOME}/.local/share/irccd/plugins` (if `XDG_DATA_HOME` is not set)
58 - \(W) `installation-directory/share/plugins`
59 - \(U) `installation-directory/share/irccd/plugins`
60
61 Examples:
62
63 - `/home/john/.local/share/irccd/plugins/ask.js`
64 - `/usr/local/share/irccd/plugins/ask.js`
65 - `C:/Users/john/AppDAta/irccd/share/plugins/ask.js`
66 - `C:/Program Files/irccd/share/plugins/ask.js`
67
68 # Templates and formatting
69
70 Plugins can be configured using a powerful template syntax, this allows editing
71 the plugin messages to override them.
72
73 The syntax is `?{}` where `?` is replaced by one of the token defined below.
74 Braces are mandatory and cannot be ommited. To write a literal template
75 construct, prepend the token twice.
76
77 ## Availables templates
78
79 The following templates are available:
80
81 - `%`, date and time (see [Time](#time)),
82 - `#{name}`, name will be substituted from the keywords
83 (see [Keywords](#keywords)),
84 - `${name}`, name will be substituted from the environment variable
85 (see [Environment variables](#environment-variables)),
86 - `@{attributes}`, the attributes will be substituted to IRC colors
87 (see [Attributes](#attributes)),
88
89 ## Time
90
91 When you can use patterns, the date and time may be used just like `strftime(3)`
92 so for the hours and minutes, you can use **%H:%M**.
93
94 ## Environment variables
95
96 If supported, you can use environment variables like **${HOME}**. Please note
97 that braces are mandatory.
98
99 ## Attributes
100
101 The attribute format is composed of three parts, foreground, background and
102 modifiers, each separated by a comma.
103
104 Note: attributes and colors are not supported by all IRC clients.
105
106 Warning: do not use colors and attributes outside IRC (e.g. for storing text in
107 files) because escape codes are only valid in IRC context.
108
109 ### Available colors
110
111 - white,
112 - black,
113 - blue,
114 - green,
115 - red,
116 - brown,
117 - purple,
118 - orange,
119 - yellow,
120 - lightgreen,
121 - cyan,
122 - lightcyan,
123 - lightblue,
124 - pink,
125 - grey,
126 - lightgrey.
127
128 ### Available attributes
129
130 - bold,
131 - italic,
132 - strike,
133 - reset,
134 - underline,
135 - underline2,
136 - reverse.
137
138 ## Keywords
139
140 Keywords are arbitrary names that are replaced depending on the context. They
141 are usually available to configure plugins.
142
143 ### Predefined keywords
144
145 Here's the list of keywords that a lot of plugins uses:
146
147 - **#{channel}**, the channel name,
148 - **#{command}**, the command to invoke the plugin, e.g. `!ask`,
149 - **#{message}**, a message (depending on context),
150 - **#{origin}**, the full user, e.g. `markand!~mkd@localhost`,
151 - **#{nickname}**, the short nickname,
152 - **#{plugin}**, the plugin name,
153 - **#{server}**, the current server name,
154 - **#{topic}**, the topic,
155 - **#{target}**, a target, e.g. a person who gets kicked.
156
157 Warning: these keywords can be overriden by plugins.
158
159 ## Examples
160
161 ### Valid constructs
162
163 - `#{target}, welcome`: if target is set to "irccd", becomes "irccd, welcome",
164 - `@{red}#{target}`: if target is specified, it is written in red.
165
166 ### Invalid or literals constructs
167
168 - `##{target}`: will output "#{target}",
169 - `##`: will output "##",
170 - `#target`: will output "#target",
171 - `#{target`: will throw an error.
172
173 ### Colors & attributes
174
175 - `@{red,blue}`: will write text red on blue background,
176 - `@{default,yellow}`: will write default color text on yellow background,
177 - `@{white,black,bold,underline}`: will write white text on black in both bold
178 and underline.
179
180 ### In the logger plugin
181
182 For instance, using the **logger** plugin, it's possible to customize the
183 pattern to use when someone joins a channel like that:
184
185 #{origin} joined #{channel}
186
187 The keyword **#{origin}** will be substituted to the nickname and **#{channel}**
188 to the channel name.
189
190 # See also
191
192 - irccd.conf(5)
193 - irccdctl(1)