update documentation

Endless gratitude to WanderingBeekeper for editing the text.
master
Manos Pitsidianakis 2020-07-15 20:20:37 +03:00
parent 587eaf7215
commit 15b15854bf
Signed by: Manos Pitsidianakis
GPG Key ID: 73627C2F690DF710
4 changed files with 381 additions and 304 deletions

View File

@ -23,7 +23,7 @@ The Makefile *should* be portable and not require a specific `make` version.
# Documentation # Documentation
After installing meli, see `meli(1)` and `meli.conf(5)` for documentation. After installing meli, see `meli(1)` and `meli.conf(5)` for documentation. Sample configuration and theme files can be found in the `samples/` subdirectory.
# Building # Building

View File

@ -29,10 +29,10 @@ mail client
.Nm meli .Nm meli
comes with two themes, comes with two themes,
.Ic dark .Ic dark
(the default) and (default) and
.Ic light . .Ic light .
.sp .sp
Custom themes can be defined as lists of key-values in the configuration files: Custom themes are defined as lists of key-values in the configuration files:
.Bl -bullet -compact .Bl -bullet -compact
.It .It
.Pa $XDG_CONFIG_HOME/meli/config.toml .Pa $XDG_CONFIG_HOME/meli/config.toml
@ -48,15 +48,18 @@ theme = "dark"
.Sh DESCRIPTION .Sh DESCRIPTION
Themes for Themes for
.Nm meli .Nm meli
are described in the configuration language TOML. are described in the configuration language TOML, as they are key-value tables defined in the TERMINAL section of the configuration file.
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. 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. For example,
.Ic mail.listing.compact.*
keys are settings for the
.Ic compact
mail listing style.
A setting contains three fields: fg for foreground color, bg for background color, and attrs for text attribute. A setting contains three fields: fg for foreground color, bg for background color, and attrs for text attribute.
.sp .sp
.Dl \&"widget.key.label\&" = { fg = \&"Default\&", bg = \&"Default\&", attrs = \&"Default\&" } .Dl \&"widget.key.label\&" = { fg = \&"Default\&", bg = \&"Default\&", attrs = \&"Default\&" }
.sp .sp
Each field contains a value, and each value can either be a color/attribute, a link (key name) or a valid alias. Each field contains a value, which may be either a color/attribute, a link (key name) or a valid alias.
An alias is a string starting with the \&"\&$\&" character and must be declared in advance in the An alias is a string starting with the \&"\&$\&" character and must be declared in advance in the
.Ic color_aliases .Ic color_aliases
or or
@ -134,8 +137,8 @@ Color values are of type String with the following valid contents:
.It .It
"Default" is the terminal default. (Case-sensitive) "Default" is the terminal default. (Case-sensitive)
.It .It
Hex triplet eg #FFFFFF for RGB colors Hex triplet e.g. #FFFFFF for RGB colors.
(three letter shorthand also valid, eg #09c → #0099cc) (Case-insensitive) Three character shorthand is also valid, e.g. #09c → #0099cc (Case-insensitive)
.It .It
0-255 byte for 256 colors. 0-255 byte for 256 colors.
.It .It
@ -162,7 +165,7 @@ is explicitly set to true by the user,
is ignored. is ignored.
.El .El
.sp .sp
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. In this mode, cursor locations (i.e., currently selected entries/items) will use the "reverse video" ANSI attribute to invert the terminal's default foreground/background colors.
.Sh VALID KEYS .Sh VALID KEYS
.Bl -bullet -compact .Bl -bullet -compact
.It .It

363
meli.1
View File

@ -55,19 +55,19 @@ View mail from input file.
.Nm .Nm
is a terminal mail client aiming for extensive and user-frendly configurability. is a terminal mail client aiming for extensive and user-frendly configurability.
.Bd -literal .Bd -literal
^^ .-=-=-=-. ^^ ^^ .-=-=-=-. ^^
^^ (`-=-=-=-=-`) ^^ ^^ (`-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-`) ^^ ^^ (`-=-=-=-=-=-=-`) ^^ ^^
^^ (`-=-=-=-=-=-=-=-`) ^^ ^^ (`-=-=-=-=-=-=-=-`) ^^
( `-=-=-=-(@)-=-=-` ) ^^ ( `-=-=-=-(@)-=-=-` ) ^^
(`-=-=-=-=-=-=-=-=-`) ^^ (`-=-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-=-=-`) ^^ (`-=-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-=-=-`) (`-=-=-=-=-=-=-=-=-`)
^^ (`-=-=-=-=-=-=-=-=-`) ^^ ^^ (`-=-=-=-=-=-=-=-=-`) ^^
^^ (`-=-=-=-=-=-=-=-`) ^^ ^^ (`-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-`) ^^ (`-=-=-=-=-=-=-`) ^^
^^ (`-=-=-=-=-`) ^^ (`-=-=-=-=-`)
`-=-=-=-=-` ^^ `-=-=-=-=-` ^^
.Ed .Ed
.Sh STARTING WITH meli .Sh STARTING WITH meli
When launched for the first time, When launched for the first time,
@ -75,29 +75,27 @@ When launched for the first time,
will search for its configuration directory, will search for its configuration directory,
.Pa $XDG_CONFIG_HOME/meli/ Ns .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. If it doesn't exist, you will be asked if you want to create one and presented with a sample configuration file
The sample configuration .Pq Pa $XDG_CONFIG_HOME/meli/config.toml
.Pa $XDG_CONFIG_HOME/meli/config.toml that includes the basic settings required for setting up accounts allowing you to copy and edit right away.
includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away.
See See
.Xr meli.conf 5 .Xr meli.conf 5
for the available configuration options. for the available configuration options.
.Pp .Pp
At any time, you may press At any time, you may press
.Cm \&? .Cm \&?
to show a searchable list of all available actions and shortcuts, along with every possible setting and command that your version supports. for a searchable list of all available actions and shortcuts, along with every possible setting and command that your version supports.
.Pp .Pp
The main visual navigation tool is the left-side sidebar. The main visual navigation tool, the left-side sidebar may be toggled with
The menu's visibility may be toggled with
.Cm ` .Cm `
(shortcuts.listing: (shortcuts.listing:
.Ic toggle_menu_visibility Ns .Ic toggle_menu_visibility Ns
). ).
.Pp .Pp
The view into each mailbox has 4 modes: plain, threaded, conversations and compact. Each mailbox may be viewed in 4 modes:
Plain views each mail indvidually, threaded shows their thread relationship visually, and conversations includes one entry per thread of emails (compact is one row per thread). Plain views each mail individually, Threaded shows their thread relationship visually, Conversations collapses each thread of emails into a single entry, Compact shows one row per thread.
.Pp .Pp
If you're using a light color palette in your terminal, you may set If you're using a light color palette in your terminal, you should set
.Em theme = "light" .Em theme = "light"
in the in the
.Em terminal .Em terminal
@ -107,14 +105,21 @@ See
for complete documentation on user themes. for complete documentation on user themes.
.Sh VIEWING MAIL .Sh VIEWING MAIL
Open attachments by typing their index in the attachments list and then Open attachments by typing their index in the attachments list and then
.Cm a Ns .Cm a
\&. .Po
shortcut
.Ic open_attachment
.Pc .
.Nm .Nm
will attempt to open text inside its pager and other content via will attempt to open text inside its pager, and other content via
.Cm xdg-open Ns .Cm xdg-open Ns
\&. \&.
Press Press
.Cm m .Cm m
.Po
shortcut
.Ic open_mailcap
.Pc
instead to use the mailcap entry for the MIME type of the attachment, if any. instead to use the mailcap entry for the MIME type of the attachment, if any.
See See
.Sx FILES .Sx FILES
@ -122,6 +127,8 @@ for the location of the mailcap files and
.Xr mailcap 5 .Xr mailcap 5
for their syntax. for their syntax.
You can save individual attachments with the You can save individual attachments with the
.Em EXECUTE
command
.Cm save-attachment Ar INDEX Ar path-to-file .Cm save-attachment Ar INDEX Ar path-to-file
where where
.Ar INDEX .Ar INDEX
@ -129,18 +136,27 @@ is the attachment's index in the listing.
If the zeroth index is provided, the entire message is saved. If the zeroth index is provided, the entire message is saved.
If the path provided is a directory, the message is saved as an eml file with its filename set to the messages message-id. If the path provided is a directory, the message is saved as an eml file with its filename set to the messages message-id.
.Sh SEARCH .Sh SEARCH
Each e-mail storage backend has its default search method. Each e-mail storage backend has a default search method assigned.
.Em IMAP .Em IMAP
uses the SEARCH command, uses the SEARCH command,
.Em notmuch .Em notmuch
uses libnotmuch and uses libnotmuch and
.Em Maildir/mbox .Em Maildir/mbox
have to do a slow linear search. performs a slow linear search.
Thus it is advised to use a cache on It is advised to use a cache on
.Em Maildir/mbox .Em Maildir/mbox
accounts. accounts.
.Nm Ns .Nm Ns
, if built with sqlite3, includes the ability to perform full text search on the following fields: From, To, Cc, Bcc, In-Reply-To, References, Subject and Date. , if built with sqlite3, includes the ability to perform full text search on the following fields:
.Em From ,
.Em To ,
.Em Cc ,
.Em Bcc ,
.Em In-Reply-To ,
.Em References ,
.Em Subject
and
.Em Date .
The message body (in plain text human readable form) and the flags can also be queried. The message body (in plain text human readable form) and the flags can also be queried.
To enable sqlite3 indexing for an account set To enable sqlite3 indexing for an account set
.Em cache_type .Em cache_type
@ -182,6 +198,37 @@ to
will relay your queries to the IMAP server. will relay your queries to the IMAP server.
Expect a delay between query and response. Expect a delay between query and response.
Sqlite3 on the contrary at reasonable mailbox sizes should have a non noticable delay. Sqlite3 on the contrary at reasonable mailbox sizes should have a non noticable delay.
.Ss QUERY ABNF SYNTAX
.Bl -bullet
.It
.Li query = \&"(\&" query \&")\&" | from | to | cc | bcc | alladdresses | subject | flags | has_attachments | query \&"or\&" query | query \&"and\&" query | not query
.It
.Li not = \&"not\&" | \&"!\&"
.It
.Li quoted = ALPHA / SP *(ALPHA / DIGIT / SP)
.It
.Li term = ALPHA *(ALPHA / DIGIT) | DQUOTE quoted DQUOTE
.It
.Li tagname = term
.It
.Li flagval = \&"passed\&" | \&"replied\&" | \&"seen\&" | \&"read\&" | \&"junk\&" | \&"trash\&" | \&"trashed\&" | \&"draft\&" | \&"flagged\&" | tagname
.It
.Li flagterm = flagval | flagval \&",\&" flagterm
.It
.Li from = \&"from:\&" term
.It
.Li to = \&"to:\&" term
.It
.Li cc = \&"cc:\&" term
.It
.Li bcc = \&"bcc:\&" term
.It
.Li alladdresses = \&"alladdresses:\&" term
.It
.Li subject = \&"subject:\&" term
.It
.Li flags = \&"flags:\&" flag | \&"tags:\&" flag | \&"is:\&" flag
.El
.Sh TAGS .Sh TAGS
.Nm .Nm
supports tagging in notmuch and IMAP/JMAP backends. supports tagging in notmuch and IMAP/JMAP backends.
@ -197,54 +244,40 @@ and
.Ic ignore_tags .Ic ignore_tags
for how to set tag colors and tag visiblity) for how to set tag colors and tag visiblity)
.Sh COMPOSING .Sh COMPOSING
To send mail, press .Ss Opening the message Composer tab
To create a new mail message, press
.Cm m .Cm m
while viewing the appropriate account to open a new composing tab. (shortcut
.Ic new_mail Ns
) while viewing a mailbox.
To reply to a mail, press To reply to a mail, press
.Cm R Ns .Cm R
\&. .Po
You may edit some of the header fields from within the view, by selecting with the arrow keys and pressing shortcut
.Ic reply
.Pc .
Both these actions open the mail composer view in a new tab.
.Ss Editing text
.Bl -bullet -compact
.It
Edit the header fields by selecting with the arrow keys and pressing
.Cm enter .Cm enter
to enter to enter
.Ar INSERT .Em INSERT
mode. mode and
.Cm Esc
key to exit.
.It
At any time you may press At any time you may press
.Cm e .Cm e
to launch your editor (see (shortcut
.Ic edit_mail Ns
) to launch your editor (see
.Xr meli.conf 5 COMPOSING Ns .Xr meli.conf 5 COMPOSING Ns
, setting , setting
.Ic editor_command .Ic editor_command
for how to select which editor to launch). for how to select which editor to launch).
Attachments may be handled with the .It
.Em add-attachment Ns
,
.Em remove-attachment
commands (see below).
Finally, pressing
.Cm s
will send your message according to your settings
.Po
see
.Xr meli.conf 5 COMPOSING Ns
, setting
.Ic send_mail
.Pc Ns
\&.
To save your draft without sending it, issue command
.Cm close
and select 'save as draft'.
.Pp
With no Draft or Sent mailbox,
.Nm
tries first saving mail in your INBOX and then at any other mailbox.
On complete failure to save your draft or sent message it will be saved in your
.Em tmp
directory instead and you will be notified of its location.
.Pp
To open a draft for editing later, select your draft in the mail listing and press
.Cm e Ns
\&.
.sp
Your editor can be used in Your editor can be used in
.Nm Ns .Nm Ns
\&'s embed terminal emulator by setting \&'s embed terminal emulator by setting
@ -252,14 +285,54 @@ Your editor can be used in
to to
.Em true .Em true
in your composing settings. in your composing settings.
.It
When launched, your editor captures all input until it exits or stops. When launched, your editor captures all input until it exits or stops.
.It
To stop your editor and return to To stop your editor and return to
.Nm .Nm
issue Ctrl-z and to resume editing press the press Ctrl-z and to resume editing press the
.Ic edit_mail .Ic edit_mail
command again (default command again
.Em e Ns .Po
). default
.Em e
.Pc .
.El
.Ss Attachments
Attachments may be handled with the
.Cm add-attachment Ns
,
.Cm remove-attachment
commands (see below).
.Ss Sending
Finally, pressing
.Cm s
(shortcut
.Ic send_mail Ns
) will send your message according to your settings
.Po
see
.Xr meli.conf 5 COMPOSING Ns
, setting
.Ic send_mail
.Pc Ns
\&.
With no Draft or Sent mailbox,
.Nm
tries first saving mail in your INBOX and then at any other mailbox.
On complete failure to save your draft or sent message it will be saved in your
.Em tmp
directory instead and you will be notified of its location.
.Ss Drafts
To save your draft without sending it, issue
.Em EXECUTE
command
.Cm close
and select 'save as draft'.
.sp
To open a draft for further editing, select your draft in the mail listing and press
.Ic edit_mail Ns
\&.
.Sh CONTACTS .Sh CONTACTS
.Nm .Nm
supports two kinds of contact backends: supports two kinds of contact backends:
@ -282,10 +355,25 @@ They are loaded read only.
See See
.Xr meli.conf 5 ACCOUNTS .Xr meli.conf 5 ACCOUNTS
for the complete account configuration values. for the complete account configuration values.
.Sh EXECUTE mode .Sh MODES
Commands are issued in EXECUTE mode, by default started with Space and exited with Escape key. .Bl -tag -compact -width 8n
.Pp .It NORMAL
the following commands are valid in the mail listing context: is the default mode
.It EXECUTE
commands are issued in
.Em EXECUTE
mode, by default started with Space and exited with
.Cm Esc
key.
.It EMBED
is the mode of the embed terminal emulator
.It INSERT
captures all input as text input, and is exited with
.Cm Esc
key.
.El
.Ss EXECUTE Mode
.Ss Mail listing commands
.Bl -tag -width 36n .Bl -tag -width 36n
.It Cm set Ar plain | threaded | compact | conversations .It Cm set Ar plain | threaded | compact | conversations
set the way mailboxes are displayed set the way mailboxes are displayed
@ -317,6 +405,7 @@ search mailbox with
key. key.
Escape exits search results Escape exits search results
.It Cm set read, set unread .It Cm set read, set unread
Set read status of message.
.It Cm create-mailbox Ar ACCOUNT Ar MAILBOX_PATH .It Cm create-mailbox Ar ACCOUNT Ar MAILBOX_PATH
create mailbox with given path. create mailbox with given path.
Be careful with backends and separator sensitivity (eg IMAP) Be careful with backends and separator sensitivity (eg IMAP)
@ -327,10 +416,10 @@ unsubscribe to mailbox with given path
.It Cm rename-mailbox Ar ACCOUNT Ar MAILBOX_PATH_SRC Ar MAILBOX_PATH_DEST .It Cm rename-mailbox Ar ACCOUNT Ar MAILBOX_PATH_SRC Ar MAILBOX_PATH_DEST
rename mailbox rename mailbox
.It Cm delete-mailbox Ar ACCOUNT Ar MAILBOX_PATH .It Cm delete-mailbox Ar ACCOUNT Ar MAILBOX_PATH
delete mailbox deletes mailbox in the mail backend.
This action is unreversible.
.El .El
.Pp .Ss Mail view commands
envelope view commands:
.Bl -tag -width 36n .Bl -tag -width 36n
.It Cm pipe Ar EXECUTABLE Ar ARGS .It Cm pipe Ar EXECUTABLE Ar ARGS
pipe pager contents to binary pipe pager contents to binary
@ -342,8 +431,7 @@ unsubscribe automatically from list of viewed envelope
open list archive with open list archive with
.Cm xdg-open .Cm xdg-open
.El .El
.Pp .Ss composing mail commands
composing mail commands:
.Bl -tag -width 36n .Bl -tag -width 36n
.It Cm add-attachment Ar PATH .It Cm add-attachment Ar PATH
in composer, add in composer, add
@ -358,11 +446,13 @@ remove attachment with given index
.It Cm toggle sign .It Cm toggle sign
toggle between signing and not signing this message. toggle between signing and not signing this message.
If the gpg invocation fails then the mail won't be sent. If the gpg invocation fails then the mail won't be sent.
See
.Xr meli.conf 5 PGP
for PGP configuration.
.It Cm save-draft .It Cm save-draft
saves a copy of the draft in the Draft folder saves a copy of the draft in the Draft folder
.El .El
.Pp .Ss generic commands
generic commands:
.Bl -tag -width 36n .Bl -tag -width 36n
.It Cm open-in-tab .It Cm open-in-tab
opens envelope view in new tab opens envelope view in new tab
@ -378,108 +468,18 @@ print environment variable
.Ar KEY .Ar KEY
.El .El
.Sh SHORTCUTS .Sh SHORTCUTS
Non-complete list of shortcuts and their default values. See
.Bl -tag -width 36n .Xr meli.conf 5 SHORTCUTS
.It Ic open_thread for shortcuts and their default values.
\&'\\n'
.It Ic exit_thread
\&'i'
.It Ic create_contact
\&'c'
.It Ic edit_contact
\&'e'
.It Ic prev_page
PageUp,
.It Ic next_page
PageDown
.It Ic prev_mailbox
\&'K'
.It Ic next_mailbox
\&'J'
.It Ic prev_account
\&'l'
.It Ic next_account
\&'h'
.It Ic new_mail
\&'m'
.It Ic scroll_up
\&'k'
.It Ic scroll_down
\&'j'
.It Ic page_up
PageUp
.It Ic page_down
PageDown
.It Ic toggle-menu-visibility
\&'`'
.It Ic select
\&'v'
.It Ic `
toggles hiding of sidebar in mail listings
.It Ic \&?
opens up a shortcut window that shows available actions in the current component you are using (eg mail listing, contact list, mail composing)
.It Ic m
starts a new mail composer
.It Ic R
replies to the viewed mail.
.It Ic u
displays numbers next to urls in the body text of an email and
.Ar n Ns Ic g
opens the
.Ar n Ns
th
url with xdg-open
.It Ar n Ns Ic a
opens the
.Ar n Ns
th
attachment.
.It Ar n Ns Ic m
opens the
.Ar n Ns
th
attachment according to its mailcap entry.
.It Ic v
(un)selects mail entries in mail listings
.El
.Sh QUERY ABNF SYNTAX
.Bl -bullet
.It
.Li query = \&"(\&" query \&")\&" | from | to | cc | bcc | alladdresses | subject | flags | has_attachments | query \&"or\&" query | query \&"and\&" query | not query
.It
.Li not = \&"not\&" | \&"!\&"
.It
.Li quoted = ALPHA / SP *(ALPHA / DIGIT / SP)
.It
.Li term = ALPHA *(ALPHA / DIGIT) | DQUOTE quoted DQUOTE
.It
.Li tagname = term
.It
.Li flagval = \&"passed\&" | \&"replied\&" | \&"seen\&" | \&"read\&" | \&"junk\&" | \&"trash\&" | \&"trashed\&" | \&"draft\&" | \&"flagged\&" | tagname
.It
.Li flagterm = flagval | flagval \&",\&" flagterm
.It
.Li from = \&"from:\&" term
.It
.Li to = \&"to:\&" term
.It
.Li cc = \&"cc:\&" term
.It
.Li bcc = \&"bcc:\&" term
.It
.Li alladdresses = \&"alladdresses:\&" term
.It
.Li subject = \&"subject:\&" term
.It
.Li flags = \&"flags:\&" flag | \&"tags:\&" flag | \&"is:\&" flag
.El
.Sh EXIT STATUS .Sh EXIT STATUS
.Nm .Nm
exits with 0 on a successful run. exits with 0 on a successful run.
Other exit statuses are: Other exit statuses are:
.Bl -tag -width 2n .Bl -tag -width 5n
.It 1 .It 1
catchall for general errors catchall for general errors
.It 101
process panic
.El .El
.Sh ENVIRONMENT .Sh ENVIRONMENT
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
@ -508,10 +508,9 @@ defaults to
and appropriates the following locations: and appropriates the following locations:
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
.It Pa $XDG_CONFIG_HOME/meli/ .It Pa $XDG_CONFIG_HOME/meli/
User configuration directory. User configuration directory
.It Pa $XDG_CONFIG_HOME/meli/config.toml .It Pa $XDG_CONFIG_HOME/meli/config.toml
User configuration file. User configuration file, see
See
.Xr meli.conf 5 .Xr meli.conf 5
for its syntax and values. for its syntax and values.
.It Pa $XDG_CONFIG_HOME/meli/hooks/* .It Pa $XDG_CONFIG_HOME/meli/hooks/*

View File

@ -26,8 +26,7 @@
.Sh SYNOPSIS .Sh SYNOPSIS
.Pa $XDG_CONFIG_HOME/meli/config.toml .Pa $XDG_CONFIG_HOME/meli/config.toml
.Sh DESCRIPTION .Sh DESCRIPTION
Configuration for meli is written in TOML. Configuration for meli is written in TOML which has a few things to consider (quoting the spec):
Few things to consider before writing TOML (quoting the spec):
.Pp .Pp
.Bl -bullet -compact .Bl -bullet -compact
.It .It
@ -123,24 +122,24 @@ set_seen = 'n'
theme = "light" theme = "light"
.Ed .Ed
.Pp .Pp
available options are listed below. Available options are listed below.
.Sy default values are shown in parentheses. Default values are shown in parentheses.
.Sh ACCOUNTS .Sh ACCOUNTS
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic root_mailbox Ar String .It Ic root_mailbox Ar String
the backend-specific path of the root_mailbox, usually INBOX. The backend-specific path of the root_mailbox, usually INBOX.
.It Ic format Ar String Op maildir mbox imap notmuch jmap .It Ic format Ar String Op maildir mbox imap notmuch jmap
the format of the mail backend. The format of the mail backend.
.It Ic subscribed_mailboxes Ar [String,] .It Ic subscribed_mailboxes Ar [String,]
an array of mailbox paths to display in the UI. An array of mailbox paths to display in the UI.
Paths are relative to the root mailbox (eg "INBOX/Sent", not "Sent"). Paths are relative to the root mailbox (eg "INBOX/Sent", not "Sent").
The glob wildcard The glob wildcard
.Em \&* .Em \&*
can be used to match every mailbox name and path. can be used to match every mailbox name and path.
.It Ic identity Ar String .It Ic identity Ar String
your e-mail address that is inserted in the From: headers of outgoing mail Your e-mail address that is inserted in the From: headers of outgoing mail.
.It Ic index_style Ar String .It Ic index_style Ar String
set the way mailboxes are displayed Sets the way mailboxes are displayed.
.El .El
.TS .TS
allbox tab(:); allbox tab(:);
@ -152,26 +151,31 @@ plain:shows one row per mail, regardless of threading
.TE .TE
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic display_name Ar String .It Ic display_name Ar String
(optional) a name which can be combined with your address: .Pq Em optional
"Name <email@address.tld>" A name which can be combined with your address: "Name <email@address.tld>".
.It Ic read_only Ar boolean .It Ic read_only Ar boolean
attempt to not make any changes to this account. Attempt to not make any changes to this account.
.Pq Em false .Pq Em false
.It Ic manual_refresh Ar boolean .It Ic manual_refresh Ar boolean
(optional) if true, do not monitor account for changes (you can use shortcut listing.refresh) .Pq Em optional
If true, do not monitor account for changes (you can use shortcut listing.refresh)
.Pq Em false .Pq Em false
.It Ic refresh_command Ar String .It Ic refresh_command Ar String
(optional) command to execute when manually refreshing (shortcut listing.refresh) .Pq Em optional
command to execute when manually refreshing (shortcut listing.refresh)
.Pq Em None .Pq Em None
.It Ic cache_type Ar String .It Ic cache_type Ar String
(optional) choose which cache backend to use. .Pq Em optional
Choose which cache backend to use.
Available options are 'none' and 'sqlite3' Available options are 'none' and 'sqlite3'
.Pq Em "sqlite3" .Pq Em "sqlite3"
.It Ic vcard_folder Ar String .It Ic vcard_folder Ar String
(optional) Folder that contains .vcf files. .Pq Em optional
Folder that contains .vcf files.
They are parsed and imported read-only. They are parsed and imported read-only.
.It Ic mailboxes Ar mailbox .It Ic mailboxes Ar mailbox
(optional) configuration for each mailbox. .Pq Em optional
Configuration for each mailbox.
Its format is described below in Its format is described below in
.Sx mailboxes Ns .Sx mailboxes Ns
\&. \&.
@ -182,7 +186,7 @@ points to the directory which contains the
.Pa .notmuch/ .Pa .notmuch/
subdirectory. subdirectory.
notmuch mailboxes are virtual, since they are defined by user-given notmuch queries. notmuch mailboxes are virtual, since they are defined by user-given notmuch queries.
Thus you have to explicitly state the mailboxes you want in the You must explicitly state the mailboxes you want in the
.Ic mailboxes .Ic mailboxes
field and set the field and set the
.Ar query .Ar query
@ -204,46 +208,59 @@ IMAP specific options are:
example: example:
.Qq mail.example.tld .Qq mail.example.tld
.It Ic server_username Ar String .It Ic server_username Ar String
Server username
.It Ic server_password Ar String .It Ic server_password Ar String
Server password
.It Ic server_password_command Ar String .It Ic server_password_command Ar String
(optional) Use instead of .Pq Em optional
Use instead of
.Ic server_password .Ic server_password
.It Ic server_port Ar number .It Ic server_port Ar number
(optional) .Pq Em optional
The port to connect to
.\" default value .\" default value
.Pq Em 143 .Pq Em 143
.It Ic use_starttls Ar boolean .It Ic use_starttls Ar boolean
(optional) if port is 993 and use_starttls is unspecified, it becomes false by default. .Pq Em optional
If port is 993 and use_starttls is unspecified, it becomes false by default.
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic danger_accept_invalid_certs Ar boolean .It Ic danger_accept_invalid_certs Ar boolean
(optional) do not validate TLS certificates. .Pq Em optional
Do not validate TLS certificates.
.\" default value .\" default value
.Pq Em false .Pq Em false
.El .El
.Ss JMAP only .Ss JMAP only
JMAP specific options are: JMAP specific options
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic server_hostname Ar String .It Ic server_hostname Ar String
example: example:
.Qq mail.example.tld .Qq mail.example.tld
.It Ic server_username Ar String .It Ic server_username Ar String
Server username
.It Ic server_password Ar String .It Ic server_password Ar String
Server password
.It Ic server_port Ar number .It Ic server_port Ar number
(optional) .Pq Em optional
The port to connect to
.\" default value .\" default value
.Pq Em 443 .Pq Em 443
.It Ic danger_accept_invalid_certs Ar boolean .It Ic danger_accept_invalid_certs Ar boolean
(optional) do not validate TLS certificates. .Pq Em optional
Do not validate TLS certificates.
.\" default value .\" default value
.Pq Em false .Pq Em false
.El .El
.Ss mbox only .Ss mbox only
mbox specific options are: mbox specific options
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic prefer_mbox_type Ar String .It Ic prefer_mbox_type Ar String
(optional) prefer specific mbox format reader for each message. Default is mboxcl2 format. If the preferred format fails, the message is retried with mboxrd and then if it fails again there's a recover attempt, which discards the invalid message. .Pq Em optional
Valid values are: Prefer specific mbox format reader for each message.
Default is mboxcl2 format.
If the preferred format fails, the message is retried with mboxrd and then if it fails again there's a recover attempt, which discards the invalid message.
Valid values
.Bl -bullet -compact .Bl -bullet -compact
.It .It
.Ar auto .Ar auto
@ -259,7 +276,7 @@ Valid values are:
.\" default value .\" default value
.Pq Em auto .Pq Em auto
.El .El
to set multiple mailboxes, you have to explicitly state the mailboxes you want in the To set multiple mailboxes, you have to explicitly state the mailboxes you want in the
.Ic mailboxes .Ic mailboxes
field and set the field and set the
.Ar path .Ar path
@ -270,28 +287,34 @@ Example:
format = "mbox" format = "mbox"
mailboxes."Python mailing list" = { path = "~/.mail/python.mbox", subscribe = true, autoload = true } mailboxes."Python mailing list" = { path = "~/.mail/python.mbox", subscribe = true, autoload = true }
.Ed .Ed
.Sh mailboxes .Ss MAILBOXES
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic alias Ar String .It Ic alias Ar String
(optional) show a different name for this mailbox in the UI .Pq Em optional
Show a different name for this mailbox in the UI
.It Ic autoload Ar boolean .It Ic autoload Ar boolean
(optional) load this mailbox on startup .Pq Em optional
Load this mailbox on startup
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic subscribe Ar boolean .It Ic subscribe Ar boolean
(optional) watch this mailbox for updates .Pq Em optional
Watch this mailbox for updates
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic ignore Ar boolean .It Ic ignore Ar boolean
(optional) silently insert updates for this mailbox, if any .Pq Em optional
Silently insert updates for this mailbox, if any
.\" default value .\" default value
.Pq Em false .Pq Em false
.It Ic usage Ar boolean .It Ic usage Ar boolean
(optional) special usage of this mailbox. .Pq Em optional
special usage of this mailbox.
Valid values are: Valid values are:
.Bl -bullet -compact .Bl -bullet -compact
.It .It
.Ar Normal .Ar Normal
.Pq Em default
.It .It
.Ar Inbox .Ar Inbox
.It .It
@ -308,12 +331,16 @@ Valid values are:
.Ar Trash .Ar Trash
.El .El
otherwise usage is inferred from the mailbox title. otherwise usage is inferred from the mailbox title.
If for example your Sent folder is not named "Sent", you must explicitly set it.
.It Ic conf_override Ar boolean .It Ic conf_override Ar boolean
(optional) override global settings for this mailbox. .Pq Em optional
Override global settings for this mailbox.
Available sections to override are Available sections to override are
.Em pager, notifications, shortcuts, composing .Em pager, notifications, shortcuts, composing
and the account options and the account options
.Em identity and index_style Ns .Em identity
and
.Em index_style Ns
\&. \&.
Example: Example:
.Bd -literal .Bd -literal
@ -324,23 +351,27 @@ Example:
.Ed .Ed
.El .El
.Sh COMPOSING .Sh COMPOSING
Composing specific options
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic send_mail Ar String|SmtpServerConf .It Ic send_mail Ar String|SmtpServerConf
command to pipe new mail to (exit code must be 0 for success) or settings for an SMTP server connection. Command to pipe new mail to (exit code must be 0 for success) or settings for an SMTP server connection.
See section See section
.Sx SMTP Connections .Sx SMTP Connections
for its fields. for its fields.
.It Ic editor_command Ar String .It Ic editor_command Ar String
command to launch editor. Command to launch editor.
Can have arguments. Can have arguments.
Draft filename is given as the last argument. Draft filename is given as the last argument.
If it's missing, the environment variable $EDITOR is looked up. If it's missing, the environment variable $EDITOR is looked up.
.It Ic embed Ar boolean .It Ic embed Ar boolean
(optional) embed editor within meli .Pq Em optional
Embed editor within meli.
Editor must be xterm compliant.
.\" default value .\" default value
.Pq Em false .Pq Em false
.It Ic format_flowed Ar boolean .It Ic format_flowed Ar boolean
(optional) set format=flowed [RFC3676] in text/plain attachments. .Pq Em optional
Set format=flowed [RFC3676] in text/plain attachments.
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic default_header_values Ar hash table String[String] .It Ic default_header_values Ar hash table String[String]
@ -348,26 +379,46 @@ Default header values used when creating a new draft.
.El .El
.Sh SHORTCUTS .Sh SHORTCUTS
Shortcuts can take the following values: Shortcuts can take the following values:
.Qq Em Backspace .Bl -bullet -compact
.Qq Em Left .It
.Qq Em Right .Em Backspace
.Qq Em Up .It
.Qq Em Down .Em Left
.Qq Em Home .It
.Qq Em End .Em Right
.Qq Em PageUp .It
.Qq Em PageDown .Em Up
.Qq Em Delete .It
.Qq Em Insert .Em Down
.Qq Em Enter .It
.Qq Em Tab .Em Home
.Qq Em Esc .It
.Qq Em F1..F12 .Em End
.Qq Em M-char .It
.Qq Em C-char .Em PageUp
and .It
.Qq Em char Ns .Em PageDown
, where char is a single character string. .It
.Em Delete
.It
.Em Insert
.It
.Em Enter
.It
.Em Tab
.It
.Em Esc
.It
.Em F1..F12
.It
.Em M-char
.It
.Em C-char
.It
.Em char
.El
.Em char
is a single character string.
.sp .sp
The headings before each list indicate the map key of the shortcut list. The headings before each list indicate the map key of the shortcut list.
For example for the first list titled For example for the first list titled
@ -520,7 +571,7 @@ Edit mail.
.sp .sp
.Em envelope-view .Em envelope-view
.Pp .Pp
To "select" an attachment, type its index (you will see the typed result in the command buffer on your bottom right of the status line) and then issue the corresponding command. To select an attachment, type its index (you will see the typed result in the command buffer on the bottom right of the status line), then issue the corresponding command.
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic add_addresses_to_contacts Ns .It Ic add_addresses_to_contacts Ns
Select addresses from envelope to add to contacts. Select addresses from envelope to add to contacts.
@ -550,7 +601,7 @@ Opens selected attachment with
.It Ic open_mailcap .It Ic open_mailcap
Opens selected attachment according to its mailcap entry. Opens selected attachment according to its mailcap entry.
See See
.Xr meli.1 FILES .Xr meli 1 FILES
for the mailcap file locations. for the mailcap file locations.
.\" default value .\" default value
.Pq Em m .Pq Em m
@ -560,7 +611,7 @@ Go to url of given index
.Pq Em g .Pq Em g
.It Ic toggle_url_mode .It Ic toggle_url_mode
Toggles url open mode. Toggles url open mode.
When active, it prepends an index next to each url that you can select by typing and open by issuing When active, it prepends an index next to each url that you can select by typing the index and open by issuing
.Ic go_to_url .Ic go_to_url
.\" default value .\" default value
.Pq Em u .Pq Em u
@ -601,81 +652,88 @@ Go to next page.
.Sh NOTIFICATIONS .Sh NOTIFICATIONS
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic enable Ar boolean .It Ic enable Ar boolean
enable freedesktop-spec notifications. Enable freedesktop-spec notifications.
this is usually what you want
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic script Ar String .It Ic script Ar String
(optional) script to pass notifications to, with title as 1st arg and body as 2nd .Pq Em optional
Script to pass notifications to, with title as 1st arg and body as 2nd
.\" default value .\" default value
.Pq Em none .Pq Em none Ns
\&.
.It Ic xbiff_file_path Ar String .It Ic xbiff_file_path Ar String
(optional) file that gets its size updated when new mail arrives .Pq Em optional
File that gets its size updated when new mail arrives.
.Pq Em none .Pq Em none
.\" default value .\" default value
.It Ic play_sound Ar boolean .It Ic play_sound Ar boolean
(optional) play theme sound in notifications if possible .Pq Em optional
Play theme sound in notifications if possible.
.Pq Em false .Pq Em false
.\" default value .\" default value
.It Ic sound_file Ar String .It Ic sound_file Ar String
(optional) play sound file in notifications if possible .Pq Em optional
Play sound file in notifications if possible.
.\" default value .\" default value
.Pq Em none .Pq Em none
.El .El
.Sh PAGER .Sh PAGER
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic pager_context Ar num
(optional) number of context lines when going to next page.
(Unimplemented)
.\" default value
.Pq Em 0
.It Ic headers_sticky Ar boolean .It Ic headers_sticky Ar boolean
(optional) always show headers when scrolling. .Pq Em optional
Always show headers when scrolling.
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic html_filter Ar String .It Ic html_filter Ar String
(optional) pipe html attachments through this filter before display .Pq Em optional
Pipe html attachments through this filter before display
.\" default value .\" default value
.Pq Em none .Pq Em none
.It Ic filter Ar String .It Ic filter Ar String
(optional) a command to pipe mail output through for viewing in pager. .Pq Em optional
A command to pipe mail output through for viewing in pager.
.\" default value .\" default value
.Pq Em none .Pq Em none
.It Ic format_flowed Ar bool .It Ic format_flowed Ar bool
(optional) respect format=flowed .Pq Em optional
Respect format=flowed
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic split_long_lines Ar bool .It Ic split_long_lines Ar bool
(optional) Split long lines that would overflow on the x axis. .Pq Em optional
Split long lines that would overflow on the x axis.
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic minimum_width Ar num .It Ic minimum_width Ar num
(optional) Minimum text width in columns. .Pq Em optional
Minimum text width in columns.
.\" default value .\" default value
.Pq Em 80 .Pq Em 80
.It Ic auto_choose_multipart_alternative Ar boolean, .It Ic auto_choose_multipart_alternative Ar boolean
(optional) Choose `text/html` alternative if `text/plain` is empty in `multipart/alternative` attachments. .Pq Em optional
Choose `text/html` alternative if `text/plain` is empty in `multipart/alternative` attachments.
.\" default value .\" default value
.Pq Em true .Pq Em true
.El .El
.Sh LISTING .Sh LISTING
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic context_lines Ar num
(optional) number of context lines when going to next page.
(Unimplemented)
.\" default value
.Pq Em 0
.It Ic datetime_fmt Ar String .It Ic datetime_fmt Ar String
(optional) datetime formatting passed verbatim to strftime(3). .Pq Em optional
Datetime formatting passed verbatim to strftime(3).
.\" default value .\" default value
.Pq Em \&%Y-\&%m-\&%d \&%T .Pq Em \&%Y-\&%m-\&%d \&%T
.It Ic recent_dates Ar Boolean .It Ic recent_dates Ar Boolean
(optional) Show recent dates as `X {minutes,hours,days} ago`, up to 7 days. .Pq Em optional
Show recent dates as `X {minutes,hours,days} ago`, up to 7 days.
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic filter Ar Query .It Ic filter Ar Query
(optional) Show only envelopes matching this query (for query syntax see .Pq Em optional
.Xr meli 1 ) Show only envelopes matching this query.
.Po
For query syntax see
.Xr meli 1 QUERY ABNF SYNTAX
.Pc
.\" default value .\" default value
.Pq Em None .Pq Em None
.Pp .Pp
@ -687,12 +745,14 @@ filter = "not flags:seen" # show only unseen messages
.Sh TAGS .Sh TAGS
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic colours Ar hash table String[Color] .It Ic colours Ar hash table String[Color]
(optional) set UI colors for tags .Pq Em optional
Set UI colors for tags
.It Ic ignore_tags Ar Array String .It Ic ignore_tags Ar Array String
(optional) hide tags (not the tagged messages themselves) .Pq Em optional
Hide tags (not the tagged messages themselves)
.El .El
.sp .sp
example configuration: Example:
.sp .sp
.Bd -literal .Bd -literal
[tags] [tags]
@ -707,42 +767,49 @@ colors = { signed="#Ff6600", replied="DeepSkyBlue4", draft="#f00", replied="8" }
.Sh PGP .Sh PGP
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic auto_verify_signatures Ar boolean .It Ic auto_verify_signatures Ar boolean
auto verify signed e-mail according to RFC3156 Auto verify signed e-mail according to RFC3156
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic auto_sign Ar boolean .It Ic auto_sign Ar boolean
(optional) always sign sent messages .Pq Em optional
Always sign sent messages
.\" default value .\" default value
.Pq Em false .Pq Em false
.It Ic key Ar String .It Ic key Ar String
(optional) key to be used when signing/encrypting (not functional yet) .Pq Em optional
Key to be used when signing/encrypting (not functional yet)
.\" default value .\" default value
.Pq Em none .Pq Em none
.It Ic gpg_binary Ar String .It Ic gpg_binary Ar String
(optional) gpg binary name or file location to use .Pq Em optional
The gpg binary name or file location to use
.\" default value .\" default value
.Pq Em "gpg2" .Pq Em "gpg2"
.El .El
.Sh TERMINAL .Sh TERMINAL
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic theme Ar String .It Ic theme Ar String
(optional) select between these themes: light / dark .Pq Em optional
Theme name to use.
.\" default value .\" default value
.Pq Em dark .Pq Em dark
.It Ic ascii_drawing Ar boolean .It Ic ascii_drawing Ar boolean
(optional) if true, box drawing will be done with ascii characters. .Pq Em optional
If true, box drawing will be done with ascii characters.
.\" default value .\" default value
.Pq Em false .Pq Em false
.It Ic use_color Ar boolean .It Ic use_color Ar boolean
(optional) if false, no ANSI colors are used .Pq Em optional
If false, no ANSI colors are used.
.\" default value .\" default value
.Pq Em true .Pq Em true
.It Ic window_title Ar String .It Ic window_title Ar String
(optional) set window title in xterm compatible terminals (empty string means no window title is set) .Pq Em optional
Set window title in xterm compatible terminals An empty string means no window title is set.
.\" default value .\" default value
.Pq Em "meli" .Pq Em "meli"
.It Ic themes Ar hash table String[String[Attribute]] .It Ic themes Ar hash table String[String[Attribute]]
define UI themes. Define UI themes.
See See
.Xr meli-themes 5 .Xr meli-themes 5
for details. for details.
@ -763,13 +830,17 @@ theme = "themeB"
.Sh LOG .Sh LOG
.Bl -tag -width 36n .Bl -tag -width 36n
.It Ic log_file Ar String .It Ic log_file Ar String
(optional) path of the log file .Pq Em optional
path of the log file
.\" default value .\" default value
.Pq Pa $XDG_DATA_HOME/meli/meli.log .Pq Pa $XDG_DATA_HOME/meli/meli.log
.It Ic maximum_level Ar String .It Ic maximum_level Ar String
(optional) maximum level of messages to log. All levels less or equal to the .Pq Em optional
maximum level of messages to log.
All levels less or equal to the
.Ic maximum_level .Ic maximum_level
will be appended to the log file. Available levels are, in partial order: will be appended to the log file.
Available levels are, in partial order:
.Bl -bullet -compact .Bl -bullet -compact
.It .It
.Em OFF .Em OFF
@ -801,7 +872,8 @@ server hostname
.It Ic port Ar Integer .It Ic port Ar Integer
server port server port
.It Ic envelope_from Ar String .It Ic envelope_from Ar String
(optional) address to set as sender in SMTP transactions .Pq Em optional
address to set as sender in SMTP transactions
.\" default value .\" default value
.Pq Em none .Pq Em none
.It Ic auth Ar SmtpAuth .It Ic auth Ar SmtpAuth
@ -810,14 +882,16 @@ See
.Sx SmtpAuth .Sx SmtpAuth
subsection. subsection.
.It Ic security Ar SmtpSecurity .It Ic security Ar SmtpSecurity
(optional) gpg binary name or file location to use .Pq Em optional
gpg binary name or file location to use
.\" default value .\" default value
.Po see .Po see
.Sx SmtpSecurity .Sx SmtpSecurity
subsection subsection
.Pc .Pc
.It Ic extensions Ar SmtpExtensions .It Ic extensions Ar SmtpExtensions
(optional) set support for SMTP extensions if they are advertised by the server .Pq Em optional
set support for SMTP extensions if they are advertised by the server
.\" default value .\" default value
.Po see .Po see
.Sx SmtpExtensions .Sx SmtpExtensions
@ -834,7 +908,8 @@ For type "auto":
.It Ic username Ar String .It Ic username Ar String
.It Ic password Ar String|SmtpPassword .It Ic password Ar String|SmtpPassword
.It Ic require_auth Ar bool .It Ic require_auth Ar bool
(optional) require authentication in every case .Pq Em optional
require authentication in every case
.\" default value .\" default value
.Pq Em true .Pq Em true
.El .El