Mercurial > irccd

comparison man/irccd-templates.7 @ 845:00a4720c4874

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: rewrite documentation in manual pages, closes #1674 Get rid of markdown documentation and the custom generator tools, instead use raw manual pages.
author David Demelier <markand@malikania.fr>
date Mon, 08 Jul 2019 16:15:57 +0200
parents
children 54496ac51649
comparison
equal deleted inserted replaced
844:dc6b42d7b97a 845:00a4720c4874
1 .\"
2 .\" Copyright (c) 2013-2019 David Demelier <markand@malikania.fr>
3 .\"
4 .\" Permission to use, copy, modify, and/or distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd @IRCCD_MAN_DATE@
17 .Dt IRCCD-TEMPLATES 7
18 .Os
19 .\" NAME
20 .Sh NAME
21 .Nm irccd-templates
22 .Nd irccd formatting and common patterns
23 .\" DESCRIPTION
24 .Sh DESCRIPTION
25 Plugins can be configured using a powerful template syntax, this allows editing
26 the plugin messages to override them.
27 .Pp
28 The syntax is
29 .Ar \&?{}
30 where
31 .Ar \&?
32 is replaced by one of the token defined below. Braces are mandatory and cannot
33 be ommited. To write a literal template construct, prepend the token twice.
34 .Pp
35 The following templates are available:
36 .Bl -tag -width 14n
37 .It Ar %
38 date and time (see Time section).
39 .It Ar #{name}
40 name will be substituted from the keywords (see Keywords section).
41 .It Ar ${name}
42 name will be substituted from the environment variable (see Environment
43 variables).
44 .It Ar @{attributes}
45 the attributes will be substituted to IRC colors (see Attributes).
46 .El
47 .\" TIME
48 .Sh TIME
49 The date and time format may be used just like
50 .Xr strftime 3
51 so for the hours and minutes, you can write %H:%M.
52 .\" ENVIRONMENT VARIABLES
53 .Sh ENVIRONMENT VARIABLES
54 If supported, you can use environment variables like ${HOME}. Please note
55 that braces are mandatory.
56 .\" IRC ATTRIBUTES
57 .Sh IRC ATTRIBUTES
58 The attribute format is composed of three parts, foreground, background and
59 modifiers, each separated by a comma.
60 .Pp
61 Note: attributes and colors are not supported by all IRC clients.
62 .Pp
63 Warning: do not use colors and attributes outside IRC (e.g. for storing text in
64 files) because escape codes are only valid in IRC context.
65 .Ss Available colors
66 .Bl -bullet -compact
67 .It
68 white
69 .It
70 black
71 .It
72 blue
73 .It
74 green
75 .It
76 red
77 .It
78 brown
79 .It
80 purple
81 .It
82 orange
83 .It
84 yellow
85 .It
86 lightgreen
87 .It
88 cyan
89 .It
90 lightcyan
91 .It
92 lightblue
93 .It
94 pink
95 .It
96 grey
97 .It
98 lightgrey
99 .El
100 .Ss Available attributes
101 .Bl -bullet -compact
102 .It
103 bold
104 .It
105 italic
106 .It
107 strike
108 .It
109 reset
110 .It
111 underline
112 .It
113 underline2
114 .It
115 reverse
116 .El
117 .\" SHELL ATTRIBUTES
118 .Sh SHELL ATTRIBUTES
119 Like IRC attributes, it's possible to specify colors and attributes in some
120 places such as logger configuration.
121 .Pp
122 Warning: colors are not supported on all platforms.
123 .Ss Available colors
124 .Bl -bullet -compact
125 .It
126 black
127 .It
128 red
129 .It
130 green
131 .It
132 orange
133 .It
134 blue
135 .It
136 purple
137 .It
138 cyan
139 .It
140 white
141 .It
142 default
143 .El
144 .Ss Available attributes
145 .Bl -bullet -compact
146 .It
147 bold
148 .It
149 dim
150 .It
151 underline
152 .It
153 blink
154 .It
155 reverse
156 .It
157 hidden
158 .El
159 .\" KEYWORDS
160 .Sh KEYWORDS
161 Keywords are arbitrary names that are replaced depending on the context. They
162 are usually available to configure plugins.
163 .Ss Predefined keywords
164 Here's the list of keywords that a lot of plugins uses:
165 .Bl -tag -width 12n
166 .It Va #{channel}
167 the channel name,
168 .It Va #{command}
169 the command to invoke the plugin, e.g. `!ask`,
170 .It Va #{message}
171 a message (depending on context),
172 .It Va #{origin}
173 the full user, e.g. `markand!~mkd@localhost`,
174 .It Va #{nickname}
175 the short nickname,
176 .It Va #{plugin}
177 the plugin name,
178 .It Va #{server}
179 the current server name,
180 .It Va #{topic}
181 the topic,
182 .It Va #{target}
183 a target, e.g. a person who gets kicked.
184 .El
185 .Pp
186 Warning: these keywords can be overriden by plugins.
187 .\" EXAMPLES
188 .Sh EXAMPLES
189 Valid constructs:
190 .Bl -tag -width 20n -offset Ds
191 .It #{target}, welcome
192 if target is set to "irccd", becomes "irccd, welcome".
193 .It @{red}#{target}
194 if target is specified, it is written in red.
195 .El
196 .Pp
197 Invalid or literals constructs:
198 .Bl -tag -width 20n -offset Ds
199 .It #{target}
200 will output "#{target}".
201 .It ##
202 will output "##".
203 .It #target
204 will output "#target".
205 .It #{target
206 will cause an error.
207 .El
208 .Pp
209 Colors & attributes:
210 .Bl -tag -width 20n -offset Ds
211 .It @{red,blue}
212 will write text red on blue background,
213 .It @{default,yellow}
214 will write default color text on yellow background,
215 .It @{white,black,bold,underline}
216 will write white text on black in both bold and underline.
217 .El
218 .Pp
219 For instance, using the logger plugin, it's possible to customize the pattern to
220 use when someone joins a channel like that:
221 .Bd -literal -offset Ds
222 #{origin} joined #{channel}
223 .Ed
224 .Pp
225 The keyword #{origin} will be substituted to the nickname and #{channel} to the
226 channel name.
227 .\" SEE ALSO
228 .Sh SEE ALSO
229 .Xr irccd 1 ,
230 .Xr irccd.conf 5