Mercurial > irccd
comparison 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 |
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) |