diff --git a/README.md b/README.md
index fd6fd4f..2900dbf 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 fb3087a..7545d0b 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 475208d..702b836 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,32 +244,72 @@ 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).
+.It
+Your editor can be used in
+.Nm Ns
+\&'s embed terminal emulator by setting
+.Ic embed
+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
+press Ctrl-z and to resume editing press the
+.Ic edit_mail
+command again
+.Po
+default
+.Em e
+.Pc .
+.El
+.Ss Attachments
 Attachments may be handled with the
-.Em add-attachment Ns
+.Cm add-attachment Ns
 ,
-.Em remove-attachment
+.Cm remove-attachment
 commands (see below).
+.Ss Sending
 Finally, pressing
 .Cm s
-will send your message according to your settings
+(shortcut
+.Ic send_mail Ns
+) will send your message according to your settings
 .Po
 see
 .Xr meli.conf 5 COMPOSING Ns
@@ -230,36 +317,22 @@ see
 .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
-\&.
+.Ss Drafts
+To save your draft without sending it, issue
+.Em EXECUTE
+command
+.Cm close
+and select 'save as draft'.
 .sp
-Your editor can be used in
-.Nm Ns
-\&'s embed terminal emulator by setting
-.Ic embed
-to
-.Em true
-in your composing settings.
-When launched, your editor captures all input until it exits or stops.
-To stop your editor and return to
-.Nm
-issue Ctrl-z and to resume editing press the
-.Ic edit_mail
-command again (default
-.Em e Ns
-).
+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 e85b477..8d8727d 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 <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