update manual page and add meli.conf(5)

embed
Manos Pitsidianakis 2019-09-16 14:07:38 +03:00
parent 080b8ae775
commit e6b7d3a855
Signed by: Manos Pitsidianakis
GPG Key ID: 73627C2F690DF710
3 changed files with 365 additions and 27 deletions

91
meli.1
View File

@ -49,7 +49,9 @@ When launched for the first time, meli will search for its configuration directo
.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
includes comments with 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
.Xr meli.conf 5
for the available configuration options.
.Pp
At any time, you can press
.Cm \&?
@ -59,7 +61,7 @@ The main visual navigation tool is the left-side sidebar. The menu's visibility
.Cm ` Ns
).
.Pp
The view into each folder has 3 modes: plain, threaded and compact. Plain views each mail indvidually, threaded shows their thread relationship visually, and compact includes one entry per thread of emails.
The view into each folder 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).
.Bd -literal
^^ .-=-=-=-. ^^
^^ (`-=-=-=-=-`) ^^
@ -77,35 +79,54 @@ The view into each folder has 3 modes: plain, threaded and compact. Plain views
.Ed
.Sh EXECUTE mode
Commands are issued in EXECUTE mode, by default started with the space character and exited with Escape key.
.Bl -tag -width "Cm subsort Op Ar subject | date Op asc | desc"
.It Cm set Ar plain | threaded | compact
.Pp
the following commands are valid in the mail listing context:
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST"
.It Ic set Ar plain | threaded | compact | conversations
set the way mailboxes are displayed
.Bl -tag -width "threaded" -compact
.Bl -tag -width "conversations" -compact
.It Cm plain
shows one row per mail, regardless of threading
.It Cm threaded
shows threads as a tree structure, with one row per thread entry
.It Cm conversations
shows one entry per thread
.It Cm compact
shows one row per thread
.El
.It Cm sort Ar subject | date \ Ar asc | desc
.It Ic sort Ar subject | date \ Ar asc | desc
sort mail listing
.It Cm subsort Ar subject | date \ Ar asc | desc
.It Ic subsort Ar subject | date \ Ar asc | desc
sorts only the first level of replies.
.It Cm close
closes closeable tabs
.It Cm go Ar n
.It Ic go Ar n
where
.Ar n
is a mailbox prefixed with the
.Ar n
number in the side menu for the current account
.It Cm toggle_thread_snooze
.It Ic toggle_thread_snooze
don't issue notifications for thread under cursor in thread listing
.It Cm filter Ar STRING
.It Ic filter Ar STRING
filter mailbox with
.Ar STRING
key. Escape exits filter results
.It Ic set read, set unread
.It Ic create-folder Ar ACCOUNT Ar FOLDER_PATH
create folder with given path. be careful with backends and separator sensitivity (eg IMAP)
.It Ic subscribe-folder Ar ACCOUNT Ar FOLDER_PATH
subscribe to folder with given path
.It Ic unsubscribe-folder Ar ACCOUNT Ar FOLDER_PATH
unsubscribe to folder with given path
.It Ic rename-folder Ar ACCOUNT Ar FOLDER_PATH_SRC Ar FOLDER_PATH_DEST
rename folder
.It Ic delete-folder Ar ACCOUNT Ar FOLDER_PATH
delete folder
.El
.Pp
envelope view commands:
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST" -offset indent
.It Cm pipe Ar EXECUTABLE Ar ARGS
pipe pager contents to binary
.It Cm list-post
post in list of currently viewed envelope
.It Cm list-unsubscribe
@ -113,19 +134,36 @@ unsubscribe automatically from list of currently viewed envelope
.It Cm list-archive
open list archive with
.Cm xdg-open
.It Cm set read, set unread
.El
.Pp
composing mail commands:
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST" -offset indent
.It Ic add-attachment Ar PATH
in composer, add
.Ar PATH
as an attachment
.It Ic remove-attachment Ar INDEX
remove attachment with given index
.El
.Pp
generic commands:
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST" -offset indent
.It Cm open-in-tab
opens envelope view in new tab
.It Ic close
closes closeable tabs
.It Cm setenv Ar KEY=VALUE
set environment variable
.Ar KEY
to
.Ar VALUE
.It Cm printenv KEY
.It Cm printenv Ar KEY
print environment variable
.Ar KEY
.El
.Sh SHORTCUTS
Non-complete list of shortcuts and their default values.
.Bl -tag -width "create_contact" -offset indent
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST" -offset indent
.It Cm open_thread
\&'\\n'
.It Cm exit_thread
@ -156,8 +194,12 @@ PageDown
PageUp
.It Cm page_down
PageDown
.It Cm toggle-menu-visibility
\&'`'
.It Cm select
\&'v'
.El
.Bl -tag -width "<n>a" -offset indent
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST" -offset indent
.It Cm `
toggles hiding of sidebar in mail listings
.It Cm \&?
@ -178,6 +220,8 @@ opens the
.Ar n Ns
th
attachment.
.It Cm v
(un)selects mail entries in mail listings
.El
.Sh EXIT STATUS
.Nm
@ -187,7 +231,7 @@ exits with 0 on a successful run. Other exit statuses are:
catchall for general errors
.El
.Sh ENVIRONMENT
.Bl -tag -width "Ev MELI_CONFIG" -offset indent
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
.It Ev EDITOR
Specifies the editor to use
.It Ev MELI_CONFIG
@ -195,7 +239,7 @@ Override the configuration file
.El
.Sh FILES
meli uses the following parts of the XDG standard:
.Bl -tag -width "XDG_CONFIG_HOME" -offset indent
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
.It Ev XDG_CONFIG_HOME
defaults to
.Pa ~/.config/
@ -209,18 +253,25 @@ and appropriates the following locations:
.It Pa $XDG_CONFIG_HOME/meli/
User configuration directory.
.It Pa $XDG_CONFIG_HOME/meli/config
User configuration file.
User configuration file. See
.Xr meli.conf 5
for its syntax and values.
.It Pa $XDG_CONFIG_HOME/meli/hooks/*
Reserved for event hooks.
.It Pa $XDG_CONFIG_HOME/meli/plugins/*
Reserved for plugin files.
.It Pa $XDG_CACHE_HOME/meli/*
Internal cached data used by meli.
.It Pa $XDG_DATA_HOME/meli/*
Internal data used by meli.
.It Pa $XDG_DATA_HOME/meli/meli.log
Operation log.
.It Pa /tmp/meli/*
Temporary files generated by meli.
.El
.Sh SEE ALSO
.Xr xdg-open 1
.Xr xdg-open 1 ,
.Xr meli.conf 5
.Sh CONFORMING TO
XDG Standard
.Aq https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html Ns

286
meli.conf.5 100644
View File

@ -0,0 +1,286 @@
.\" meli - meli.1
.\"
.\" Copyright 2017-2019 Manos Pitsidianakis
.\"
.\" This file is part of meli.
.\"
.\" meli is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" meli is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with meli. If not, see <http://www.gnu.org/licenses/>.
.\"
.Dd September 16, 2019
.Dt MELI.CONF 5
.Os Linux
.Sh NAME
.Nm meli.conf
.Nd configuration file for the Meli Mail User Agent
.Sh SYNOPSIS
.Pa $XDG_CONFIG_HOME/meli/config
.Sh DESCRIPTION
Configuration for meli is written in TOML. Few things to consider before writing TOML (quoting the spec):
.Pp
.Bl -bullet -compact
.It
TOML is case sensitive.
.It
A TOML file must be a valid UTF-8 encoded Unicode document.
.It
Whitespace means tab (0x09) or space (0x20).
.It
Newline means LF (0x0A) or CRLF (0x0D 0x0A).
.El
.Pp
Refer to TOML documentation for valid TOML syntax.
.Sh SECTIONS
The top level sections of the config are accounts, shortcuts, notifications, pager, mailer.
.Pp
.Sy example configuration
.Bd -literal
# Setting up a Maildir account
[accounts.account-name]
root_folder = "/path/to/root/folder"
format = "Maildir"
index_style = "Compact"
identity="Name <email@address.tld>"
display_name = "Name"
# Set folder-specific settings
[accounts.account-name.folders]
"INBOX" = { rename="Inbox" } #inline table
"drafts" = { rename="Drafts" } #inline table
[accounts.account-name.folders."foobar-devel"] # or a regular table
ignore = true # don't show notifications for this folder
# Setting up an mbox account
[accounts.mbox]
root_folder = "/var/mail/username"
format = "mbox"
index_style = "Compact"
identity="username@hostname.local"
[pager]
filter = "/usr/bin/pygmentize"
[notifications]
script = "notify-send"
[mailer]
# required for sending e-mail
mailer_cmd = 'msmtp --read-recipients --read-envelope-from'
[shortcuts]
scroll_up = 'k'
scroll_down = 'j'
page_up = PageUp
page_down = PageDown
.Ed
.Pp
available options are listed below.
.Sy default values are shown in parentheses.
.Sh ACCOUNTS
.Bl -tag -width "danger_accept_invalid_certs boolean" -offset -indent
.It Cm root_folder Ar String
the backend-specific path of the root_folder, usually INBOX
.It Cm format Ar String Op maildir mbox imap
the format of the mail backend.
.It Cm subscribed_folders Ar [String,]
an array of folder paths to display in the UI. Paths are relative to the root folder (eg "INBOX/Sent", not "Sent")
.It Cm identity Ar String
your e-mail address that is inserted in the From: headers of outgoing mail
.It Cm index_style Ar String
set the way mailboxes are displayed
.Bl -tag -width "conversations" -compact
.It Cm plain
shows one row per mail, regardless of threading
.It Cm threaded
shows threads as a tree structure, with one row per thread entry
.It Cm conversations
shows one entry per thread
.It Cm compact
shows one row per thread
.El
.It Cm display_name Ar String
(optional) a name which can be combined with your address:
"Name <email@address.tld>"
.It Cm html_filter Ar String
(optional) pipe html attachments through this filter before display
.It Cm read_only Ar boolean
attempt to not make any changes to this account.
.Pq Em false
.It Cm folders Ar folder_config
(optional) configuration for each folder. Its format is described below in
.Sx FOLDERS Ns
\&.
.El
.Pp
IMAP specific options are:
.Bl -tag -width "danger_accept_invalid_certs boolean" -offset -indent
.It Cm server_hostname Ar String
example:
.Qq mail.example.tld
.It Cm server_username Ar String
.It Cm server_password Ar String
.It Cm danger_accept_invalid_certs Ar boolean
(optional) do not validate TLS certificates.
.\" default value
.Pq Em false
.El
.Sh FOLDERS
.Bl -tag -width "danger_accept_invalid_certs boolean" -offset -indent
.It Cm rename Ar String
(optional) show a different name for this folder in the UI
.It Cm autoload Ar boolean
(optional) load this folder on startup (not functional yet)
.It Cm subscribe Ar boolean
(optional) watch this folder for updates
.\" default value
.Pq Em true
.It Cm ignore Ar boolean
(optional) silently insert updates for this folder, if any
.\" default value
.Pq Em false
.It Cm usage Ar boolean
(optional) special usage of this folder. valid values are:
.Bl -bullet -compact
.It
.Ar Normal
.It
.Ar Inbox
.It
.Ar Archive
.It
.Ar Drafts
.It
.Ar Flagged
.It
.Ar Junk
.It
.Ar Sent
.It
.Ar Trash
.El
otherwise usage is inferred from the folder title.
.It Cm conf_override Ar boolean
(optional) override global settings for this folder. available sections to override are
.Em pager, notifications, shortcuts, mailer
and the account options
.Em identity and index_style Ns
\&. example:
.Bd -literal
[accounts."imap.domain.tld".folders."INBOX"]
index_style = "plain"
[accounts."imap.domain.tld".folders."INBOX".pager]
filter = ""
.Ed
.El
.Sh MAILER
.Bl -tag -width "danger_accept_invalid_certs boolean" -offset -indent
.It Cm mailer_cmd Ar String
command to pipe new mail to, exit code must be 0 for success.
.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 Esc
and
.Qq Em char Ns
, where char is a single character string.
.Bl -tag -width "danger_accept_invalid_certs boolean" -offset -indent
.It Cm prev_page
Go to previous page.
.It Cm next_page
Go to next page.
.It Cm prev_folder
Go to previous folder.
.It Cm next_folder
Go to next folder.
.It Cm prev_account
Go to previous account.
.It Cm next_account
Go to next account.
.It Cm new_mail
Start new mail draft in new tab
.It Cm open_thread
Open thread.
.It Cm exit_thread
Exit thread view
.It Cm scroll_up
Scroll up pager.
.It Cm scroll_down
Scroll down pager.
.It Cm page_up
Go to previous pager page
.It Cm page_down
Go to next pager pag
.It Cm create_contact
Create new contact.
.It Cm edit_contact
Edit contact under cursor
.El
.Sh NOTIFICATIONS
.Bl -tag -width "danger_accept_invalid_certs boolean" -offset -indent
.It Cm enable Ar boolean
enable freedesktop-spec notifications. this is usually what you want
.\" default value
.Pq Em true
.It Cm script Ar String
(optional) script to pass notifications to, with title as 1st arg and body as 2nd
.\" default value
.Pq Em none
.It Cm xbiff_file_path Ar String
(optional) file that gets its size updated when new mail arrives
.Pq Em none
.\" default value
.It Cm play_sound Ar boolean
(optional) play theme sound in notifications if possible
.Pq Em false
.\" default value
.It Cm sound_file Ar String
(optional) play sound file in notifications if possible
.\" default value
.Pq Em none
.El
.Sh PAGER
.Bl -tag -width "danger_accept_invalid_certs boolean" -offset -indent
.It Cm pager_context Ar num
(optional) number of context lines when going to next page.
.\" default value
.Pq Em 0
.It Cm headers_sticky Ar boolean
(optional) always show headers when scrolling.
.\" default value
.Pq Em false
.It Cm filter Ar String
(optional) a command to pipe mail output through for viewing in pager.
.\" default value
.Pq Em none
.El
.Sh SEE ALSO
.Xr meli 1
.Sh CONFORMING TO
TOML Standard v.0.5.0 https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md
.Sh AUTHORS
Copyright 2017-2019
.An Manos Pitsidianakis Aq epilys@nessuent.xyz
Released under the GPL, version 3 or greater. This software carries no warranty of any kind. (See COPYING for full copyright and warranty notices.)
.Pp
.Aq https://meli.delivery

View File

@ -1,10 +1,8 @@
# Setting up a Maildir account
#[accounts.account-name]
#root_folder = "/path/to/root/folder"
#sent_folder = "/path/to/sent/folder" # optional
#draft_folder = "Drafts"
#format = "Maildir"
#index = "Compact" # [plain, threaded, compact]
#index_style = "Compact" # [plain, threaded, compact]
#identity="Name <email@address.tld>"
#display_name = "Name"
@ -17,18 +15,21 @@
# Setting up an mbox account
#[accounts.mbox]
#root_folder = "/var/mail/username"
#draft_folder = ""
#sent_folder = ""
#format = "mbox"
#index = "Compact"
#index_style = "Compact"
#identity="username@hostname.local"
#[pager]
#pager_ratio = 80
#filter = "/usr/bin/pygmentize"
#pager_context = 0 # default, optional
#headers_sticky = true # default, optional
#[notifications]
#enable = true # default, optional
#script = "notify-send"
#xbiff_file_path = PATH # for use with xbiff(1)
#play_sound = true # default, optional
#sound_file = PATH # optional
#[shortcuts]
# Compact mail listing defaults: