diff --git a/README.md b/README.md index fd6fd4f41..2900dbf57 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/meli-themes.5 b/meli-themes.5 index fb3087a67..7545d0b46 100644 --- a/meli-themes.5 +++ b/meli-themes.5 @@ -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 diff --git a/meli.1 b/meli.1 index 475208daa..702b83656 100644 --- a/meli.1 +++ b/meli.1 @@ -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/* diff --git a/meli.conf.5 b/meli.conf.5 index e85b47760..8d8727d41 100644 --- a/meli.conf.5 +++ b/meli.conf.5 @@ -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 " +.Pq Em optional +A name which can be combined with your address: "Name ". .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