--- /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)