From 449e526953db7c2e31febe6bd2d0f520bee0a005 Mon Sep 17 00:00:00 2001 From: Manos Pitsidianakis Date: Tue, 28 Jan 2020 00:32:40 +0200 Subject: [PATCH] Add meli-themes.5 doc, update others --- meli-themes.5 | 472 ++++++++++++++++++++++++++++++++++++++++++++++++++ meli.1 | 13 +- meli.conf.5 | 28 ++- 3 files changed, 507 insertions(+), 6 deletions(-) create mode 100644 meli-themes.5 diff --git a/meli-themes.5 b/meli-themes.5 new file mode 100644 index 000000000..196f1d603 --- /dev/null +++ b/meli-themes.5 @@ -0,0 +1,472 @@ +.\" meli - meli-themes.5 +.\" +.\" Copyright 2017-2020 Manos Pitsidianakis +.\" +.\" This file is part of meli. +.\" +.\" meli is free software: you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation, either version 3 of the License, or +.\" (at your option) any later version. +.\" +.\" meli is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with meli. If not, see . +.\" +.Dd January 23, 2020 +.Dt MELI-THEMES 5 +.Os +.Sh NAME +.Nm meli-themes +.Nd themes for the +.Nm meli +mail client +.Sh SYNOPSIS +.Nm meli +comes with two themes, +.Ic dark +(the default) and +.Ic light. +The application theme is defined in the configuration as follows: +.Bd +[terminal] +theme = "dark" +.Ed +Custom themes can be defined as lists of key-values in the configuration files: + +.Bl -compact +.It +.Pa $XDG_CONFIG_HOME/meli/config.toml +.It +.Pa $XDG_CONFIG_HOME/meli/themes/*.toml +.El +.Sh DESCRIPTION +Themes for +.Nm meli +are described in the configuration language TOML. +They are key-value tables defined in the TERMINAL section of the configuration file. +Each key defines the semantic location of the theme attribute within the application. +For example, "mail.listing.compact.* keys are settings for the `compact` mail listing style. +A setting contains three fields: fg for foreground color, bg for background color, and attrs for attribute. +Each field contains a value, and each value can be either a color/attribute, or a key name. +In the latter case the setting's real value depends on the value of the key. +This allows for defaults within a group of associated values. +Cycles in a theme's links results in an error. +.Pp +Two themes are included by default, `light` and `dark`. +Specific settings from already defined themes can be overwritten: +.Bd -literal +[terminal] +theme = "dark" + +[terminal.themes.dark] +"mail.sidebar_highlighted_account" = { bg = "#ff4529" } +"mail.listing.attachment_flag" = { fg = "#ff4529" } +"mail.view.headers" = { fg = "30" } +"mail.view.body" = {fg = "HotPink3", bg = "LightSalmon1"} +# Linked value keys can be whatever: +"mail.listing.compact.unseen" = { bg = "mail.sidebar_highlighted_account" } + +# define new theme. Undefined settings will inherit from the default "dark" theme. +[terminal.themes."hunter2"] +"mail.view.headers" = { fg = "White", bg = "Black" } +.Ed +.Sh CUSTOM THEMES +Custom themes can be included in your configuration files or be saved independently in your +.Pa $XDG_CONFIG_HOME/meli/themes/ +directory as TOML files. To start creating a theme right away, you can begin by editing the default theme keys and values: +.Bd -literal +meli --print-default-theme > ~/.config/meli/themes/new_theme.toml +.Ed + +.Pa new_theme.toml +will now include all keys and values of the "dark" theme. + +.Fl -print-loaded-themes +.Ed +will print all loaded themes with the links resolved. +.Sh VALID ATTRIBUTE VALUES +Case-sensitive. +.Bl -bullet -compact +.It +"Default" +.It +"Bold" +.It +"Underline" +.It +"BoldUnderline" +.It +"Reverse" +.It +"BoldReverse" +.It +"UnderlineReverse" +.It +"BoldReverseUnderline" +.El +.Sh VALID COLOR VALUES +Color values are of type String with the following valid contents: +.Bl -bullet -compact +.It +"Default" Terminal default. +.It +Hex triplet eg #FFFFFF for RGB colors +(three letter shorthand also valid, eg #09c → #0099cc) (Case-insensitive) +.It +0-255 byte for 256 colors. +.It +.Xr xterm 1 +name but with some modifications (for a full table see COLOR NAMES addendum) (Case-sensitive) +.El +.Sh NO COLOR +To completely disable ANSI colors, there are two options: +.Bl -bullet -compact +.It +Set the +.Ic use_color +option (section +.Ic terminal Ns +.Ns ) +to false, which is true by default. +.It +The +.Ev NO_COLOR +environmental variable, when present (regardless of its value), prevents the addition of ANSI color. When the configuration value +.Ic use_color +is explicitly set to true by the user, +.Ev NO_COLOR +is ignored. +.El + +In this mode, cursor locations (i.e. currently selected entries/items) will use the "reverse video" ANSI attribute to inverse the terminal's default foreground/background colors. + +.Sh VALID KEYS +.TS +allbox tab(:); +lb +l. +key name +theme_default +status.bar +status.notification +tab.focused +tab.unfocused +tab.bar +widgets.form.label +widgets.form.field +widgets.form.highlighted +widgets.options.highlighted +mail.sidebar +mail.sidebar_unread_count +mail.sidebar_index +mail.sidebar_highlighted +mail.sidebar_highlighted_unread_count +mail.sidebar_highlighted_index +mail.sidebar_highlighted_account +mail.sidebar_highlighted_account_unread_count +mail.sidebar_highlighted_account_index +mail.listing.compact.even +mail.listing.compact.odd +mail.listing.compact.unseen +mail.listing.compact.selected +mail.listing.compact.highlighted +mail.listing.plain.even +mail.listing.plain.odd +mail.listing.plain.unseen +mail.listing.plain.selected +mail.listing.plain.highlighted +mail.listing.conversations +mail.listing.conversations.subject +mail.listing.conversations.from +mail.listing.conversations.date +mail.listing.conversations.padding +mail.listing.conversations.unseen +mail.listing.conversations.unseen_padding +mail.listing.conversations.highlighted +mail.listing.conversations.selected +mail.view.headers +mail.view.body +mail.listing.attachment_flag +mail.listing.thread_snooze_flag +.TE +.Sh COLOR NAMES +.TS +allbox tab(:); +lb|lb|l|lb|lb +l l|l|l l. +name ↓:byte:_:name:byte ↓ +Aqua:14:_:Black:0 +Aquamarine1:122:_:Maroon:1 +Aquamarine2:86:_:Green:2 +Aquamarine3:79:_:Olive:3 +Black:0:_:Navy:4 +Blue:12:_:Purple1:5 +Blue1:21:_:Teal:6 +Blue2:19:_:Silver:7 +Blue3:20:_:Grey:8 +BlueViolet:57:_:Red:9 +CadetBlue:72:_:Lime:10 +CadetBlue1:73:_:Yellow:11 +Chartreuse1:118:_:Blue:12 +Chartreuse2:112:_:Fuchsia:13 +Chartreuse3:82:_:Aqua:14 +Chartreuse4:70:_:White:15 +Chartreuse5:76:_:Grey0:16 +Chartreuse6:64:_:NavyBlue:17 +CornflowerBlue:69:_:DarkBlue:18 +Cornsilk1:230:_:Blue2:19 +Cyan1:51:_:Blue3:20 +Cyan2:50:_:Blue1:21 +Cyan3:43:_:DarkGreen:22 +DarkBlue:18:_:DeepSkyBlue5:23 +DarkCyan:36:_:DeepSkyBlue6:24 +DarkGoldenrod:136:_:DeepSkyBlue7:25 +DarkGreen:22:_:DodgerBlue3:26 +DarkKhaki:143:_:DodgerBlue2:27 +DarkMagenta:90:_:Green4:28 +DarkMagenta1:91:_:SpringGreen6:29 +DarkOliveGreen1:192:_:Turquoise4:30 +DarkOliveGreen2:155:_:DeepSkyBlue3:31 +DarkOliveGreen3:191:_:DeepSkyBlue4:32 +DarkOliveGreen4:107:_:DodgerBlue1:33 +DarkOliveGreen5:113:_:Green2:34 +DarkOliveGreen6:149:_:SpringGreen4:35 +DarkOrange:208:_:DarkCyan:36 +DarkOrange2:130:_:LightSeaGreen:37 +DarkOrange3:166:_:DeepSkyBlue2:38 +DarkRed:52:_:DeepSkyBlue1:39 +DarkRed2:88:_:Green3:40 +DarkSeaGreen:108:_:SpringGreen5:41 +DarkSeaGreen1:158:_:SpringGreen2:42 +DarkSeaGreen2:193:_:Cyan3:43 +DarkSeaGreen3:151:_:DarkTurquoise:44 +DarkSeaGreen4:157:_:Turquoise2:45 +DarkSeaGreen5:115:_:Green1:46 +DarkSeaGreen6:150:_:SpringGreen3:47 +DarkSeaGreen7:65:_:SpringGreen1:48 +DarkSeaGreen8:71:_:MediumSpringGreen:49 +DarkSlateGray1:123:_:Cyan2:50 +DarkSlateGray2:87:_:Cyan1:51 +DarkSlateGray3:116:_:DarkRed:52 +DarkTurquoise:44:_:DeepPink8:53 +DarkViolet:128:_:Purple4:54 +DarkViolet1:92:_:Purple5:55 +DeepPink1:199:_:Purple3:56 +DeepPink2:197:_:BlueViolet:57 +DeepPink3:198:_:Orange3:58 +DeepPink4:125:_:Grey37:59 +DeepPink6:162:_:MediumPurple6:60 +DeepPink7:89:_:SlateBlue2:61 +DeepPink8:53:_:SlateBlue3:62 +DeepPink9:161:_:RoyalBlue1:63 +DeepSkyBlue1:39:_:Chartreuse6:64 +DeepSkyBlue2:38:_:DarkSeaGreen7:65 +DeepSkyBlue3:31:_:PaleTurquoise4:66 +DeepSkyBlue4:32:_:SteelBlue:67 +DeepSkyBlue5:23:_:SteelBlue3:68 +DeepSkyBlue6:24:_:CornflowerBlue:69 +DeepSkyBlue7:25:_:Chartreuse4:70 +DodgerBlue1:33:_:DarkSeaGreen8:71 +DodgerBlue2:27:_:CadetBlue:72 +DodgerBlue3:26:_:CadetBlue1:73 +Fuchsia:13:_:SkyBlue3:74 +Gold1:220:_:SteelBlue1:75 +Gold2:142:_:Chartreuse5:76 +Gold3:178:_:PaleGreen4:77 +Green:2:_:SeaGreen4:78 +Green1:46:_:Aquamarine3:79 +Green2:34:_:MediumTurquoise:80 +Green3:40:_:SteelBlue2:81 +Green4:28:_:Chartreuse3:82 +GreenYellow:154:_:SeaGreen3:83 +Grey:8:_:SeaGreen1:84 +Grey0:16:_:SeaGreen2:85 +Grey100:231:_:Aquamarine2:86 +Grey11:234:_:DarkSlateGray2:87 +Grey15:235:_:DarkRed2:88 +Grey19:236:_:DeepPink7:89 +Grey23:237:_:DarkMagenta:90 +Grey27:238:_:DarkMagenta1:91 +Grey3:232:_:DarkViolet1:92 +Grey30:239:_:Purple2:93 +Grey35:240:_:Orange4:94 +Grey37:59:_:LightPink3:95 +Grey39:241:_:Plum4:96 +Grey42:242:_:MediumPurple4:97 +Grey46:243:_:MediumPurple5:98 +Grey50:244:_:SlateBlue1:99 +Grey53:102:_:Yellow4:100 +Grey54:245:_:Wheat4:101 +Grey58:246:_:Grey53:102 +Grey62:247:_:LightSlateGrey:103 +Grey63:139:_:MediumPurple:104 +Grey66:248:_:LightSlateBlue:105 +Grey69:145:_:Yellow5:106 +Grey7:233:_:DarkOliveGreen4:107 +Grey70:249:_:DarkSeaGreen:108 +Grey74:250:_:LightSkyBlue2:109 +Grey78:251:_:LightSkyBlue3:110 +Grey82:252:_:SkyBlue2:111 +Grey84:188:_:Chartreuse2:112 +Grey85:253:_:DarkOliveGreen5:113 +Grey89:254:_:PaleGreen3:114 +Grey93:255:_:DarkSeaGreen5:115 +Honeydew2:194:_:DarkSlateGray3:116 +HotPink:205:_:SkyBlue1:117 +HotPink1:206:_:Chartreuse1:118 +HotPink2:169:_:LightGreen:119 +HotPink3:132:_:LightGreen1:120 +HotPink4:168:_:PaleGreen1:121 +IndianRed:131:_:Aquamarine1:122 +IndianRed1:167:_:DarkSlateGray1:123 +IndianRed2:204:_:Red2:124 +IndianRed3:203:_:DeepPink4:125 +Khaki1:228:_:MediumVioletRed:126 +Khaki3:185:_:Magenta4:127 +LightCoral:210:_:DarkViolet:128 +LightCyan2:195:_:Purple:129 +LightCyan3:152:_:DarkOrange2:130 +LightGoldenrod1:227:_:IndianRed:131 +LightGoldenrod2:222:_:HotPink3:132 +LightGoldenrod3:179:_:MediumOrchid3:133 +LightGoldenrod4:221:_:MediumOrchid:134 +LightGoldenrod5:186:_:MediumPurple2:135 +LightGreen:119:_:DarkGoldenrod:136 +LightGreen1:120:_:LightSalmon2:137 +LightPink1:217:_:RosyBrown:138 +LightPink2:174:_:Grey63:139 +LightPink3:95:_:MediumPurple3:140 +LightSalmon1:216:_:MediumPurple1:141 +LightSalmon2:137:_:Gold2:142 +LightSalmon3:173:_:DarkKhaki:143 +LightSeaGreen:37:_:NavajoWhite3:144 +LightSkyBlue1:153:_:Grey69:145 +LightSkyBlue2:109:_:LightSteelBlue3:146 +LightSkyBlue3:110:_:LightSteelBlue:147 +LightSlateBlue:105:_:Yellow6:148 +LightSlateGrey:103:_:DarkOliveGreen6:149 +LightSteelBlue:147:_:DarkSeaGreen6:150 +LightSteelBlue1:189:_:DarkSeaGreen3:151 +LightSteelBlue3:146:_:LightCyan3:152 +LightYellow3:187:_:LightSkyBlue1:153 +Lime:10:_:GreenYellow:154 +Magenta1:201:_:DarkOliveGreen2:155 +Magenta2:165:_:PaleGreen2:156 +Magenta3:200:_:DarkSeaGreen4:157 +Magenta4:127:_:DarkSeaGreen1:158 +Magenta5:163:_:PaleTurquoise1:159 +Magenta6:164:_:Red3:160 +Maroon:1:_:DeepPink9:161 +MediumOrchid:134:_:DeepPink6:162 +MediumOrchid1:171:_:Magenta5:163 +MediumOrchid2:207:_:Magenta6:164 +MediumOrchid3:133:_:Magenta2:165 +MediumPurple:104:_:DarkOrange3:166 +MediumPurple1:141:_:IndianRed1:167 +MediumPurple2:135:_:HotPink4:168 +MediumPurple3:140:_:HotPink2:169 +MediumPurple4:97:_:Orchid:170 +MediumPurple5:98:_:MediumOrchid1:171 +MediumPurple6:60:_:Orange2:172 +MediumSpringGreen:49:_:LightSalmon3:173 +MediumTurquoise:80:_:LightPink2:174 +MediumVioletRed:126:_:Pink3:175 +MistyRose1:224:_:Plum3:176 +MistyRose3:181:_:Violet:177 +NavajoWhite1:223:_:Gold3:178 +NavajoWhite3:144:_:LightGoldenrod3:179 +Navy:4:_:Tan:180 +NavyBlue:17:_:MistyRose3:181 +Olive:3:_:Thistle3:182 +Orange1:214:_:Plum2:183 +Orange2:172:_:Yellow3:184 +Orange3:58:_:Khaki3:185 +Orange4:94:_:LightGoldenrod5:186 +OrangeRed1:202:_:LightYellow3:187 +Orchid:170:_:Grey84:188 +Orchid1:213:_:LightSteelBlue1:189 +Orchid2:212:_:Yellow2:190 +PaleGreen1:121:_:DarkOliveGreen3:191 +PaleGreen2:156:_:DarkOliveGreen1:192 +PaleGreen3:114:_:DarkSeaGreen2:193 +PaleGreen4:77:_:Honeydew2:194 +PaleTurquoise1:159:_:LightCyan2:195 +PaleTurquoise4:66:_:Red1:196 +PaleVioletRed1:211:_:DeepPink2:197 +Pink1:218:_:DeepPink3:198 +Pink3:175:_:DeepPink1:199 +Plum1:219:_:Magenta3:200 +Plum2:183:_:Magenta1:201 +Plum3:176:_:OrangeRed1:202 +Plum4:96:_:IndianRed3:203 +Purple:129:_:IndianRed2:204 +Purple1:5:_:HotPink:205 +Purple2:93:_:HotPink1:206 +Purple3:56:_:MediumOrchid2:207 +Purple4:54:_:DarkOrange:208 +Purple5:55:_:Salmon1:209 +Red:9:_:LightCoral:210 +Red1:196:_:PaleVioletRed1:211 +Red2:124:_:Orchid2:212 +Red3:160:_:Orchid1:213 +RosyBrown:138:_:Orange1:214 +RoyalBlue1:63:_:SandyBrown:215 +Salmon1:209:_:LightSalmon1:216 +SandyBrown:215:_:LightPink1:217 +SeaGreen1:84:_:Pink1:218 +SeaGreen2:85:_:Plum1:219 +SeaGreen3:83:_:Gold1:220 +SeaGreen4:78:_:LightGoldenrod4:221 +Silver:7:_:LightGoldenrod2:222 +SkyBlue1:117:_:NavajoWhite1:223 +SkyBlue2:111:_:MistyRose1:224 +SkyBlue3:74:_:Thistle1:225 +SlateBlue1:99:_:Yellow1:226 +SlateBlue2:61:_:LightGoldenrod1:227 +SlateBlue3:62:_:Khaki1:228 +SpringGreen1:48:_:Wheat1:229 +SpringGreen2:42:_:Cornsilk1:230 +SpringGreen3:47:_:Grey100:231 +SpringGreen4:35:_:Grey3:232 +SpringGreen5:41:_:Grey7:233 +SpringGreen6:29:_:Grey11:234 +SteelBlue:67:_:Grey15:235 +SteelBlue1:75:_:Grey19:236 +SteelBlue2:81:_:Grey23:237 +SteelBlue3:68:_:Grey27:238 +Tan:180:_:Grey30:239 +Teal:6:_:Grey35:240 +Thistle1:225:_:Grey39:241 +Thistle3:182:_:Grey42:242 +Turquoise2:45:_:Grey46:243 +Turquoise4:30:_:Grey50:244 +Violet:177:_:Grey54:245 +Wheat1:229:_:Grey58:246 +Wheat4:101:_:Grey62:247 +White:15:_:Grey66:248 +Yellow:11:_:Grey70:249 +Yellow1:226:_:Grey74:250 +Yellow2:190:_:Grey78:251 +Yellow3:184:_:Grey82:252 +Yellow4:100:_:Grey85:253 +Yellow5:106:_:Grey89:254 +Yellow6:148:_:Grey93:255 +.TE +.Sh SEE ALSO +.Xr meli 1 , +.Xr meli.conf 5 +.Sh CONFORMING TO +TOML Standard v.0.5.0 https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md +.Sh AUTHORS +Copyright 2017-2019 +.An Manos Pitsidianakis Aq epilys@nessuent.xyz +Released under the GPL, version 3 or greater. +This software carries no warranty of any kind. +(See COPYING for full copyright and warranty notices.) +.Pp +.Aq https://meli.delivery diff --git a/meli.1 b/meli.1 index bf113a3fd..ba7f5bd48 100644 --- a/meli.1 +++ b/meli.1 @@ -30,6 +30,8 @@ .Op Fl -create-config Op Ar path .Op Fl -test-config Op Ar path .Op Fl -config Ar path +.Op Fl -print-default-theme +.Op Fl -print-loaded-themes .Sh DESCRIPTION Experimental terminal mail client .Bl -tag -width flag -offset indent @@ -41,11 +43,15 @@ Show version and exit. Create configuration file in .Pa path if given, or at -.Pa $XDG_CONFIG_HOME/meli/config +.Pa $XDG_CONFIG_HOME/meli/config.toml .It Fl -test-config Op Ar path Test a configuration file for syntax issues or missing options. .It Fl -config Ar path Start meli with given configuration file. +.It Fl -print-default-theme +Print default theme keys and values in TOML syntax, to be used as a blueprint. +.It Fl -print-loaded-themes +Print all loaded themes in TOML syntax. .El .Sh STARTING WITH meli When launched for the first time, @@ -53,7 +59,7 @@ When launched for the first time, will search for its configuration directory, .Pa $XDG_CONFIG_HOME/meli/ Ns \&. If it doesn't exist, you will be asked if you want to create one along with a sample configuration. The sample configuration -.Pa $XDG_CONFIG_HOME/meli/config +.Pa $XDG_CONFIG_HOME/meli/config.toml includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away. See .Xr meli.conf 5 for the available configuration options. @@ -423,7 +429,7 @@ and appropriates the following locations: .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent .It Pa $XDG_CONFIG_HOME/meli/ User configuration directory. -.It Pa $XDG_CONFIG_HOME/meli/config +.It Pa $XDG_CONFIG_HOME/meli/config.toml User configuration file. See .Xr meli.conf 5 for its syntax and values. @@ -461,6 +467,7 @@ Mailcap entries are searched for in the following files, in this order: .El .Sh SEE ALSO .Xr meli.conf 5 , +.Xr meli-themes 5 , .Xr xdg-open 1 , .Xr mailcap 5 .Sh CONFORMING TO diff --git a/meli.conf.5 b/meli.conf.5 index 58c833b20..a920486ec 100644 --- a/meli.conf.5 +++ b/meli.conf.5 @@ -24,7 +24,7 @@ .Nm meli.conf .Nd configuration file for the Meli Mail User Agent .Sh SYNOPSIS -.Pa $XDG_CONFIG_HOME/meli/config +.Pa $XDG_CONFIG_HOME/meli/config.toml .Sh DESCRIPTION Configuration for meli is written in TOML. Few things to consider before writing TOML (quoting the spec): .Pp @@ -607,7 +607,7 @@ example configuration: # valid inputs: #HHHHHH, #ABC -> #AABBCC, XTERM_NAME, 0-255 byte colors = { signed="#Ff6600", replied="DeepSkyBlue4", draft="#f00", replied="8" } [accounts.dummy] -#...8<-- +\&... [accounts.dummy.folders] # per folder override: "INBOX" = { tags.ignore_tags=["inbox", ] } @@ -641,13 +641,35 @@ auto verify signed e-mail according to RFC3156 (optional) if true, box drawing will be done with ascii characters. .\" default value .Pq Em false +.It Ic use_color Ar boolean +(optional) if false, no ANSI colors are used +.\" default value +.Pq Em true .It Ic window_title Ar String (optional) set window title in xterm compatible terminals (empty string means no window title is set) .\" default value .Pq Em "meli" +.It Ic themes Ar hash table String[String[Attribute]] +define UI themes. See +.Xr meli-themes 5 +for details. +.Bd -literal +[terminal] +theme = "themeB" + +[terminal.themes.themeA] +"mail.view.body" = {fg = "HotPink3", bg = "LightSalmon1"} +\&... +[terminal.themes.themeB] +"mail.view.body" = {fg = "CadetBlue", bg = "White"} +\&... +[terminal.themes.themeC] +\&... +.Ed .El .Sh SEE ALSO -.Xr meli 1 +.Xr meli 1 , +.Xr meli-themes 5 .Sh CONFORMING TO TOML Standard v.0.5.0 https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md .Sh AUTHORS