@ -23,7 +23,7 @@ The Makefile *should* be portable and not require a specific `make` version.
# 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.
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
.Ic color_aliases
or
@ -134,8 +137,8 @@ Color values are of type String with the following valid contents:
.It
"Default" is the terminal default. (Case-sensitive)
.It
Hex triplet eg #FFFFFF for RGB colors
(three letter shorthand also valid, eg #09c → #0099cc) (Case-insensitive)
Hex triplet e.g. #FFFFFF for RGB colors.
Three character shorthand is also valid, e.g. #09c → #0099cc (Case-insensitive)
.It
0-255 byte for 256 colors.
.It
@ -162,7 +165,7 @@ is explicitly set to true by the user,
is ignored.
.El
.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.
is a terminal mail client aiming for extensive and user-frendly configurability.
.Bd -literal
^^ .-=-=-=-. ^^
^^ (`-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-`) ^^ ^^
^^ (`-=-=-=-=-=-=-=-`) ^^
( `-=-=-=-(@)-=-=-` ) ^^
(`-=-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-=-=-`)
^^ (`-=-=-=-=-=-=-=-=-`) ^^
^^ (`-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-`) ^^
^^ (`-=-=-=-=-`)
`-=-=-=-=-` ^^
^^ .-=-=-=-. ^^
^^ (`-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-`) ^^ ^^
^^ (`-=-=-=-=-=-=-=-`) ^^
( `-=-=-=-(@)-=-=-` ) ^^
(`-=-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-=-=-`)
^^ (`-=-=-=-=-=-=-=-=-`) ^^
^^ (`-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-`) ^^
^^ (`-=-=-=-=-`)
`-=-=-=-=-` ^^
.Ed
.Sh STARTING WITH meli
When launched for the first time,
@ -75,29 +75,27 @@ 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.toml
includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away.
If it doesn't exist, you will be asked if you want to create one and presented with a sample configuration file
.Pq 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.
See
.Xr meli.conf 5
for the available configuration options.
.Pp
At any time, you may press
.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
The main visual navigation tool is the left-side sidebar.
The menu's visibility may be toggled with
The main visual navigation tool, the left-side sidebar may be toggled with
.Cm `
(shortcuts.listing:
.Ic toggle_menu_visibility Ns
).
.Pp
The view into each mailbox has 4 modes: plain, threaded, conversations and compact.
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).
Each mailbox may be viewed in 4 modes:
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
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"
in the
.Em terminal
@ -107,14 +105,21 @@ See
for complete documentation on user themes.
.Sh VIEWING MAIL
Open attachments by typing their index in the attachments list and then
.Cm a Ns
\&.
.Cm a
.Po
shortcut
.Ic open_attachment
.Pc .
.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
\&.
Press
.Cm m
.Po
shortcut
.Ic open_mailcap
.Pc
instead to use the mailcap entry for the MIME type of the attachment, if any.
See
.Sx FILES
@ -122,6 +127,8 @@ for the location of the mailcap files and
.Xr mailcap 5
for their syntax.
You can save individual attachments with the
.Em EXECUTE
command
.Cm save-attachment Ar INDEX Ar path-to-file
where
.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 path provided is a directory, the message is saved as an eml file with its filename set to the messages message-id.
.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
uses the SEARCH command,
.Em notmuch
uses libnotmuch and
.Em Maildir/mbox
have to do a slow linear search.
Thus it is advised to use a cache on
performs a slow linear search.
It is advised to use a cache on
.Em Maildir/mbox
accounts.
.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.
To enable sqlite3 indexing for an account set
.Em cache_type
@ -182,6 +198,37 @@ to
will relay your queries to the IMAP server.
Expect a delay between query and response.
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
Few things to consider before writing TOML (quoting the spec):
Configuration for meli is written in TOML which has a few things to consider (quoting the spec):
.Pp
.Bl -bullet -compact
.It
@ -123,24 +122,24 @@ set_seen = 'n'
theme = "light"
.Ed
.Pp
available options are listed below.
.Sy default values are shown in parentheses.
Available options are listed below.
Default values are shown in parentheses.
.Sh ACCOUNTS
.Bl -tag -width 36n
.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
the format of the mail backend.
The format of the mail backend.
.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").
The glob wildcard
.Em \&*
can be used to match every mailbox name and path.
.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
set the way mailboxes are displayed
Sets the way mailboxes are displayed.
.El
.TS
allbox tab(:);
@ -152,26 +151,31 @@ plain:shows one row per mail, regardless of threading
.TE
.Bl -tag -width 36n
.It Ic display_name Ar String
(optional) a name which can be combined with your address:
"Name <email@address.tld>"
.Pq Em optional
A name which can be combined with your address: "Name <email@address.tld>".
.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
.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
.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
.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'
.Pq Em "sqlite3"
.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.
.It Ic mailboxes Ar mailbox
(optional) configuration for each mailbox.
.Pq Em optional
Configuration for each mailbox.
Its format is described below in
.Sx mailboxes Ns
\&.
@ -182,7 +186,7 @@ points to the directory which contains the
.Pa .notmuch/
subdirectory.
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
field and set the
.Ar query
@ -204,46 +208,59 @@ IMAP specific options are:
example:
.Qq mail.example.tld
.It Ic server_username Ar String
Server username
.It Ic server_password Ar String
Server password
.It Ic server_password_command Ar String
(optional) Use instead of
.Pq Em optional
Use instead of
.Ic server_password
.It Ic server_port Ar number
(optional)
.Pq Em optional
The port to connect to
.\" default value
.Pq Em 143
.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
.Pq Em true
.It Ic danger_accept_invalid_certs Ar boolean
(optional) do not validate TLS certificates.
.Pq Em optional
Do not validate TLS certificates.
.\" default value
.Pq Em false
.El
.Ss JMAP only
JMAP specific options are:
JMAP specific options
.Bl -tag -width 36n
.It Ic server_hostname Ar String
example:
.Qq mail.example.tld
.It Ic server_username Ar String
Server username
.It Ic server_password Ar String
Server password
.It Ic server_port Ar number
(optional)
.Pq Em optional
The port to connect to
.\" default value
.Pq Em 443
.It Ic danger_accept_invalid_certs Ar boolean
(optional) do not validate TLS certificates.
.Pq Em optional
Do not validate TLS certificates.
.\" default value
.Pq Em false
.El
.Ss mbox only
mbox specific options are:
mbox specific options
.Bl -tag -width 36n
.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.
Valid values are:
.Pq Em 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.
Valid values
.Bl -bullet -compact
.It
.Ar auto
@ -259,7 +276,7 @@ Valid values are:
.\" default value
.Pq Em auto
.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
(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
(optional) load this mailbox on startup
.Pq Em optional
Load this mailbox on startup
.\" default value
.Pq Em true
.It Ic subscribe Ar boolean
(optional) watch this mailbox for updates
.Pq Em optional
Watch this mailbox for updates
.\" default value
.Pq Em true
.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
.Pq Em false
.It Ic usage Ar boolean
(optional) special usage of this mailbox.
.Pq Em optional
special usage of this mailbox.
Valid values are:
.Bl -bullet -compact
.It
.Ar Normal
.Pq Em default
.It
.Ar Inbox
.It
@ -308,12 +331,16 @@ Valid values are:
.Ar Trash
.El
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
(optional) override global settings for this mailbox.
.Pq Em optional
Override global settings for this mailbox.
Available sections to override are
.Em pager, notifications, shortcuts, composing
and the account options
.Em identity and index_style Ns
.Em identity
and
.Em index_style Ns
\&.
Example:
.Bd -literal
@ -324,23 +351,27 @@ Example:
.Ed
.El
.Sh COMPOSING
Composing specific options
.Bl -tag -width 36n
.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
.Sx SMTP Connections
for its fields.
.It Ic editor_command Ar String
command to launch editor.
Command to launch editor.
Can have arguments.
Draft filename is given as the last argument.
If it's missing, the environment variable $EDITOR is looked up.
.It Ic embed Ar boolean
(optional) embed editor within meli
.Pq Em optional
Embed editor within meli.
Editor must be xterm compliant.
.\" default value
.Pq Em false
.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
.Pq Em true
.It Ic default_header_values Ar hash table String[String]
@ -348,26 +379,46 @@ Default header values used when creating a new draft.
.El
.Sh SHORTCUTS
Shortcuts can take the following values:
.Qq Em Backspace
.Qq Em Left
.Qq Em Right
.Qq Em Up
.Qq Em Down
.Qq Em Home
.Qq Em End
.Qq Em PageUp
.Qq Em PageDown
.Qq Em Delete
.Qq Em Insert
.Qq Em Enter
.Qq Em Tab
.Qq Em Esc
.Qq Em F1..F12
.Qq Em M-char
.Qq Em C-char
and
.Qq Em char Ns
, where char is a single character string.
.Bl -bullet -compact
.It
.Em Backspace
.It
.Em Left
.It
.Em Right
.It
.Em Up
.It
.Em Down
.It
.Em Home
.It
.Em End
.It
.Em PageUp
.It
.Em PageDown
.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
The headings before each list indicate the map key of the shortcut list.
For example for the first list titled
@ -520,7 +571,7 @@ Edit mail.
.sp
.Em envelope-view
.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
.It Ic add_addresses_to_contacts Ns
Select addresses from envelope to add to contacts.
@ -550,7 +601,7 @@ Opens selected attachment with
.It Ic open_mailcap
Opens selected attachment according to its mailcap entry.
See
.Xr meli.1 FILES
.Xr meli1 FILES
for the mailcap file locations.
.\" default value
.Pq Em m
@ -560,7 +611,7 @@ Go to url of given index
.Pq Em g
.It Ic toggle_url_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
.\" default value
.Pq Em u
@ -601,81 +652,88 @@ Go to next page.
.Sh NOTIFICATIONS
.Bl -tag -width 36n
.It Ic enable Ar boolean
enable freedesktop-spec notifications.
this is usually what you want
Enable freedesktop-spec notifications.
.\" default value
.Pq Em true
.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
.Pq Em none
.Pq Em none Ns
\&.
.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
.\" default value
.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
.\" default value
.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
.Pq Em none
.El
.Sh PAGER
.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
(optional) always show headers when scrolling.
.Pq Em optional
Always show headers when scrolling.
.\" default value
.Pq Em true
.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
.Pq Em none
.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
.Pq Em none
.It Ic format_flowed Ar bool
(optional) respect format=flowed
.Pq Em optional
Respect format=flowed
.\" default value
.Pq Em true
.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
.Pq Em true
.It Ic minimum_width Ar num
(optional) Minimum text width in columns.
.Pq Em optional
Minimum text width in columns.
.\" default value
.Pq Em 80
.It Ic auto_choose_multipart_alternative Ar boolean,
(optional) Choose `text/html` alternative if `text/plain` is empty in `multipart/alternative` attachments.
.It Ic auto_choose_multipart_alternative Ar boolean
.Pq Em optional
Choose `text/html` alternative if `text/plain` is empty in `multipart/alternative` attachments.
.\" default value
.Pq Em true
.El
.Sh LISTING
.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
(optional) datetime formatting passed verbatim to strftime(3).
.Pq Em optional
Datetime formatting passed verbatim to strftime(3).
.\" default value
.Pq Em \&%Y-\&%m-\&%d \&%T
.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
.Pq Em true
.It Ic filter Ar Query
(optional) Show only envelopes matching this query (for query syntax see
.Xr meli 1 )
.Pq Em optional
Show only envelopes matching this query.
.Po
For query syntax see
.Xr meli 1 QUERY ABNF SYNTAX
.Pc
.\" default value
.Pq Em None
.Pp
@ -687,12 +745,14 @@ filter = "not flags:seen" # show only unseen messages
.Sh TAGS
.Bl -tag -width 36n
.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
(optional) hide tags (not the tagged messages themselves)
