 ;;; db-mail.el --- Utility Functions for sending mail -*- lexical-binding: t -*-
 
 ;;; Commentary:
+
+;; This package consists mostly of utility functions for sending and editing
+;; mail, fixing some issues, and extending Gnus in the way I like it.  However,
+;; the most important feature of is an abstract way to hande remote mail
+;; accounts.  Theses are stored in the variable `db/mail-accounts’ and consist
+;; of various entries denoting how to read mail via IMAP (POP not supported) and
+;; how to send mail via SMTP (server, port, protocol, …).  Based on the entries
+;; in this variable, appropriate settings of `gnus-secondary-select-methods’ are
+;; derived automatically by the custom setter of `db/mail-accounts’.  Then when
+;; inside Gnus, the mail can be read without further configuration.  Note that
+;; when the "IMAP address" of an entry in `db/mail-accounts’ is empty, it will
+;; not be included as an IMAP account in `gnus-secondary-select-methods’.  This
+;; let’s you specify mail accounts that can be used for sending mail, but that
+;; are read not directly via IMAP, but by other means (POP, offlineimap, …).
+
+;; When sending mail, `db/mail-accounts’ is used to determine settings of the
+;; relevant variables from `smtpmail’ based on the current value of the "From: "
+;; header entry in the mail.  If this header entry is set correctly, send
+;; `db/set-smtp-server-from-header’ will set these variables automatically.  To
+;; make this work, however, two things have to be done:
+;;
+;; - Ensure that the "From: " header is set correctly.  In Gnus this can be done
+;;   by configuring `gnus-posting-style’ accordingly.
+;;
+;; - Make sure `db/set-smtp-server-from-header’ is called when sending mail.
+;;   Currently, this function is written to be added as an around advice for
+;;   `smtpmail-via-smtp’.  In the future, this function might be changed to be a
+;;   valid value for `send-mail-function’
+
+;; All this functionality is provided under "Mail related customizations".  The
+;; other headlines provide the aforementioned utility functions.
 
 ;;; Code:
 

      (goto-char (point-max))
      (apply orig-fun args))))

(provide 'db-mail)
;;; db-mail ends here

           (integer :tag "SMTP Service Port")
           (string :tag "SMTP Login Name")))
  :set #'db/mail-accounts--set-value)

(defun db/set-smtp-server-from-header (orig-fun &rest args)
  "Choose smtp-settings dynamically, based on the From: header
