update manual page and add meli.conf(5)

1 files changed, 286 insertions, 0 deletions

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