Mercurial > irccd
changeset 368:d731ce3ae821
Docs: add new documentation about paths
author | David Demelier <markand@malikania.fr> |
---|---|
date | Tue, 06 Dec 2016 13:13:11 +0100 |
parents | b81c6fdec22e |
children | 5aca8eeebcf1 |
files | doc/html/CMakeLists.txt doc/html/index.md doc/html/irccd/configuring.md doc/html/irccd/index.md doc/html/irccd/paths.md |
diffstat | 5 files changed, 94 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/html/CMakeLists.txt Thu Dec 01 13:22:58 2016 +0100 +++ b/doc/html/CMakeLists.txt Tue Dec 06 13:13:11 2016 +0100 @@ -144,6 +144,7 @@ ${html_SOURCE_DIR}/dev/socket-protocol.md ${html_SOURCE_DIR}/irccd/configuring.md ${html_SOURCE_DIR}/irccd/index.md + ${html_SOURCE_DIR}/irccd/paths.md ${html_SOURCE_DIR}/irccdctl/configuring.md ${html_SOURCE_DIR}/irccdctl/index.md ${html_SOURCE_DIR}/irccdctl/usage.md
--- a/doc/html/index.md Thu Dec 01 13:22:58 2016 +0100 +++ b/doc/html/index.md Tue Dec 06 13:13:11 2016 +0100 @@ -16,6 +16,7 @@ Running irccd, configuration and command line options. + - [Paths](irccd/paths.html) - [Configure irccd](irccd/configuring.html) And about irccdctl.
--- a/doc/html/irccd/configuring.md Thu Dec 01 13:22:58 2016 +0100 +++ b/doc/html/irccd/configuring.md Tue Dec 06 13:13:11 2016 +0100 @@ -3,6 +3,11 @@ guide: yes --- +# Configuring irccd + +To configure irccd, create a `irccd.conf` file in one of the +[configuration directories][cfgdir]. + Options that have a default value are optional and can be omitted. # Identifiers @@ -314,3 +319,5 @@ ask = "" # This search for plugin ask myplugin = /path/to/myplugin.js # This use absolute path ```` + +[cfgdir]: @baseurl@/irccd/paths.html
--- a/doc/html/irccd/index.md Thu Dec 01 13:22:58 2016 +0100 +++ b/doc/html/irccd/index.md Tue Dec 06 13:13:11 2016 +0100 @@ -4,4 +4,5 @@ guide: yes --- + - [Paths](paths.html) - [Configure irccd](configuring.html)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/html/irccd/paths.md Tue Dec 06 13:13:11 2016 +0100 @@ -0,0 +1,84 @@ +--- +title: Paths +guide: yes +--- + +# Paths + +Irccd uses different types of paths depending on the context. + + - Configuration + - Data + - Plugins + +Paths prefixed by (W) means they are only used on Windows, others prefixed by +(U) means they are used on Unix. + +## 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` + +## Data + +The data directory is only used by plugins, it is dedicated to store important +files such as plugin assets, logs or anything that is meaningful for the user +or the plugin. + +<div class="alert alert-info" role="alert"> +**Note**: The plugins never try to create the directories, instead irccd +searches for the first available one and use it. If the directory does not exist +it is set by default to the **system** one. + +It is thus recommended to create a directory into your local home folder if you +run irccd as your user and not as a system daemon. +</div> + +The following directories as searched in order: + + - \(W) `%APPDATA%/irccd/share` + - \(U) `${XDG_DATA_HOME}/irccd` + - \(U) `${HOME}/.local/share/irccd` (if `XDG_DATA_HOME` is not set) + - \(W) `installation-directory/share` + - \(U) `installation-directory/share/irccd` + +For plugins, the path is appended with `plugin/<plugin_name>` (e.g. plugin/ask). + +Examples: + + - `/home/john/.local/share/irccd/plugin/ask` + - `/usr/local/share/irccd/plugin/ask` + - `C:/Users/john/AppData/irccd/share/plugin/ask` + - `C:/Program Files/irccd/share/plugin/ask` + +## 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`