update documentation

Endless gratitude to WanderingBeekeper for editing the text.
memfd
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
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

View File

@ -29,10 +29,10 @@ mail client
.Nm meli
comes with two themes,
.Ic dark
(the default) and
(default) and
.Ic light .
.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
.It
.Pa $XDG_CONFIG_HOME/meli/config.toml
@ -48,15 +48,18 @@ theme = "dark"
.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.
are described in the configuration language TOML, as 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.
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.
.sp
.Dl \&"widget.key.label\&" = { fg = \&"Default\&", bg = \&"Default\&", attrs = \&"Default\&" }
.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
.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.
.Sh VALID KEYS
.Bl -bullet -compact
.It

363
meli.1
View File

@ -55,19 +55,19 @@ View mail from input file.
.Nm
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
.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
.Nm
supports tagging in notmuch and IMAP/JMAP backends.
@ -197,54 +244,40 @@ and
.Ic ignore_tags
for how to set tag colors and tag visiblity)
.Sh COMPOSING
To send mail, press
.Ss Opening the message Composer tab
To create a new mail message, press
.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
.Cm R Ns
\&.
You may edit some of the header fields from within the view, by selecting with the arrow keys and pressing
.Cm R
.Po
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
to enter
.Ar INSERT
mode.
.Em INSERT
mode and
.Cm Esc
key to exit.
.It
At any time you may press
.Cm e
to launch your editor (see
(shortcut
.Ic edit_mail Ns
) to launch your editor (see
.Xr meli.conf 5 COMPOSING Ns
, setting
.Ic editor_command
for how to select which editor to launch).
Attachments may be handled with the
.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
.It
Your editor can be used in
.Nm Ns
\&'s embed terminal emulator by setting
@ -252,14 +285,54 @@ Your editor can be used in
to
.Em true
in your composing settings.
.It
When launched, your editor captures all input until it exits or stops.
.It
To stop your editor and return to
.Nm
issue Ctrl-z and to resume editing press the
press Ctrl-z and to resume editing press the
.Ic edit_mail
command again (default
.Em e Ns
).
command again
.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
.Nm
supports two kinds of contact backends:
@ -282,10 +355,25 @@ They are loaded read only.
See
.Xr meli.conf 5 ACCOUNTS
for the complete account configuration values.
.Sh EXECUTE mode
Commands are issued in EXECUTE mode, by default started with Space and exited with Escape key.
.Pp
the following commands are valid in the mail listing context:
.Sh MODES
.Bl -tag -compact -width 8n
.It NORMAL
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
.It Cm set Ar plain | threaded | compact | conversations
set the way mailboxes are displayed
@ -317,6 +405,7 @@ search mailbox with
key.
Escape exits search results
.It Cm set read, set unread
Set read status of message.
.It Cm create-mailbox Ar ACCOUNT Ar MAILBOX_PATH
create mailbox with given path.
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
rename mailbox
.It Cm delete-mailbox Ar ACCOUNT Ar MAILBOX_PATH
delete mailbox
deletes mailbox in the mail backend.
This action is unreversible.
.El
.Pp
envelope view commands:
.Ss Mail view commands
.Bl -tag -width 36n
.It Cm pipe Ar EXECUTABLE Ar ARGS
pipe pager contents to binary
@ -342,8 +431,7 @@ unsubscribe automatically from list of viewed envelope
open list archive with
.Cm xdg-open
.El
.Pp
composing mail commands:
.Ss composing mail commands
.Bl -tag -width 36n
.It Cm add-attachment Ar PATH
in composer, add
@ -358,11 +446,13 @@ remove attachment with given index
.It Cm toggle sign
toggle between signing and not signing this message.
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
saves a copy of the draft in the Draft folder
.El
.Pp
generic commands:
.Ss generic commands
.Bl -tag -width 36n
.It Cm open-in-tab
opens envelope view in new tab
@ -378,108 +468,18 @@ print environment variable
.Ar KEY
.El
.Sh SHORTCUTS
Non-complete list of shortcuts and their default values.
.Bl -tag -width 36n
.It Ic open_thread
\&'\\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
See
.Xr meli.conf 5 SHORTCUTS
for shortcuts and their default values.
.Sh EXIT STATUS
.Nm
exits with 0 on a successful run.
Other exit statuses are:
.Bl -tag -width 2n
.Bl -tag -width 5n
.It 1
catchall for general errors
.It 101
process panic
.El
.Sh ENVIRONMENT
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
@ -508,10 +508,9 @@ defaults to
and appropriates the following locations:
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
.It Pa $XDG_CONFIG_HOME/meli/
User configuration directory.
User configuration directory
.It Pa $XDG_CONFIG_HOME/meli/config.toml
User configuration file.
See
User configuration file, see
.Xr meli.conf 5
for its syntax and values.
.It Pa $XDG_CONFIG_HOME/meli/hooks/*

View File

@ -26,8 +26,7 @@
.Sh SYNOPSIS
.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):
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
.Ic mailboxes
field and set the
.Ar path
@ -270,28 +287,34 @@ Example:
format = "mbox"
mailboxes."Python mailing list" = { path = "~/.mail/python.mbox", subscribe = true, autoload = true }
.Ed
.Sh mailboxes
.Ss MAILBOXES
.Bl -tag -width 36n
.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
(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 meli 1 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)
.Pq Em optional
Hide tags (not the tagged messages themselves)
.El
.sp
example configuration:
Example:
.sp
.Bd -literal
[tags]
@ -707,42 +767,49 @@ colors = { signed="#Ff6600", replied="DeepSkyBlue4", draft="#f00", replied="8" }
.Sh PGP
.Bl -tag -width 36n
.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
.Pq Em true
.It Ic auto_sign Ar boolean
(optional) always sign sent messages
.Pq Em optional
Always sign sent messages
.\" default value
.Pq Em false
.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
.Pq Em none
.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
.Pq Em "gpg2"
.El
.Sh TERMINAL
.Bl -tag -width 36n
.It Ic theme Ar String
(optional) select between these themes: light / dark
.Pq Em optional
Theme name to use.
.\" default value
.Pq Em dark
.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
.Pq Em false
.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
.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)
.Pq Em optional
Set window title in xterm compatible terminals An 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.
Define UI themes.
See
.Xr meli-themes 5
for details.
@ -763,13 +830,17 @@ theme = "themeB"
.Sh LOG
.Bl -tag -width 36n
.It Ic log_file Ar String
(optional) path of the log file
.Pq Em optional
path of the log file
.\" default value
.Pq Pa $XDG_DATA_HOME/meli/meli.log
.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
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
.It
.Em OFF
@ -801,7 +872,8 @@ server hostname
.It Ic port Ar Integer
server port
.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
.Pq Em none
.It Ic auth Ar SmtpAuth
@ -810,14 +882,16 @@ See
.Sx SmtpAuth
subsection.
.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
.Po see
.Sx SmtpSecurity
subsection
.Pc
.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
.Po see
.Sx SmtpExtensions
@ -834,7 +908,8 @@ For type "auto":
.It Ic username Ar String
.It Ic password Ar String|SmtpPassword
.It Ic require_auth Ar bool
(optional) require authentication in every case
.Pq Em optional
require authentication in every case
.\" default value
.Pq Em true
.El