Mercurial > irccd
changeset 996:2a6d753f79f6
man: add back
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 11 Feb 2021 22:13:01 +0100 |
parents | 0d71bfa6c97a |
children | 0db97f67f31f |
files | CMakeLists.txt man/CMakeLists.txt man/irccd-api-chrono.3 man/irccd-api-file.3 man/irccd-api-server.3 man/irccd-api-system.3 man/irccd.conf.5 man/irccdctl.conf.5 |
diffstat | 8 files changed, 343 insertions(+), 506 deletions(-) [+] |
line wrap: on
line diff
--- a/CMakeLists.txt Thu Feb 11 17:39:22 2021 +0100 +++ b/CMakeLists.txt Thu Feb 11 22:13:01 2021 +0100 @@ -58,6 +58,7 @@ add_subdirectory(irccd) add_subdirectory(irccdctl) add_subdirectory(plugins) +add_subdirectory(man) if (IRCCD_WITH_TESTS) enable_testing()
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/CMakeLists.txt Thu Feb 11 22:13:01 2021 +0100 @@ -0,0 +1,67 @@ +# +# CMakeLists.txt -- CMake build for irccd +# +# Copyright (c) 2013-2021 David Demelier <markand@malikania.fr> +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +# + +project(man) + +set( + MAN1 + ${man_SOURCE_DIR}/irccd.1 + ${man_SOURCE_DIR}/irccdctl.1 +) + +set( + MAN3 + ${man_SOURCE_DIR}/irccd-api-chrono.3 + ${man_SOURCE_DIR}/irccd-api-directory.3 + ${man_SOURCE_DIR}/irccd-api-file.3 + ${man_SOURCE_DIR}/irccd-api-logger.3 + ${man_SOURCE_DIR}/irccd-api-plugin.3 + ${man_SOURCE_DIR}/irccd-api-server.3 + ${man_SOURCE_DIR}/irccd-api-system.3 + ${man_SOURCE_DIR}/irccd-api-timer.3 + ${man_SOURCE_DIR}/irccd-api-unicode.3 + ${man_SOURCE_DIR}/irccd-api-util.3 + ${man_SOURCE_DIR}/irccd-api.3 +) + +set( + MAN5 + ${man_SOURCE_DIR}/irccd.conf.5 +) + +set( + MAN7 + ${man_SOURCE_DIR}/irccd-ipc.7 + ${man_SOURCE_DIR}/irccd-templates.7 +) + +foreach (m ${MAN1}) + install(FILES ${m} DESTINATION ${CMAKE_INSTALL_MANDIR}/man1) +endforeach () + +foreach (m ${MAN3}) + install(FILES ${m} DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) +endforeach () + +foreach (m ${MAN5}) + install(FILES ${m} DESTINATION ${CMAKE_INSTALL_MANDIR}/man5) +endforeach () + +foreach (m ${MAN7}) + install(FILES ${m} DESTINATION ${CMAKE_INSTALL_MANDIR}/man7) +endforeach ()
--- a/man/irccd-api-chrono.3 Thu Feb 11 17:39:22 2021 +0100 +++ b/man/irccd-api-chrono.3 Thu Feb 11 22:13:01 2021 +0100 @@ -23,10 +23,7 @@ .\" SYNOPSIS .Sh SYNOPSIS .Fn Irccd.Chrono -.Fn Irccd.Chrono.prototype.elapsed -.Fn Irccd.Chrono.prototype.pause -.Fn Irccd.Chrono.prototype.resume -.Fn Irccd.Chrono.prototype.start +.Fn Irccd.Chrono.prototype.reset .\" DESCRIPTION .Sh DESCRIPTION This module keeps track of elapsed time. @@ -37,26 +34,16 @@ .Fn Irccd.Chrono constructor function creates a chrono object at the current time. .Pp -.\" Irccd.Chrono.prototype.elapsed -The -.Fn Irccd.Chrono.prototype.elapsed -method returns the number of milliseconds elapsed since last the object was -started or constructed. +When constructed successfully, the object has the following properties: .Pp -.\" Irccd.Chrono.prototype.pause +.Bl -tag -width 18n -offset indent -compact +.It Va elapsed No (int) +Return the number of milliseconds since creation or last call to +.El +.Pp +.\" Irccd.Chrono.prototype.reset The -.Fn Irccd.Chrono.prototype.pause -method pauses the timer, without resetting the current elapsed time stored. -.Pp -.\" Irccd.Chrono.prototype.resume -The -.Fn Irccd.Chrono.prototype.resume -method resume accumulating additional time. Has no effect if the timer is -already running. -.Pp -.\" Irccd.Chrono.prototype.start -The -.Fn Irccd.Chrono.prototype.start +.Fn Irccd.Chrono.prototype.reset method starts or restarts accumulating time. .\" SEE ALSO .Sh SEE ALSO
--- a/man/irccd-api-file.3 Thu Feb 11 17:39:22 2021 +0100 +++ b/man/irccd-api-file.3 Thu Feb 11 22:13:01 2021 +0100 @@ -178,10 +178,7 @@ The .Fn Irccd.File.prototype.readline method reads the next line available and returns it. If EOF was reached, -returns undefined. Warning: this method is slow and its usage is discouraged on -large files. Consider using -.Fn Irccd.File.prototype.lines -function if you want to read a file line per line. +returns undefined. .Pp .\" Irccd.File.prototype.remove The
--- a/man/irccd-api-server.3 Thu Feb 11 17:39:22 2021 +0100 +++ b/man/irccd-api-server.3 Thu Feb 11 22:13:01 2021 +0100 @@ -82,21 +82,21 @@ .Fa parameters object which may have the following properties: .Pp -.Bl -tag -width 20n -compact -offset Ds +.Bl -tag -compact -width "hostname (string)" .It Fa name No (string) The unique identifier name. .It Fa hostname No (string) The host or IP address. -.It Fa ipv4 No (bool) -Enable ipv4 (Optional, default: true). -.It Fa ipv6 No (bool) -Enable ipv6, (Optional, default: true). .It Fa port No (int) The port number, (Optional, default: 6667). .It Fa password No (string) The password, (Optional, default: undefined). .It Fa channels No (array) -Array of channels (Optional, default: empty). +Array of channels as object of two properties: +.Fa name +and +.Fa password (optional) +as channel name and password respectively. (Optional, default: empty). .It Fa ssl No (bool) True to use ssl (Optional, default: false). .It Fa nickname No (string) @@ -105,7 +105,7 @@ User name, (Optional, default: irccd). .It Fa realname No (string) Real name, (Optional, default: IRC Client Daemon). -.It Fa commandChar No (string) +.It Fa prefix No (string) Plugin prefix character, (Optional, default: "!"). .El .Pp @@ -115,7 +115,7 @@ method returns the server information. The object have the following properties: .Pp -.Bl -tag -width 20n -compact -offset Ds +.Bl -tag -compact -width "hostname (string)" .It Va name No (string) The server unique name. .It Va hostname No (string) @@ -125,7 +125,21 @@ .It Va ssl No (bool) True if using ssl. .It Va channels No (array) -An array of all channels. +An array of all channels. Each channel in the returned array contain the +following properties: +.Bl -tag -width xxx +.It Va name No (string) +The channel name. +.It Va joined No (bool) +True if the daemon is actually present on this channel. +.It Va users No (array) +An array of users that consists of objects with three properties: +.Va nickname , mode +and +.Va symbol +as their nickname, the channel mode and the symbol representing this mode. +.El +.Pp .It Va realname No (string) The current real name. .It Va username No (string)
--- a/man/irccd-api-system.3 Thu Feb 11 17:39:22 2021 +0100 +++ b/man/irccd-api-system.3 Thu Feb 11 22:13:01 2021 +0100 @@ -28,7 +28,6 @@ .Fn Irccd.System.name .Fn Irccd.System.popen "cmd, mode" .Fn Irccd.System.sleep "seconds" -.Fn Irccd.System.ticks .Fn Irccd.System.uptime .Fn Irccd.System.usleep "microseconds" .Fn Irccd.System.version @@ -112,11 +111,6 @@ method suspends the execution thread for the given amount of .Fa seconds . .Pp -.\" Irccd.System.ticks -The -.Fn Irccd.System.ticks -method returns the time spent since irccd startup in milliseconds. -.Pp .\" Irccd.System.uptime The .Fn Irccd.System.uptime
--- a/man/irccd.conf.5 Thu Feb 11 17:39:22 2021 +0100 +++ b/man/irccd.conf.5 Thu Feb 11 22:13:01 2021 +0100 @@ -22,349 +22,300 @@ .Nd irccd configuration file .\" DESCRIPTION .Sh DESCRIPTION -Both -.Nm irccd -and -.Nm irccdctl -use configuration file in a extended INI format. This section will briefly -explain the additional extensions to the INI format. -.Pp -The file syntax has following rules: -.Bl -enum -.It -Each option is stored in a section, -.It -Some sections may be redefined multiple times, -.It -Empty option must have quotes (e.g. option = ""). -.El -.Ss The @include and @tryinclude statements -Irccd adds an extension to this format by adding an -.\" @include and @tryinclude -.Ar @include keyword -which let you splitting your configuration file. -.Pp -Note: this @include statement must be at the beginning of the file and must be -surrounded by quotes if the file name has spaces. -.Pp -You can use both relative or absolute paths. If relative paths are used, they -are relative to the current file being parsed. +The +.Nm +uses a custom configuration file to setup the IRC daemon. +.\" SYNTAX +.Sh SYNTAX +The file consists of several directives that are evaluated in order of +appearance. It is advised to follow the same directive order as described in +this document. .Pp -The alternative -.Ar @tryinclude -keyword is similar but does not fails if the requested file is not found. +The below sections describe the supported syntax. +.\" Comments +.Ss Comments +Comments start when a # is found and continue until the next line. +.\" Strings +.Ss Strings +String are either written in pure ASCII strings or enclosed between double +quotes. Because some reserved tokens may collide with your values, it is +recommended to use double quoted strings in user values (such as identifiers, +channels names and such). Also, double quotes are required when string contain +spaces. .Pp -Example of includes: -.Bd -literal -offset Ds -@include "rules.conf" -@include "servers.conf" - -[mysection] -myoption = "1" +Example: +.Bd -literal -offset indent +String +"This is a double quoted string" .Ed -.\" lists -.Ss The list construct -When requested, an option can have multiples values in a list. The syntax uses -parentheses and values are separated by commas. -.Pp -If the list have only one value, you can just use a simple string. -.Pp -Example of lists: -.Bd -literal -offset Ds -[rule] -servers = ( "server1", "server2" ) - -[rule] -servers = "only-one-server" -.Ed -.Pp -Note: spaces are completely optional. -.\" identifiers +.\" Identifiers .Ss Identifiers Some sections require an identifier (specified as id) as parameter. They must be -unique, not empty and can only contain characters, numbers, '-' and '_'. +unique, not empty and can only contain characters, numbers, +.Dq - +and +.Dq _ . .Pp Example: both .Ar abc and .Ar server-tz2 are valid. +.\" Blocks +.Ss Blocks +For configuration sections that are more complex, block using braces are +required and each directive between the enclosing block require a trailing +semicolon. +.Pp +Example: +.Bd -literal -offset indent +block { + option; + key and value; +} +.Ed +.\" Lists +.Ss Lists +Lists are separated by a comma. +.Pp +Example: +.Bd -literal -offset indent +one, two, three +.Ed .\" CONFIGURATION SECTIONS .Sh CONFIGURATION SECTIONS -Configuration are always stored in dedicated section in the form -.Ar [name] -where name is one of the section defined below and are case-sensitive. -.\" [logs] +The following sections describe what is allowed in the configuration file. +.\" logs .Ss logs This section can let you configure how irccd should log the messages. -.Pp -Available options: -.Bl -tag -width 20n -.It Va verbose No (bool) -Be verbose (Optional, default: false). -.It Va type No (string) -Which kind of logging, valid values are -.Dq console , -.Dq file -or -.Dq syslog -(Optional, default: console). -.Pp -Note: syslog is not available on all platforms. +.Bl -tag +.It Ar logs [verbose|quiet] to console +Use the standard output and error to log content. This the default. +.It Ar logs [verbose|quiet] to syslog +Use the +.Xr syslog 3 +daemon to log information. +.It Ar logs [verbose|quiet] to file path +Use +.Pa path +to logs every entries. .El .Pp -The following options are available for the -.Ar file -type: -.Bl -tag -width 20n -.It Va path-logs No (string) -Path to the normal messages. -.It Va path-errors No (string) -Path to the error messages. -.El -.\" [templates] -.Ss templates -The templates section let you change the irccd's output. It uses the templates -system (see -.Xr irccd-templates 7 -for more information about templates) +The optional self explained +.Op verbose|quiet +argument controls either if verbose logging should be enabled or not. Only +informative messages are affected by this setting. Warnings and debugging +messages are stored independently from this setting. +.\" transport +.Ss transport +Enable transport to interract with the +.Nm irccdctl +utility or any networking program that can communicate through a UNIX domain +socket. .Pp -Only one keyword is defined, message which contains the message that irccd -wants to output. -.Pp -Note: colors and attributes are not supported on Windows. +.Ar transport to path .Pp -Available options: -.Bl -tag -width 18n -.It Va debug No (string) -Template to use to format debug messages (Optional, default: none). -.It Va info No (string) -Template to use to format information messages (Optional, default: none). -.It Va warning No (string) -Template to use to format warnings (Optional, default: none). -.El -.\" [server] +Enable transport on +.Pa path . +.\" server .Ss server This section is used to connect to one or more server. Create a new server -section for each IRC server you want to connect to. +section block for each IRC server you want to connect to. .Pp -Available options: -.Bl -tag -width 26n -.It Va name No (identifier) -The unique id. -.It Va hostname No (string) -The server address or IP. -.It Va port No (int) -The server port (Optional, default: 6667). -.It Va password No (string) -An optional server password (Optional, default: none). -.It Va join-invite No (bool) -Automatically join channels upon invitation (Optional, default: false). -.It Va channels No (list) -List of channels to auto join (Optional, default: empty). +.Ar server id { options } .Pp -Note: if a channel requires a password, add it after a colon (e.g. -.Dq #channel:password ) . -.It Va command-char No (string) -The prefix for invoking special commands (Optional, default: !). -.It Va ssl No (bool) -Enable or disable SSL (Optional, default: false). -.It Va auto-reconnect No (bool) -Enable reconnection after failure (Optional, default: true). -.It Va auto-reconnect-delay No (int) -Number of seconds to wait before retrying (Optional, default: 30). -.It Va ping-timeout No (int) -Number of seconds before ping timeout (Optional, default: 1800). -.It Va nickname No (string) -The nickname (Optional, default: irccd). -.It Va realname No (string) -The realname (Optional, default: IRC Client Daemon). -.It Va username No (string) -The username name (Optional, default: irccd). -.It Va ctcp-version No (string) -What version to respond to CTCP VERSION (Optional, default: IRC Client Daemon). -.El -.\" [paths] -.Ss paths -The paths section defines common paths used as defaults for all plugins. -.Pp -Any option in this section can be defined altough the following are used as -common convention used in all plugins: -.Pp -Available options: -.Bl -tag -width 16n -.It Va cache No (string) -Path for data files written by the plugin. -.It Va data No (string) -Path for data files provided by the user. -.It Va config No (string) -Path for additional configuration from the user. -.El -.Pp -For each of these paths, -.Dq plugin/name -is appended with the appropriate plugin name when used. -.Pp -The section is redefinable per plugin basis using the -.Va [paths.<plugin>] -syntax. -.\" [plugins] -.Ss plugins -This section is used to load plugins. +The following directives are allowed in the +.Em options +block: +.Bl -tag -width "hostname value" +.It Ar hostname value +Connect to the +.Ar value +hostname. This can be either a DNS name or a IP address. +.It Ar port value +Use +.Ar value +number as IP port to connect to. +.It Ar ident nick user realname +Specify the IRC identity to use by using the three arguments +.Ar nick , user +and +.Ar realname +as nickname, user name and your real name respectively. .Pp -Just add any key you like to load a plugin. If the value is not specified, the -plugin is searched through the standard directories, otherwise, provide the full -path (including the .js extension). -.Pp -Warning: remember to add an empty string for searching plugins. -.\" [hooks] -.Ss hooks -This sections stores every hooks in key-value pairs. The option key denotes the -hook id and the value must be a path to the actual hook file. -.\" [transport] -.Ss transport -This section defines transports that are used to communicate through clients -connected to irccd and to perform requests to irccd. -.Pp -With transports, you may ask irccd to send a message, a notice or even to kick -someone from a channel. Irccd will also notify all clients connected to this -transport on IRC events. -.Pp -There are two types of transport availables: -.Bl -bullet -.It -Internet sockets, IPv4 and IPv6, -.It -Unix sockets, based on files (not available on Windows). +Note: this is not a list of strings but three arguments separated by a space. If +you want to use a real name with spaces, don't forget the double quotes. +.It Ar ssl +Enable SSL. Only available if built with OpenSSL support. +.It Ar channels list +List of channels to join automatically when the server is connected +successfully. This is a list of strings where each element is the channel name +to join prepended by a optional +.Ar password@ +if required. You must use double quotes if the channel starts with a hash (#) +otherwise it would be detected as a comment. +.It Ar options list +Use specific server features. This is a list of string which can be one of +following: +.Bl -tag -width "AUTO-RECONNECT" +.It Ar AUTO-RECONNECT +Reconnect automatically to a server upon disconnection. +.It Ar AUTO-REJOIN +Automatically rejoin a channel if the bot was kicked from. +.It Ar JOIN-INVITE +Automatically join a channel upon invitation. .El -.Pp -If SSL support was built in, both internet and unix sockets can be set to use -encrypted connections. -.Pp -Available options: -.Bl -tag -width 18n -.It Va type No (string) -Type of transport -.Dq ip -or -.Dq unix . -.It Va password No (string) -An authentication password (Optional, default: none). -.It Va ssl No (bool) -Enable SSL (Optional, default: false), -.It Va key No (string) -Path to private key file (Required if ssl is true) -.It Va certificate No (string) -Path to certificate (Required if ssl is true) +.It Ar prefix value +Use +.Ar value +as command prefix for plugins (Optional, default: +.Dq \&! ) . .El -.Pp -The following options are available for the -.Ar ip -type: -.Bl -tag -width 18n -.It Va port No (int) -Port number. -.It Va address No (string) -Address to bind or -.Dq * -for any (Optional, default: -.Dq * ) . -.It Va ipv4 No (bool) -Bind on IPv4 (Optional, default true). -.It Va ipv6 No (bool) -Bind on IPv6 (Optional, default true). -.El -.Pp -The following options are available for the -.Ar unix -type: -.Bl -tag -width 18n -.It Va path No (string) -The file path to the socket. -.El -.\" [rule] +.\" rule .Ss rule The rule section is one of the most powerful within irccd configuration. It lets -you enable or disable plugins and IRC events for specific criterias. For +you enable or disable plugins and IRC events for specific criteria. For instance, you may want to disable a plugin only for a specific channel on a specific server. And because rules are evaluated in the order they are defined, you can override rules. .Pp -Available options: -.Bl -tag -width 15n -.It Va servers No (list) -A list of servers that will match the rule (Optional, default: empty). -.It Va channels No (list) -A list of channel (Optional, default: empty). -.It Va origins No (list) -A list of nicknames to check (Optional, default: empty). -.It Va plugins No (list) -Which plugins (Optional, default: empty), -.It Va events No (list) -Which events like onCommand, onMessage (Optional, default: empty). -.It Va action No (string) -Set to -.Dq accept +When you don't specify any value into the corresponding criteria the rule is +considered as matched. +.Pp +.Ar rule accept|drop { criteria } +.Pp +Create a rule that either +.Ar accept or -.Dq drop . +.Ar drop +the current event. +.Pp +The following directives are allowed in the +.Em options +block: +.Bl -tag -width "channels list" +.It Ar servers list +List of servers to match by their ids. +.It Ar channels list +List of channel to match. This can be used to match user nicknames as well. +.It Ar origins list +List of originators to match. +.It Ar events list +List of events to match (in the form onCommand, onMessage, etc). See the +.Xr irccd 1 +manual page for the allowed names here. +.It Ar plugins list +List of plugins to match by their ids. .El .Pp Warning: don't make sensitive rules on origins option, irccd does not have any kind of nickname authentication. Thus, it may be very easy for someone to use a temporary nickname. +.\" hooks +.Ss hooks +This section loads hooks. The configuration does not test if the file is +actually executable nor present on the filesystem and will be tried as long as +the daemon is running. +.Pp +.Ar hook id to path +.Pp +Load the hook with name +.Ar id +from the given +.Pa path . +.\" plugins +.Ss plugins +This section is used to load plugins. +.Pp +To load plugin with default values, you can just use the declaration without +block of options. Otherwise, use a block to add additional options, +.Pp +.Ar plugin id { options } +.Pp +The following directives are allowed in the +.Em options +block: +.Bl -tag -width "hostname value" +.It Ar location path +Specify an absolute +.Pa path +to the plugin. +.It Ar config { key value } +Specify a list of options to the plugin as key-value pair. Each entry consist of +two arguments, the option name and its value both as strings. See +.Xr EXAMPLES +for usage. +.It Ar template { key value } +Same as +.Ar config +but for templates. See +.Xr irccd-templates 7 +for more details about this section. +.It Ar paths { key value } +Same as +.Ar config +but for additional paths. Individual plugins may accept special paths but the +following are reserved by irccd and always set when loading the plugin unless +explicitly overriden in this section: +.Bl -tag +.It Ar cache +Directory for temporary files. +.It Ar data +Directory for additional data. +.It Ar config +Directory to additional configuration files. +.El +.El .\" EXAMPLES .Sh EXAMPLES Full example of configuration file .Bd -literal -# Add a transport that bind only to IPv6. -[transport] -type = ip -ipv4 = false -ipv6 = true -port = 12000 - -# A transport that binds to both IPv4 and IPv6. -[transport] -type = ip -port = 15000 +# Logs to syslog instead of console (which is the default). +logs verbose to syslog -# A server. -[server] -name = "foo" -host = "irc.foo.org" -port = "6667" -nickname = "superbot" -realname = "SuperBot v1.0" -username = "sp" +# +# Create a server "example" that connect to example.org using "fr" as nickname, +# "francis" as username and "Francis Meyer" as realname. +# +# This channel will automatically join "#test" on connection and the password +# protected "#nightclub" channel with password "secret" +# +server example { + hostname example.org; + port 6667; + ident fr francis "Francis Meyer"; + channels "#test", "secret@#nightclub"; +} -# An other server. -[server] -name = "wanadoo" -host = "chat.wanadoo.fr" -port = "6667" +# Load several plugins with their default values and locations. +plugin ask +plugin plugin -# Load some plugins. -[plugins] -ask = "" # Search ask -myplugin = /path/to/myplugin.js # Use absolute path +# Configure the plugin hangman to change templates and the path to the words. +plugin hangman { + templates { + win "Success, the word was #{word}!"; + } + config { + file "/var/irccd/hard-words.txt"; + } +} # This first rule disable the plugin reboot on all servers and channels. -[rule] -plugins = "reboot" -action = drop +rule drop { + plugins "reboot"; +} # This rule enable the reboot plugin again on the server localhost, # channel #staff. -[rule] -servers = "localhost" -channels = "#staff" -plugins = "reboot" -action = accept +rule accept { + servers "localhost"; + channels "#staff"; + plugins "reboot"; +} -# Example of hooks # This create an hook named "mail" with the given path. -[hooks] -mail = "/path/to/mail.py" +hook mail to "/path/to/mail.py" .Ed .\" SEE ALSO .Sh SEE ALSO
--- a/man/irccdctl.conf.5 Thu Feb 11 17:39:22 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,174 +0,0 @@ -.\" -.\" Copyright (c) 2013-2020 David Demelier <markand@malikania.fr> -.\" -.\" Permission to use, copy, modify, and/or distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd @IRCCD_MAN_DATE@ -.Dt IRCCDCTL.CONF 5 -.Os -.\" NAME -.Sh NAME -.Nm irccdctl.conf -.Nd irccdctl configuration file -.\" DESCRIPTION -.Sh DESCRIPTION -The -.Nm irccdctl -utility use the same configuration file syntax and paths, see the manual of -irccd.conf file for more information. -.\" CONFIGURATION SECTIONS -.Sh CONFIGURATION SECTIONS -Configuration are always stored in dedicated section in the form -.Ar [name] -where name is one of the section defined below and are case-sensitive. -.\" [general] -.Ss general -This section defines the global irccdctl parameters. -.Pp -Available options: -.Bl -tag -width 18n -.It Va verbose No (bool) -Enable verbose message (Optional, default: false). -.El -.\" [connect] -.Ss connect -The section socket permit irccdctl to connect to a specific irccd transport, -only one must be defined. Just like transports you can connect to Unix or -internet sockets. -.Pp -Available options: -.Bl -tag -width 18n -.It Va type No (string) -Connection type, must be set to -.Dq ip -or -.Dq unix . -.It Va password No (string) -An authentication password (Optional, default: none). -.El -.Pp -The following options are available for the -.Ar ip -type: -.Bl -tag -width 18n -.It Va hostname No (string) -Host to connect. -.It Va port No (int) -Port number. -.It Va ipv4 No (bool) -Try to connect with ipv4 (Optional: default true). -.It Va ipv6 No (bool) -Try to connect with ipv6 (Optional: default true). -.El -.Pp -The following options are available for the -.Ar unix -type: -.Bl -tag -width 18n -.It Va path No (string) -The file path to the socket. -.El -.\" [alias] -.Ss alias -The alias section can be used to define custom user commands. -.Pp -To define an alias, just add a new section named -.Va [alias.name] -where name is your desired alias name. -.Pp -Then, add any option you like to execute commands you want. The option name is -ignored and serves as auto-documentation only. -.Pp -Example: -.Bd -literal -offset Ds -[alias.present] -say-hello = ( "server-message", "localhost", "#staff", "hello world!" ) -warning = ( "server-me", "localhost", "#staff", "is a bot") -.Ed -.Pp -This alias -.Cm present -will do: -.Bl -enum -.It -Send a message on the channel #staff in the server localhost -.It -Send an action emote on the same channel -.El -.Pp -To use this alias, call -.Nm irccdctl -.Cm present . -.Pp -Sometimes, you want to pass parameters to your alias. The placeholder syntax -allows you to define where your command line arguments will be replaced before -being sent to irccd. -.Pp -The syntax uses -.Ar %n -where -.Ar n -is an integer starting from 0. -.Pp -As you have seen in the present alias example above, the channel and server -are hardcoded so the user is not able to use this alias for different channels. -Let's update this alias with placeholders to make it more generic. -.Pp -Example: -.Bd -literal -offset Ds -[alias.present] -say-hello = ( "server-message", "%0", "%1", "hello world!" ) -warning = ( "server-me", "%0", "%1", "is a bot") -.Ed -.Pp -Now, the -.Cm present -alias will except two arguments from the command line when the user invokes -irccdctl as following: -.Bd -literal -offset Ds -irccdctl present -.Ed -.Pp -Thus if you want to use this alias on the #staff@localhost, you call the alias -using: -.Bd -literal -offset Ds -irccdctl present localhost "#staff" -.Ed -.\" EXAMPLES -.Sh EXAMPLES -Example for internet transports. -.Bd -literal -[connect] -type = "internet" -hostname = "localhost" -port = "9999" -.Ed -Example for unix transports. -.Bd -literal -[connect] -type = "unix" -path = "/tmp/irccd.sock" - -# inspired by irssi /cycle -[alias.cycle] -leave = ( "server-part", "%0", "%1" ) -join = ( "server-join", "%0", "%1" ) -.Ed -.\" SEE ALSO -.Sh SEE ALSO -.Xr irccd 1 , -.Xr irccdctl 1 -.\" AUTHORS -.Sh AUTHORS -.Nm irccdctl -was written by David Demelier <markand@malikania.fr>