update man page

1 files changed, 180 insertions, 73 deletions

diff --git a/meli.1 b/meli.1
index 51a7215d..1dec48ad 100644
--- a/meli.1
+++ b/meli.1
@@ -1,41 +1,63 @@
 .\" 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 July 03, 2019
+.\"
+.Dd July 29, 2019
 .Dt MELI 1
 .Os Linux
 .Sh NAME
-.Nm meli - Meli Mail User Agent.
-.Nd Meli is the Greek word for honey.
+.Nm meli
+.Nd Meli Mail User Agent. meli is the Greek word for honey.
 .Sh SYNOPSIS
-\f[C]meli\f[R]
+.Nm meli
+.Op Fl -help | h
+.Op Fl -create-config Op Ar path
+.Op Fl -config Ar path
 .Sh DESCRIPTION
 Experimental terminal mail client
+.Bl -tag -width flag -offset indent
+.It Fl -help, h
+Show help message and exit.
+.It Fl -create-config Op Ar path
+Create configuration file in
+.Pa path
+if given, or at
+.Pa $XDG_CONFIG_HOME/meli/config
+.It Fl -config Ar path
+Start meli with given configuration file.
+.El
 .Sh STARTING WITH meli
-When launched for the first time, meli will search for its configuration directory ($XDG_CONFIG_HOME/meli/). If it doesn't exist, you will be asked if you want to create one along with a sample configuration. The sample configuration ($XDG_CONFIG_HOME/meli/config) includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away.
+When launched for the first time, meli 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
+includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away.
 .Pp
-At any time, you can press `?` to show a searchable list of all available actions and shortcuts, along with every possible setting and command that your version supports.
+At any time, you can press
+.Cm \&?
+to show 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 can be toggled (default shortcut `).
+The main visual navigation tool is the left-side sidebar. The menu's visibility can be toggled (default shortcut
+.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.
-.Pp
+.Bd -literal
          ^^      .-=-=-=-.  ^^
      ^^        (`-=-=-=-=-`)         ^^
              (`-=-=-=-=-=-=-`)  ^^         ^^
@@ -49,76 +71,161 @@ 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 "subsort [subject/date] [asc/desc]"
-.It set plain/threaded/compact # set the way mailboxes are displayed
-.It sort [subject/date] [asc/desc]
-.It subsort [subject/date] [asc/desc] # this only sorts the first level of replies.
-.It close # closes closeable tabs
-.It go n # where n is a mailbox prefixed with the n number for the current account
-.It toggle_thread_snooze # don't issue notifications for thread under cursor in thread listing
-.It filter STRING # filter mailbox with STRING key. Escape exits filter results
-.It list-post # post in list of currently viewed envelope
-.It list-unsubscribe # unsubscribe automatically from list of currently viewed envelope
-.It list-archive # open list archive with xdg-open
-.It set read, set unread
-.It setenv KEY=VALUE # set environment variable KEY to VALUE
-.It printenv KEY # print environment variable KEY
+.Bl -tag -width "Cm subsort Op Ar subject | date Op asc | desc"
+.It Cm set Ar plain | threaded | compact
+set the way mailboxes are displayed
+.Bl -tag -width "threaded" -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 compact
+shows one row per thread
+.El
+.It Cm sort Ar subject | date \  Ar asc | desc
+sort mail listing
+.It Cm 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
+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
+don't issue notifications for thread under cursor in thread listing
+.It Cm filter Ar STRING
+filter mailbox with
+.Ar STRING
+key. Escape exits filter results
+.It Cm list-post
+post in list of currently viewed envelope
+.It Cm list-unsubscribe
+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
+.It Cm setenv Ar KEY=VALUE
+set environment variable
+.Ar KEY
+to
+.Ar VALUE
+.It Cm printenv KEY
+print environment variable
+.Ar KEY
 .El
 .Sh SHORTCUTS
-Non-complete list of shortcuts
-.Bl -tag -width next_account
-.It open_thread '\\n'
-.It exit_thread = 'i'
-.It create_contact = 'c'
-.It edit_contact = 'e'
-.It prev_page = PageUp,
-.It next_page = PageDown,
-.It prev_folder = 'K',
-.It next_folder = 'J',
-.It prev_account = 'l',
-.It next_account = 'h',
-.It new_mail = 'm',
-.It scroll_up = 'k',
-.It scroll_down = 'j',
-.It page_up = PageUp,
-.It page_down = PageDown,
-.It '`' toggles hiding of sidebar in mail listings
-.It '?' opens up a shortcut window that shows available actions in the current component you are using (eg mail listing, contact list, mail composing)
-.It 'm' starts a new mail composer
-.It 'R' replies to the currently viewed mail.
-.It `u` displays numbers next to urls in the body text of an email and <number>g opens the url with xdg-open
-.It <n>a opens the nth attachment.
+Non-complete list of shortcuts and their default values.
+.Bl -tag -width "create_contact" -offset indent
+.It Cm open_thread
+\&'\\n'
+.It Cm exit_thread
+\&'i'
+.It Cm create_contact
+\&'c'
+.It Cm edit_contact
+\&'e'
+.It Cm prev_page
+PageUp,
+.It Cm next_page
+PageDown
+.It Cm prev_folder
+\&'K'
+.It Cm next_folder
+\&'J'
+.It Cm prev_account
+\&'l'
+.It Cm next_account
+\&'h'
+.It Cm new_mail
+\&'m'
+.It Cm scroll_up
+\&'k'
+.It Cm scroll_down
+\&'j'
+.It Cm page_up
+PageUp
+.It Cm page_down
+PageDown
+.El
+.Bl -tag -width "<n>a" -offset indent
+.It Cm `
+toggles hiding of sidebar in mail listings
+.It Cm \&?
+opens up a shortcut window that shows available actions in the current component you are using (eg mail listing, contact list, mail composing)
+.It Cm m
+starts a new mail composer
+.It Cm R
+replies to the currently viewed mail.
+.It Cm u
+displays numbers next to urls in the body text of an email and
+.Ar n Ns Cm g
+opens the
+.Ar n Ns
+th
+url with xdg-open
+.It Ar n Ns Cm a
+opens the
+.Ar n Ns
+th
+attachment.
 .El
 .Sh EXIT STATUS
-No exit status codes are currently assigned.
-.Sh CONFORMING TO
-XDG Standard
+.Nm
+exits with 0 on a successful run. Other exit statuses are:
+.Bl -tag -width 2n
+.It 1
+catchall for general errors
+.El
 .Sh ENVIRONMENT
-.Bl -tag -width MELI_CONFIG
-.It Ev EDITOR         Specifies the editor to use
-.It Ev MELI_CONFIG  Override the configuration file
+.Bl -tag -width "Ev MELI_CONFIG" -offset indent
+.It Ev EDITOR
+Specifies the editor to use
+.It Ev MELI_CONFIG
+Override the configuration file
 .El
 .Sh FILES
 meli uses the following parts of the XDG standard:
-.Bl -tag -width XDG_CONFIG_HOME
-.It Ev XDG_CONFIG_HOME defaults to ~/.config/
-.It Ev XDG_CACHE_HOME  defaults to ~/.cache/
+.Bl -tag -width "XDG_CONFIG_HOME" -offset indent
+.It Ev XDG_CONFIG_HOME
+defaults to
+.Pa ~/.config/
+.It Ev XDG_CACHE_HOME
+defaults to
+.Pa ~/.cache/
 .El
-.Bl -tag -width $XDG_CONFIG_HOME/meli/plugins/*
-.It Pa $XDG_CONFIG_HOME/meli/ User configuration directory.
-.It Pa $XDG_CONFIG_HOME/meli/config User configuration file.
-.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 /tmp/meli/* Temporary files generated by meli.
+.Pp
+and appropriates the following locations:
+.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
+.It Pa $XDG_CONFIG_HOME/meli/
+User configuration directory.
+.It Pa $XDG_CONFIG_HOME/meli/config
+User configuration file.
+.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 /tmp/meli/*
+Temporary files generated by meli.
 .El
+.Sh SEE ALSO
+.Xr xdg-open 1
+.Sh CONFORMING TO
+XDG Standard
+.Aq https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html Ns
+, maildir
+.Aq https://cr.yp.to/proto/maildir.html
 .Sh AUTHORS
-Copyright 2017--2019 Manos Pitsidianakis (epilys\[at]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.)
+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
-<https://meli.delivery>.
-.Sh SEE ALSO
+.Aq https://meli.delivery