.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "AERC-STYLESETS" "7" "2024-07-30"
.PP
.SH NAME
.PP
aerc-stylesets - styleset file specification for \fBaerc\fR(1)
.PP
.SH SYNOPSIS
.PP
aerc uses a simple configuration syntax to configure the styleset for
its ui.\&
.PP
.SH STYLESET CONFIGURATION
.PP
The styleset is described as \fB<object>\fR.\&\fB<attribute>\fR = \fI<value>\fR pairs.\&
.PP
For example, in the line below, the foreground color of the
style object \fBmsglist_unread\fR is set to \fIcornflowerblue\fR
.PP
.RS 4
\fBmsglist_unread\fR.\&\fBfg\fR = \fIcornflowerblue\fR
.PP
.RE
The configuration also allows wildcard matching of the keys
to configure multiple style objects at a time.\&
.PP
.SH ATTRIBUTES
.PP
The following options are available to be modified for each of the
style objects.\&
.PP
\fB<object>\fR.\&\fBfg\fR = \fI<color>\fR
.RS 4
The foreground color of the style object is set.\&
.PP
.RE
\fB<object>\fR.\&\fBbg\fR = \fI<color>\fR
.RS 4
The background color of the style object is set.\&
.PP
.RE
\fB<object>\fR.\&\fBbold\fR = \fItrue\fR|\fIfalse\fR|\fItoggle\fR
.RS 4
The bold attribute of the style object is set/unset.\&
.PP
.RE
\fB<object>\fR.\&\fBblink\fR = \fItrue\fR|\fIfalse\fR|\fItoggle\fR
.RS 4
The blink attribute of the style object is set/unset.\&
The terminal needs to support blinking text.\&
.PP
.RE
\fB<object>\fR.\&\fBunderline\fR = \fItrue\fR|\fIfalse\fR|\fItoggle\fR
.RS 4
The underline attribute of the style object is set/unset.\&
The terminal needs to support underline text.\&
.PP
.RE
\fB<object>\fR.\&\fBitalic\fR = \fItrue\fR|\fIfalse\fR|\fItoggle\fR
.RS 4
The italic attribute of the style object is set/unset.\&
The terminal needs to support italic text.\&
.PP
.RE
\fB<object>\fR.\&\fBdim\fR = \fItrue\fR|\fIfalse\fR|\fItoggle\fR
.RS 4
The dim attribute of the style object is set/unset.\&
The terminal needs to support half-bright text.\&
.PP
.RE
\fB<object>\fR.\&\fBreverse\fR = \fItrue\fR|\fIfalse\fR|\fItoggle\fR
.RS 4
Reverses the color of the style object.\& Exchanges the foreground
and background colors.\&
.PP
If the value is \fIfalse\fR, it doesn'\&t change anything.\&
.PP
.RE
\fB<object>\fR.\&\fBnormal\fR = true
.RS 4
All the attributes of the style object are unset.\&
.PP
The value doesn'\&t matter.\&
.PP
.RE
\fB<object>\fR.\&\fBdefault\fR = true
.RS 4
Set the style object to the default style of the context.\& Usually
based on the terminal.\&
.PP
The value doesn'\&t matter.\&
.PP
.RE
.SH STYLE OBJECTS
.PP
The style objects represent the various ui elements or ui instances for
styling.\&
.PP
.TS
allbox;l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
\fBStyle Object\fR
T}	T{
\fBDescription\fR
T}
T{
\fBdefault\fR
T}	T{
The default style object used for normal ui elements while not using specialized configuration.\&
T}
T{
\fBerror\fR
T}	T{
The style used to show errors.\&
T}
T{
\fBwarning\fR
T}	T{
The style used when showing warnings.\&
T}
T{
\fBsuccess\fR
T}	T{
The style used for success messages.\&
T}
T{
\fBtitle\fR
T}	T{
The style object used to style titles in ui elements.\&
T}
T{
\fBheader\fR
T}	T{
The style object used to style headers in ui elements.\&
T}
T{
\fBstatusline_default\fR
T}	T{
The default style applied to the statusline.\&
T}
T{
\fBstatusline_error\fR
T}	T{
The style used for error messages in statusline.\&
T}
T{
\fBstatusline_success\fR
T}	T{
The style used for success messages in statusline.\&
T}
T{
\fBmsglist_default\fR
T}	T{
The default style for messages in a message list.\&
T}
T{
\fBmsglist_unread\fR
T}	T{
Unread messages in a message list.\&
T}
T{
\fBmsglist_read\fR
T}	T{
Read messages in a message list.\&
T}
T{
\fBmsglist_flagged\fR
T}	T{
The messages with the flagged flag.\&
T}
T{
\fBmsglist_deleted\fR
T}	T{
The messages marked as deleted.\&
T}
T{
\fBmsglist_marked\fR
T}	T{
The messages with the marked flag.\&
T}
T{
\fBmsglist_result\fR
T}	T{
The messages which match the current search.\&
T}
T{
\fBmsglist_answered\fR
T}	T{
The messages marked as answered.\&
T}
T{
\fBmsglist_gutter\fR
T}	T{
The message list gutter.\&
T}
T{
\fBmsglist_pill\fR
T}	T{
The message list pill.\&
T}
T{
\fBmsglist_thread_folded\fR
T}	T{
Visible messages that have folded thread children.\&
T}
T{
\fBmsglist_thread_context\fR
T}	T{
The messages not matching the mailbox / query, displayed for context.\&
T}
T{
\fBmsglist_thread_orphan\fR
T}	T{
Threaded messages that have a missing parent message.\&
T}
T{
\fBdirlist_default\fR
T}	T{
The default style for directories in the directory list.\&
T}
T{
\fBdirlist_unread\fR
T}	T{
The style used for directories with unread messages
T}
T{
\fBdirlist_recent\fR
T}	T{
The style used for directories with recent messages
T}
T{
\fBpart_switcher\fR
T}	T{
Background for the part switcher in the message viewer.\&
T}
T{
\fBpart_filename\fR
T}	T{
Attachment file name in the part switcher.\&
T}
T{
\fBpart_mimetype\fR
T}	T{
Attachment/part MIME type in the part switcher.\&
T}
T{
\fBcompletion_default\fR
T}	T{
The default style for the completion engine.\&
T}
T{
\fBcompletion_gutter\fR
T}	T{
The completion gutter.\&
T}
T{
\fBcompletion_pill\fR
T}	T{
The completion pill.\&
T}
T{
\fBtab\fR
T}	T{
The style for the tab bar.\&
T}
T{
\fBstack\fR
T}	T{
The style for ui stack element.\&
T}
T{
\fBspinner\fR
T}	T{
The style for the loading spinner.\&
T}
T{
\fBborder\fR
T}	T{
The style used to draw borders (only the \fBbg\fR color is used unless you customize \fBborder-char-vertical\fR and/or \fBborder-char-horizontal\fR in \fIaerc.\&conf\fR).\&
T}
T{
\fBselector_default\fR
T}	T{
The default style for the selector ui element.\&
T}
T{
\fBselector_focused\fR
T}	T{
The focused item in a selector ui element.\&
T}
T{
\fBselector_chooser\fR
T}	T{
The item chooser in a selector ui element.\&
T}
.TE
.sp 1
These next style objects only affect the built-in \fBcolorize\fR filter and must be
declared under a \fB[viewer]\fR section of the styleset file.\&
.PP
.TS
allbox;l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
\fBStyle Object\fR
T}	T{
\fBDescription\fR
T}
T{
\fBurl\fR
T}	T{
URLs.\&
T}
T{
\fBheader\fR
T}	T{
RFC-822-like header names.\&
T}
T{
\fBsignature\fR
T}	T{
Email signatures.\&
T}
T{
\fBdiff_meta\fR
T}	T{
Patch diff meta lines.\&
T}
T{
\fBdiff_chunk\fR
T}	T{
Patch diff chunks.\&
T}
T{
\fBdiff_chunk_func\fR
T}	T{
Patch diff chunk function names.\&
T}
T{
\fBdiff_add\fR
T}	T{
Patch diff added lines.\&
T}
T{
\fBdiff_del\fR
T}	T{
Patch diff deleted lines.\&
T}
T{
\fBquote_1\fR
T}	T{
First level quoted text.\&
T}
T{
\fBquote_2\fR
T}	T{
Second level quoted text.\&
T}
T{
\fBquote_3\fR
T}	T{
Third level quoted text.\&
T}
T{
\fBquote_4\fR
T}	T{
Fourth level quoted text.\&
T}
T{
\fBquote_x\fR
T}	T{
Above fourth level quoted text.\&
T}
.TE
.sp 1
User defined styles can be used to style arbitrary strings in go-templates (see
\fI.\&Style\fR in \fBaerc-templates\fR(7)).\& User styles must be defined in the \fI[user]\fR
ini section.\& Styles can be referenced by their name (e.\&g.\& \fIred.\&fg\fR is named
"red").\&
.PP
Example:
.PP
.nf
.RS 4
[user]
red\&.fg=red
.fi
.RE
.PP
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.\&
.PP
For example, if the context style is:
.PP
.RS 4
fg=red bold
.PP
.RE
And the inline style is:
.PP
.RS 4
fg=yellow italic underline
.PP
.RE
The effective style will be:
.PP
.RS 4
fg=red bold italic underline
.PP
.RE
.SH FNMATCH STYLE WILDCARD MATCHING
.PP
The styleset configuration can be made simpler by using the fnmatch
style wildcard matching for the style object.\&
.PP
The special characters used in the fnmatch wildcards are:
.PP
.TS
allbox;l l
l l
l l.
T{
\fBPattern\fR
T}	T{
\fBMeaning\fR
T}
T{
\fB*\fR
T}	T{
Matches everything
T}
T{
\fB?\fR
T}	T{
Matches any single character
T}
.TE
.sp 1
For example, the following wildcards can be made using this syntax.\&
.PP
.TS
allbox;l l
l l
l l.
T{
\fBExample\fR
T}	T{
\fBDescription\fR
T}
T{
\fB*\fR.\&\fBfg\fR = \fIblue\fR
T}	T{
Set the foreground color of all style objects to blue.\&
T}
T{
\fB*list\fR.\&\fBbg\fR = \fIhotpink\fR
T}	T{
Set the background color of all style objects that end in list to hotpink.\&
T}
.TE
.sp 1
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:
.PP
.nf
.RS 4
msglist_marked\&.fg = pink
msglist_*\&.fg = white
.fi
.RE
.PP
The \fBmsglist_marked.\&fg\fR attribute will be set to \fIwhite\fR.\&
.PP
.SH SELECTED MODIFIER
.PP
The \fBselected\fR modifier can be applied to any style object.\& The style provided for
the \fBselected\fR modifier is applied on top of the style object it corresponds to.\&
.PP
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:
.PP
.RS 4
\fBmsglist_default\fR.\&\fBselected\fR.\&\fBfg\fR = \fIyellow\fR
.PP
\fBmsglist_default\fR.\&\fBselected\fR.\&\fBbg\fR = \fIblack\fR
.PP
.RE
If we specify the global style selected modifier using fnmatch as below:
.PP
.RS 4
\fB*\fR.\&\fBselected\fR.\&\fBreverse\fR = \fItoggle\fR
.PP
.RE
This toggles the reverse switch for selected version of all the style objects.\&
.PP
\fBselected\fR objects inherit from all attributes of their non-selected
counterparts.\& \fBselected\fR statements are parsed after non-selected ones and
effectively override the attributes of the non-selected style object.\&
.PP
.SH LAYERED STYLES
.PP
Some styles, (currently the \fBmsglist_*\fR and \fBdirlist_*\fR ones) are applied in
layers.\& If a style differs from the base (in this case \fB*list_default\fR) then
that style applies, unless overridden by a higher layer.\& If \fBfg\fR and \fBbg\fR 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.\&
.PP
The order that \fBmsglist_*\fR styles are applied in is, from first to last:
.PP
.PD 0
.IP 1. 4
\fBmsglist_default\fR
.IP 2. 4
\fBmsglist_unread\fR
.IP 3. 4
\fBmsglist_read\fR
.IP 4. 4
\fBmsglist_answered\fR
.IP 5. 4
\fBmsglist_flagged\fR
.IP 6. 4
\fBmsglist_deleted\fR
.IP 7. 4
\fBmsglist_result\fR
.IP 8. 4
\fBmsglist_thread_folded\fR
.IP 9. 4
\fBmsglist_thread_context\fR
.IP 10. 4
\fBmsglist_thread_orphan\fR
.IP 11. 4
\fBmsglist_marked\fR
.PD
.PP
So, the marked style will override all other msglist styles.\&
.PP
The order for \fBdirlist_*\fR styles is:
.PP
.PD 0
.IP 1. 4
\fBdirlist_default\fR
.IP 2. 4
\fBdirlist_unread\fR
.IP 3. 4
\fBdirlist_recent\fR
.PD
.PP
.SH DYNAMIC MESSAGE LIST STYLES
.PP
All \fBmsglist_*\fR styles can be defined for specific email header values.\& The
syntax is as follows:
.PP
.RS 4
\fBmsglist_<name>\fR.\&\fI<header>\fR,\fI<header_value>\fR.\&\fB<attribute>\fR = \fI<attr_value>\fR
.PP
.RE
If \fI<header_value>\fR starts with a tilde character \fI~\fR, it will be interpreted as
a regular expression.\&
.PP
Examples:
.PP
.nf
.RS 4
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
.fi
.RE
.PP
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:
.PP
.nf
.RS 4
msglist_marked\&.fg = blue
msglist_*\&.Subject,~foobar\&.fg = red
.fi
.RE
.PP
An email with \fIfoobar\fR it its subject will be colored in \fIred\fR all the time,
since \fBmsglist_*\fR also applies to \fBmsglist_marked\fR.\&
.PP
.SH COLORS
.PP
The color values are set using any of the following methods:
.PP
\fIdefault\fR
.RS 4
The color is set as per the system or terminal default.\&
.PP
.RE
\fI<Color name>\fR
.RS 4
Any w3c approved color name is used to set colors for the style.\&
.PP
.RE
\fI<Hex code>\fR
.RS 4
Hexcode for a color can be used.\& The format must be \fI#XXXXXX\fR.\&
.PP
.RE
\fI<Dec number>\fR
.RS 4
Color based on the terminal palette index.\& Valid numbers are
between \fI0\fR and \fI255\fR.\&
.PP
.RE
.SH DEFAULTS
.PP
Before parsing a styleset, it is first initialized with the following defaults:
.PP
.nf
.RS 4
*\&.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
.fi
.RE
.PP
You can choose either to reset everything (except in the \fB[viewer]\fR section) by
starting your styleset with these two lines:
.PP
.nf
.RS 4
*\&.default=true
*\&.normal=true
.fi
.RE
.PP
Or selectively override style object attributes.\&
.PP
If you want to also reset the \fB[viewer]\fR section, you need to insert the same
two lines:
.PP
.nf
.RS 4
[viewer]
*\&.default=true
*\&.normal=true
.fi
.RE
.PP
.SH SEE ALSO
.PP
\fBaerc\fR(1) \fBaerc-config\fR(5)
.PP
.SH AUTHORS
.PP
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 \fIhttps://sr.\&ht/~rjarry/aerc/\fR.\&