aboutsummaryrefslogtreecommitdiffstats
path: root/doc/aerc-stylesets.7.scd
blob: ad05d69cf2ae1fedefaa1e8a9d80c09591f80767 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
AERC-STYLESETS(7)

# NAME

aerc-stylesets - styleset file specification for *aerc*(1)

# SYNOPSIS

aerc uses a simple configuration syntax to configure the styleset for
its ui.

# STYLESET CONFIGURATION

The styleset is described as *<object>*.*<attribute>* = _<value>_ pairs.

For example, in the line below, the foreground color of the
style object *msglist_unread* is set to _cornflowerblue_

	*msglist_unread*.*fg* = _cornflowerblue_

The configuration also allows wildcard matching of the keys
to configure multiple style objects at a time.

# ATTRIBUTES

The following options are available to be modified for each of the
style objects.

*<object>*.*fg* = _<color>_
	The foreground color of the style object is set.

*<object>*.*bg* = _<color>_
	The background color of the style object is set.

*<object>*.*bold* = _true_|_false_|_toggle_
	The bold attribute of the style object is set/unset.

*<object>*.*blink* = _true_|_false_|_toggle_
	The blink attribute of the style object is set/unset.
	The terminal needs to support blinking text.

*<object>*.*underline* = _true_|_false_|_toggle_
	The underline attribute of the style object is set/unset.
	The terminal needs to support underline text.

*<object>*.*italic* = _true_|_false_|_toggle_
	The italic attribute of the style object is set/unset.
	The terminal needs to support italic text.

*<object>*.*dim* = _true_|_false_|_toggle_
	The dim attribute of the style object is set/unset.
	The terminal needs to support half-bright text.

*<object>*.*reverse* = _true_|_false_|_toggle_
	Reverses the color of the style object. Exchanges the foreground
	and background colors.

	If the value is _false_, it doesn't change anything.

*<object>*.*normal* = true
	All the attributes of the style object are unset.

	The value doesn't matter.

*<object>*.*default* = true
	Set the style object to the default style of the context. Usually
	based on the terminal.

	The value doesn't matter.

# STYLE OBJECTS

The style objects represent the various ui elements or ui instances for
styling.

[[ *Style Object*
:[ *Description*
|  *default*
:  The default style object used for normal ui elements while not using specialized configuration.
|  *error*
:  The style used to show errors.
|  *warning*
:  The style used when showing warnings.
|  *success*
:  The style used for success messages.
|  *title*
:  The style object used to style titles in ui elements.
|  *header*
:  The style object used to style headers in ui elements.
|  *statusline_default*
:  The default style applied to the statusline.
|  *statusline_error*
:  The style used for error messages in statusline.
|  *statusline_success*
:  The style used for success messages in statusline.
|  *msglist_default*
:  The default style for messages in a message list.
|  *msglist_unread*
:  Unread messages in a message list.
|  *msglist_read*
:  Read messages in a message list.
|  *msglist_flagged*
:  The messages with the flagged flag.
|  *msglist_deleted*
:  The messages marked as deleted.
|  *msglist_marked*
:  The messages with the marked flag.
|  *msglist_result*
:  The messages which match the current search.
|  *msglist_answered*
:  The messages marked as answered.
|  *msglist_forwarded*
:  The messages marked as forwarded.
|  *msglist_gutter*
:  The message list gutter.
|  *msglist_pill*
:  The message list pill.
|  *msglist_thread_folded*
:  Visible messages that have folded thread children.
|  *msglist_thread_context*
:  The messages not matching the mailbox / query, displayed for context.
|  *msglist_thread_orphan*
:  Threaded messages that have a missing parent message.
|  *dirlist_default*
:  The default style for directories in the directory list.
|  *dirlist_unread*
:  The style used for directories with unread messages
|  *dirlist_recent*
:  The style used for directories with recent messages
|  *part_switcher*
:  Background for the part switcher in the message viewer.
|  *part_filename*
:  Attachment file name in the part switcher.
|  *part_mimetype*
:  Attachment/part MIME type in the part switcher.
|  *completion_default*
:  The default style for the completion engine.
|  *completion_gutter*
:  The completion gutter.
|  *completion_pill*
:  The completion pill.
|  *tab*
:  The style for the tab bar.
|  *stack*
:  The style for ui stack element.
|  *spinner*
:  The style for the loading spinner.
|  *border*
:  The style used to draw borders (only the *bg* color is used unless you customize *border-char-vertical* and/or *border-char-horizontal* in _aerc.conf_).
|  *selector_default*
:  The default style for the selector ui element.
|  *selector_focused*
:  The focused item in a selector ui element.
|  *selector_chooser*
:  The item chooser in a selector ui element.

These next style objects only affect the built-in *colorize* filter and must be
declared under a *[viewer]* section of the styleset file.

[[ *Style Object*
:[ *Description*
|  *url*
:  URLs.
|  *header*
:  RFC-822-like header names.
|  *signature*
:  Email signatures.
|  *diff_meta*
:  Patch diff meta lines.
|  *diff_chunk*
:  Patch diff chunks.
|  *diff_chunk_func*
:  Patch diff chunk function names.
|  *diff_add*
:  Patch diff added lines.
|  *diff_del*
:  Patch diff deleted lines.
|  *quote_1*
:  First level quoted text.
|  *quote_2*
:  Second level quoted text.
|  *quote_3*
:  Third level quoted text.
|  *quote_4*
:  Fourth level quoted text.
|  *quote_x*
:  Above fourth level quoted text.

User defined styles can be used to style arbitrary strings in go-templates (see
_.Style_ in *aerc-templates*(7)). User styles must be defined in the _[user]_
ini section. Styles can be referenced by their name (e.g. _red.fg_ is named
"red").

Example:

```
[user]
red.fg=red
```

User styles are layered with other styles applied to the context in which they
are rendered. The user style colors (fg and/or bg) will only be effective if the
context style does not define any. Other boolean attributes will be merged with
the underlying style boolean attributes.

For example, if the context style is:

	fg=red bold

And the inline style is:

	fg=yellow italic underline

The effective style will be:

	fg=red bold italic underline

# FNMATCH STYLE WILDCARD MATCHING

The styleset configuration can be made simpler by using the fnmatch
style wildcard matching for the style object.

The special characters used in the fnmatch wildcards are:

[[ *Pattern*
:[ *Meaning*
|  *\**
:  Matches everything
|  *\?*
:  Matches any single character

For example, the following wildcards can be made using this syntax.

[[ *Example*
:[ *Description*
|  *\**.*fg* = _blue_
:  Set the foreground color of all style objects to blue.
|  *\*list*.*bg* = _hotpink_
:  Set the background color of all style objects that end in list to hotpink.

Note that the statements in a given styleset are parsed in the order in which
they are written. That means that with the following styleset:

```
msglist_marked.fg = pink
msglist_*.fg = white
```

The *msglist_marked.fg* attribute will be set to _white_.

# SELECTED MODIFIER

The *selected* modifier can be applied to any style object. The style provided for
the *selected* modifier is applied on top of the style object it corresponds to.

If you would like to make sure message that are flagged as read in the msglist
appear in yellow foreground and black background. You can specify that with
this:

	*msglist_default*.*selected*.*fg* = _yellow_

	*msglist_default*.*selected*.*bg* = _black_

If we specify the global style selected modifier using fnmatch as below:

	*\**.*selected*.*reverse* = _toggle_

This toggles the reverse switch for selected version of all the style objects.

*selected* objects inherit from all attributes of their non-selected
counterparts. *selected* statements are parsed after non-selected ones and
effectively override the attributes of the non-selected style object.

# LAYERED STYLES

Some styles, (currently the *msglist_\** and *dirlist_\** ones) are applied in
layers. If a style differs from the base (in this case *\*list_default*) then
that style applies, unless overridden by a higher layer. If *fg* and *bg* colors
are not defined explicitly (or defined to the default color) they will be
considered as "transparent" and the colors from the lower layer will be used
instead.

The order that *msglist_\** styles are applied in is, from first to last:

. *msglist_default*
. *msglist_unread*
. *msglist_read*
. *msglist_answered*
. *msglist_forwarded*
. *msglist_flagged*
. *msglist_deleted*
. *msglist_result*
. *msglist_thread_folded*
. *msglist_thread_context*
. *msglist_thread_orphan*
. *msglist_marked*

So, the marked style will override all other msglist styles.

The order for *dirlist_\** styles is:

. *dirlist_default*
. *dirlist_unread*
. *dirlist_recent*

# DYNAMIC MESSAGE LIST STYLES

All *msglist_\** styles can be defined for specific email header values. The
syntax is as follows:

	*msglist_<name>*._<header>_,_<header_value>_.*<attribute>* = _<attr_value>_

If _<header_value>_ starts with a tilde character _~_, it will be interpreted as
a regular expression.

Examples:

```
msglist\*.X-Sourcehut-Patchset-Update,APPROVED.fg = green
msglist\*.X-Sourcehut-Patchset-Update,NEEDS\_REVISION.fg = yellow
msglist\*.X-Sourcehut-Patchset-Update,REJECTED.fg = red
"msglist_*.Subject,~^(\\[[\w-]+\]\\s*)?\\[(RFC )?PATCH.fg" = #ffffaf
"msglist_*.Subject,~^(\\[[\w-]+\]\\s*)?\\[(RFC )?PATCH.selected.fg" = #ffffaf
```

When a dynamic style is matched to an email header, it will be used in priority
compared to its non-dynamic counterpart. Provided the following styleset:

```
msglist_marked.fg = blue
msglist_*.Subject,~foobar.fg = red
```

An email with _foobar_ it its subject will be colored in _red_ all the time,
since *msglist_\** also applies to *msglist\_marked*.

# COLORS

The color values are set using any of the following methods:

_default_
	The color is set as per the system or terminal default.

_<Color name>_
	Any w3c approved color name is used to set colors for the style.

_<Hex code>_
	Hexcode for a color can be used. The format must be _#XXXXXX_.

_<Dec number>_
	Color based on the terminal palette index. Valid numbers are
	between _0_ and _255_.

# DEFAULTS

Before parsing a styleset, it is first initialized with the following defaults:

```
*.selected.bg = 12
*.selected.fg = 15
*.selected.bold = true
statusline_*.dim = true
statusline_*.bg = 8
statusline_*.fg = 15
*warning.fg = 3
*success.fg = 2
*error.fg = 1
*error.bold = true
border.bg = 12
border.fg = 15
title.bg = 12
title.fg = 15
title.bold = true
header.fg = 4
header.bold = true
msglist_unread.bold = true
msglist_deleted.dim = true
msglist_marked.bg = 6
msglist_marked.fg = 15
msglist_pill.bg = 12
msglist_pill.fg = 15
part_mimetype.fg = 12
selector_chooser.bold = true
selector_focused.bold = true
selector_focused.bg = 12
selector_focused.fg = 15
completion_pill.bg = 12
completion_default.bg = 8
completion_default.fg = 15

[viewer]
url.underline = true
url.fg = 3
header.bold = true
header.fg = 4
signature.dim = true
signature.fg = 4
diff_meta.bold = true
diff_chunk.fg = 6
diff_chunk_func.fg = 6
diff_chunk_func.dim = true
diff_add.fg = 2
diff_del.fg = 1
quote_1.fg = 6
quote_2.fg = 4
quote_3.fg = 6
quote_3.dim = true
quote_4.fg = 4
quote_4.dim = true
quote_x.fg = 5
quote_x.dim = true
```

You can choose either to reset everything (except in the *[viewer]* section) by
starting your styleset with these two lines:

```
*.default=true
*.normal=true
```

Or selectively override style object attributes.

If you want to also reset the *[viewer]* section, you need to insert the same
two lines:

```
[viewer]
*.default=true
*.normal=true
```

# SEE ALSO

*aerc*(1) *aerc-config*(5)

# AUTHORS

Originally created by Drew DeVault and maintained by Robin Jarry who is assisted
by other open source contributors. For more information about aerc development,
see _https://sr.ht/~rjarry/aerc/_.