update manual page and add meli.conf(5)

3 files changed, 365 insertions, 27 deletions

diff --git a/meli.1 b/meli.1
index 5047da7f..0f28afd5 100644
--- a/meli.1
+++ b/meli.1
@@ -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
diff --git a/meli.conf.5 b/meli.conf.5
new file mode 100644
index 00000000..4bc0bb96
--- /dev/null
+++ b/meli.conf.5
@@ -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
diff --git a/sample-config b/sample-config
index 90f0303f..632202f8 100644
--- a/sample-config
+++ b/sample-config
@@ -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: