doc: Specify how imag-mail should look like

1 files changed, 268 insertions, 13 deletions

diff --git a/doc/src/04020-module-mails.md b/doc/src/04020-module-mails.md
index 3c46ae97..bfaed6ab 100644
--- a/doc/src/04020-module-mails.md
+++ b/doc/src/04020-module-mails.md
@@ -26,17 +26,272 @@ for the outgoing mails.
 
 The CLI of the imag-mail module is planned as follows:
 
-    imag mail track <path> [opts...]        # track a new mail, mail file passed as path
-    imag mail scan <path> [opts...]         # scan a maildir and track all untracked mails
-    imag mail box <name|path>               # work with the mailbox specified by <name|path>, name mappings from config
-    imag mail list <args...>                # list mails in a given mailbox for a given account or the default account
-    imag mail show <args...>                # open new mails in the pager
-    imag mail thread list <args...>         # list mails from a thread
-    imag mail thread show <args...>         # open new mails from a thread in the pager or call a script with them
-    imag mail new <args...>                 # craft a new mail and safe it in the <outgoing> folder
-    imag mail compose <args...>             # same as 'new'
-    imag mail send <args...>                # send emails from the outgoing folder, optionally also move them to archive boxes
-    imag mail mv <src mail> <dstbox>        # move a mail to another mailbox
-    imag mail mv thread <src mail> <dstbox> # move the thread of the mail to another mailbox
-    imag mail find <args...>                # search for a mail (by header field (msgid, from, to, cc, subject, date, date-range), body, ...)
+* imag mail
+
+  Requires configuration:
+    * mail.outgoingbox
+    * mail.accounts.<account>.maildirroot
+
+    -A, --account   - Specify the "account" to use for the opperation.
+                      A account is nothing more than a mapping of a name to a
+                      path where the Maildirs are located.  It is specified in
+                      the imag configuration file.
+                      For example:
+
+                        private -> ~/.mails/personal
+
+                      If none is specified, the configuration is searched for a
+                      "maildir" setting (where all Maildirs are found in). If
+                      there is no such setting, imag-mail fails.
+                      (or: read in documentation for --box).
+
+    -B, --box       - Specify a temporary location for a Maildir to work with.
+
+* imag mail track <path> [opts...]
+  Track a new mail, mail file passed as path
+
+    --refind        - re-find messages. Loads all messages which are known to imag
+                      and compares identifiers, to update the imag-internal cache if
+                      a mail got moved
+
+    -O, --output-id - print the store id for the new (or in case of --refind
+                      updated) imag entry
+
+* imag mail scan <path> [opts...]
+  Scan a maildir and track all untracked mails
+
+    --refind        - re-find messages. Loads all messages which are known to imag
+                      and compares identifiers, to update the imag-internal cache if
+                      a mail got moved
+
+    -O, --output-id - print the store id for the new (or in case of --refind
+                      updated) imag entry
+
+* imag mail list <args...>
+  List mails in a given mailbox for a given account or the default account
+
+    -S, --style     - print messages in a certain style
+                      Available:
+                        - 'linewise'
+                        - 'thread'
+
+    -g, --grep      - Filter by grepping for a pattern in body and subject
+
+    -d, --daterange - Filter by date(range)
+
+    -F, --filter    - Filter by passed filter
+
+        --thread    - Print only messages from the same thread as the found ones
+
+    --format=<fmt>  - Format mails for showing.
+                      --format always colorizes output (specify color in config)
+                      except when using --no-pager or piping output.
+
+                      When --tree is passed, the format is applied to the
+                      fragment _after_ the tree graphic.
+
+                      Default mode is 'default'.
+
+                      Modes:
+                        - 'subject': <Subject>
+                        - 'simple': <From>: <Subject>
+                        - 'default': <Date> - <From>: <Subject>
+                        - 'fmt:<fmt>' format with passed format
+
+                      Additional formats can be specified via the configuration
+                      file. If a format has the same name as a predefined one,
+                      the config overrides the predefined formats.
+
+    --color         - Colorize output (default).
+    --no-color      - Do never colorize output.
+
+* imag mail show <args...>
+  Show mail(s) - either in pager or by printing them to stdout.
+
+    Mails are specified by message id or imag entry
+
+    --refind        - If a imag entry is passed but the mail file is not there,
+                      try to re-find it.
+
+    --refind-in     - Same as --refind, but a path to a Maildir or a tree of
+                      Maildirs might be passed to narrow down search space.
+
+    -C, --concat    - Open all mails in one pager (by concatenating them)
+                      instead of one pager per message.
+
+    --pager         - Use pager to show mails (default).
+
+    --no-pager      - Do not use pager to show mails.
+
+    --multipager    - Pass all mails as arguments to one pager call instead of
+                      calling the pager on each mail individually (default).
+                      Only possible with --pager.
+
+    --no-multipager - Disable --multipager.
+                      Only possible with --pager.
+
+    --format=<fmt>  - Format mails for showing.
+                      --format always colorizes emails (specify color in config)
+                      except when using --no-pager or piping output.
+
+                      Modes:
+                        - 'simple': Remove headers, except
+                            From, To, Cc, Subject, Date,
+                            Message-Id/References/In-Reply-To
+                        - 'simple-imag': Same as 'simple' but also show imag
+                          entry id.
+                        - 'print': Show everything
+                        - 'full': Show everything and add imag entry id
+                        - 'minimal': Remove headers, except From, To, Cc, Subject, Date,
+                        - 'tiny': Remove headers, except From, To, Subject
+                        - 'fmt:<fmt>' format with passed format
+
+                      Additional formats can be specified via the configuration
+                      file. If a format has the same name as a predefined one,
+                      the config overrides the predefined formats.
+
+    --no-format     - Disable all formatting (same as --pretty=print and
+                      disabling color output).
+
+    --color         - Colorize output (default).
+    --no-color      - Do never colorize output.
+
+* imag mail new <args...>
+  Craft a new mail and safe it in the <outgoing> folder
+
+  Requires configuration:
+    * mail.accounts.<account>.draftbox
+    * mail.accounts.<account>.outgoingbox
+
+        --outbox    - Specify the outbox for where the new mail should be stored
+                      in, if it is not given in the config (or to override it)
+
+        --to        - Specify to whom to send.
+                      If the specified string does not contain a valid email
+                      address, `imag contact find` is used to find the email
+                      address (if not suppressed via --no-autofind).
+                      Multiple allowed.
+
+        --cc        - Specify to whom to send in CC.
+                      If the specified string does not contain a valid email
+                      address, `imag contact find` is used to find the email
+                      address (if not suppressed via --no-autofind).
+                      Multiple allowed.
+
+        --bcc       - Specify to whom to send in BCC.
+                      If the specified string does not contain a valid email
+                      address, `imag contact find` is used to find the email
+                      address (if not suppressed via --no-autofind).
+                      Multiple allowed.
+
+    --no-autofind   - Do not automatically find contacts
+                      with `imag contact find`.
+
+        --fcc       - Specify to store a copy of the mail somewhere.
+                      Multiple allowed.
+
+        --subject   - Specify subject.
+
+        --gpg-sign  - Sign with gpg.
+
+        --gpg-crypt - Crypt with gpg to all recipients.
+
+        --no-track  - Do not track new mailfile with imag.
+
+    -D, --draft     - Do not safe in "outgoing" box but rather in "draft" box.
+
+* imag mail compose <args...>
+  Same as 'new'.
+
+* imag mail fetch <args...>
+  Fetch emails
+
+  Requires configuration:
+    * mail.fetchcommand or mail.accounts.<account>.fetchcommand
+    * mail.postfetchcommand or mail.accounts.<account>.postfetchcommand (optional)
+
+    --all           - Fetch for all accounts
+    --boxes         - Fetch only some boxes (does not work with --all)
+
+* imag mail send <args...>
+  Send emails from the outgoing folder, also move them to 'sent' boxes
+
+  Requires configuration:
+    * mail.accounts.<account>.outgoingbox
+    * mail.accounts.<account>.sentbox
+    * mail.sendcommand or mail.accounts.<account>.sendcommand
+    * mail.postsendcommand or mail.accounts.<account>.postsendcommand (optional)
+
+    --outbox        - Specify the outbox for where the mails that are about to
+                      be send are stored in, if it is not given in the config
+                      (or to override it).
+
+    --sentbox       - Specify the sentbox for where the sent mails should be
+                      moved after sending them, if it is not given in the config
+                      (or to override it).
+
+    --no-move-sent  - Do not move mail to the "sent" folder after sending it.
+
+    --confirm       - Confirm each mail before sending (default).
+
+    --no-confirm    - Do not confirm each mail before sending.
+
+    --no-track      - Do not track mailfile with imag. Does only work if `imag
+                      mail new` was invoked with `--no-track` (so that the mail
+                      is not tracked already).
+
+* imag mail mv <src mail> <dstbox>
+  Move a mail to another mailbox
+
+    --thread        - Move the complete thread of emails belonging to the
+                      specified mail.
+
+    --no-track      - Do not track new mailfile with imag. Does not work if
+                      mailfile is already tracked with imag.
+
+* imag mail find <args...>
+  Search for a mail (by header field (msgid, from, to, cc, subject, date,
+  date-range), body, ...)
+
+    --msgid
+    --no-msgid
+    --from
+    --no-from
+    --to
+    --no-to
+    --cc
+    --no-cc
+    --subject
+    --no-subject
+    --date
+    --no-date
+    --body
+    --no-body
+    --daterange     - Toggle where to look at
+
+    --print-entryid     - Print imag entry id when finding mail
+    --no-print-entryid  - Do not print imag entry id when finding mail (default).
+
+    --print=<what>  - What to print for the found mails.
+                      Valid values:
+                        - msgid
+                        - subject
+                        - from
+                        - cc
+                        - to
+                        - date
+                        - filepath (default)
+
+* imag mail reply <args...>
+  Reply to an email.
+
+  Requires configuration: mail.accounts.<account>.outgoingbox
+
+  Specify the mail to reply to by msgid, filepath or imag entry id.
+
+    --add-to
+    --add-cc
+    --add-bcc       - Add another recipient. Multiple allowed.
+
+    --no-track      - Do not track new mailfile with imag.