--- a/man/CMakeLists.txt	Wed Feb 17 22:56:50 2021 +0100
+++ b/man/CMakeLists.txt	Wed Feb 17 23:30:39 2021 +0100
@@ -41,6 +41,7 @@
 	${man_SOURCE_DIR}/libirccd-log.3
 	${man_SOURCE_DIR}/libirccd-rule.3
 	${man_SOURCE_DIR}/libirccd-util.3
+	${man_SOURCE_DIR}/libirccd-subst.3
 	${man_SOURCE_DIR}/libirccd.3
 )
 

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/libirccd-subst.3	Wed Feb 17 23:30:39 2021 +0100
@@ -0,0 +1,185 @@
+.\"
+.\" 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.
+.\"
+.Dd @IRCCD_MAN_DATE@
+.Dt LIBIRCCD-SUBST 3
+.Os
+.\" NAME
+.Sh NAME
+.Nm libirccd-subst
+.Nd create templated string
+.\" SYNOPSIS
+.Sh SYNOPSIS
+.In irccd/subst.h
+.Ft ssize_t
+.Fo irc_subst
+.Fa "char *dst"
+.Fa "size_t dstsz"
+.Fa "const char *template"
+.Fa "const struct irc_subst *subst"
+.Fc
+.\" DESCRIPTION
+.Sh DESCRIPTION
+This header provides functions to generate templated strings using a custom
+format as defined in
+.Xr irccd-templates 7 .
+.Pp
+The
+.Vt "struct irc_subst_keyword"
+and
+.Vt "struct irc_subst"
+are declared as:
+.Bd -literal
+struct irc_subst_keyword {
+	const char *key;
+	const char *value;
+};
+.Ed
+.Bd -literal
+struct irc_subst {
+	time_t time;
+	enum irc_subst_flags flags;
+	const struct irc_subst_keyword *keywords;
+	size_t keywordsz;
+};
+.Ed
+.Pp
+The fields of
+.Vt "struct irc_subst_keyword"
+are:
+.Bl -tag -width 10n
+.It Va key
+The keyword name.
+.It Va value
+The keyword value.
+.El
+.Pp
+The fields of
+.Vt "struct irc_subst"
+are:
+.Bl -tag -width 10n
+.It Va time
+The timestamp if the template contains time formatting and
+.Dv IRC_SUBST_DATE
+is present in
+.Va flags .
+.It Va flags
+The allowed formats in the source string as an OR'ed combination, see below.
+.It Va keywords
+An array of user keywords to replace in the source string.
+.It Va keywordsz
+The number of elements present in
+.Va keywords
+field.
+.El
+.Pp
+The
+.Vt "enum irc_subst_flags"
+is declared as:
+.Bd -literal
+enum irc_subst_flags {
+	IRC_SUBST_DATE          = (1 << 0),
+	IRC_SUBST_KEYWORDS      = (1 << 1),
+	IRC_SUBST_ENV           = (1 << 2),
+	IRC_SUBST_SHELL         = (1 << 3),
+	IRC_SUBST_IRC_ATTRS     = (1 << 4),
+	IRC_SUBST_SHELL_ATTRS   = (1 << 5)
+};
+.Ed
+.Pp
+The following enumerators are available:
+.Bl -tag -width IRC_SUBST_SHELL_ATTRS
+.It Dv IRC_SUBST_DATE
+Allows date formatting. In that case the
+.Va time
+field should not be 0.
+.It Dv IRC_SUBST_KEYWORDS
+Allows keywords substitutions, the fields
+.Va keywords
+and
+.Va keywordsz
+should be set but are still optional.
+.It Dv IRC_SUBST_ENV
+Allows environment variables substitution.
+.It Dv IRC_SUBST_IRC_ATTRS
+Allows IRC colors and attributes. This is mutually exclusive with
+.Dv IRC_SUBST_SHELL_ATTRS .
+.It Dv IRC_SUBST_SHELL_ATTRS
+Allows shell escape sequences for color and attributes. This is mutually
+exclusive with
+.Dv IRC_SUBST_IRC_ATTRS .
+.El
+.Pp
+The
+.Fn irc_subst
+functions convert the NUL terminated string
+.Fa template
+and store the result into the non-NULL
+.Fa dst
+buffer of
+.Fa dstsz
+max size. The function never writes more than
+.Fa dstsz
+bytes including the NUL terminator. The non-NULL
+.Fa subst
+argument controls the substitution parameters and allowed flags.
+.\" RETURN VALUES
+.Sh RETURN VALUES
+The
+.Fn irc_subst
+function return the number of bytes written in
+.Fa dst
+not including the NUL terminator. If an error occurs, -1 is returned and
+.Va errno
+is set to indicate the error.
+.\" ERRORS
+.Sh ERRORS
+The function
+.Fn irc_subst
+may set one of the following error:
+.Bl -tag -width Er
+.It Bq Er ENOMEM
+Not enough space was available in
+.Fa dst .
+.It Bq Er EINVAL
+The source string contain invalid escape sequences or syntax.
+.El
+.\" EXAMPLES
+.Sh EXAMPLES
+This call will replace the keywords
+.Dq fruit
+and
+.Dq dessert
+along with the time formatting.
+.Bd -literal
+struct irc_subst subst = {
+	.time = time(NULL),
+	.flags = IRC_SUBST_KEYWORDS | IRC_SUBST_DATE,
+	.keywordsz = 2,
+	.keywords = (const struct irc_subst_keyword[]) {
+		{ "fruit",      "orange"        },
+		{ "dessert",    "tiramisu"      }
+	}
+};
+char output[512];
+const char *input = "You've eaten #{fruit} and #{dessert} on %H:%M";
+
+irc_subst(output, sizeof (output), input, &subst);
+/* output == You've eaten orange and tiramisu on 23:23 */
+.Ed
+.\" SEE ALSO
+.Sh SEE ALSO
+.Xr irccd-templates 7 ,
+.Xr libirccd 3