emacs
/
mu
mirror of https://github.com/djcb/mu.git
1
0
Fork 0
Code Issues Releases Wiki Activity

improve doc-strings 

The first sentence should summarize the variable's or function's
purpose and it should fit on the first line.  Change existing
doc-string by:

* Move first sentence onto first line even if that makes it _a bit_
  long.
* Move additional notes out of first sentence and add them later,
  possibly as complete sentences.
* If I am uncertain whether doing the above would alter the meaning,
  _don't_ do it.
* If fitting the initial sentence on the first line would require a
  complete rewrite of the doc-string _don't_ do so unless it is very
  easy to do.
* Remove indentation from second and later lines if it is there to
  align them with the first in the source code, instead of in
  `describe-*' output.
* Make "pullet point" lists a bit more consistent.

Obviously this does not fix all problems but it's a start.
This commit is contained in:
Jonas Bernoulli 2012-11-10 14:01:17 +01:00
parent b92d826808
commit 8a3d4c27de
13 changed files with 397 additions and 368 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
mu4e/mu4e-actions.el
View File

@ -37,8 +37,8 @@
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun mu4e-action-count-lines (msg)
"Count the number of lines in the e-mail message. Works for
headers view and message-view."
"Count the number of lines in the e-mail message.
Works for headers view and message-view."
(message "Number of lines: %s"
(shell-command-to-string
(concat "wc -l < " (shell-quote-argument (mu4e-message-field msg :path))))))
@ -53,8 +53,8 @@ headers view and message-view."
"Path to the msg2pdf toy.")
(defun mu4e-action-view-as-pdf (msg)
"Convert the message to pdf, then show it. Works for the message
view."
"Convert the message to pdf, then show it.
Works for the message view."
(unless (file-executable-p mu4e-msg2pdf)
(mu4e-error "msg2pdf not found; please set `mu4e-msg2pdf'"))
(let* ((pdf
@ -74,8 +74,9 @@ view."
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun mu4e-action-view-in-browser (msg)
"View the body of the message in a web browser. You can influence
the browser to use with the variable `browse-url-generic-program'."
"View the body of the message in a web browser.
You can influence the browser to use with the variable
`browse-url-generic-program'."
(let* ((html (mu4e-message-field msg :body-html))
(txt (mu4e-message-field msg :body-txt))
(tmpfile (format "%s%x.html" temporary-file-directory (random t))))
@ -127,8 +128,8 @@ with `mu4e-compose-attach-captured-message'."
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defvar mu4e-org-contacts-file nil
"File to store contact information for org-contacts. Needed by
`mu4e-action-add-org-contact'.")
"File to store contact information for org-contacts.
Needed by `mu4e-action-add-org-contact'.")
(eval-when-compile ;; silence compiler warning about free variable
(unless (require 'org-capture nil 'noerror)

26
mu4e/mu4e-compose.el
View File

@ -107,16 +107,16 @@ sent folder."
:group 'mu4e-compose)
(defvar mu4e-compose-pre-hook nil
"Hook run just *before* message composition starts. If the
compose-type is either /reply/ or /forward/, the variable
"Hook run just *before* message composition starts.
If the compose-type is either /reply/ or /forward/, the variable
`mu4e-compose-parent-message' points to the message replied to /
being forwarded / edited.")
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun mu4e-compose-attach-captured-message ()
"Insert the last captured message (through
`mu4e-action-capture-message') file as an attachment."
"Insert the last captured message file as an attachment.
Messages are captured with `mu4e-action-capture-message'."
(interactive)
(unless mu4e-captured-message
(mu4e-warn "No message has been captured"))
@ -145,8 +145,8 @@ being forwarded / edited.")
;; `mu4e-sent-messages-behavior'.
(defun mu4e~compose-setup-fcc-maybe ()
"Maybe setup Fcc, based on `mu4e-sent-messages-behavior'. If
needed, set the Fcc header, and register the handler function."
"Maybe setup Fcc, based on `mu4e-sent-messages-behavior'.
If needed, set the Fcc header, and register the handler function."
(let* ((mdir
(case mu4e-sent-messages-behavior
(delete nil)
@ -174,8 +174,8 @@ needed, set the Fcc header, and register the handler function."
(defun mu4e~compose-register-message-save-hooks ()
"Just before saving, we remove the mail-header-separator; just
after saving we restore it; thus, the separator should never
appear on disk."
after saving we restore it; thus, the separator should never
appear on disk."
(add-hook 'before-save-hook
'mu4e~draft-remove-mail-header-separator nil t)
(add-hook 'after-save-hook
@ -442,9 +442,9 @@ for draft messages."
(mu4e-compose 'forward))
(defun mu4e-compose-edit ()
"Edit the draft message at point in the headers buffer. This is
only possible if the message at point is, in fact, a draft
message."
"Edit the draft message at point in the headers buffer.
This is only possible if the message at point is, in fact, a
draft message."
(interactive)
(mu4e-compose 'edit))
@ -457,8 +457,8 @@ message."
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; address completion; inspired by org-contacts.el
(defun mu4e~compose-complete-contact (&optional start)
"Complete the text at START with a contact (ie. either 'name
<email>' or 'email')."
"Complete the text at START with a contact.
Ie. either 'name <email>' or 'email')."
(interactive)
(let ((mail-abbrev-mode-regexp mu4e~compose-address-fields-regexp)
(eoh ;; end-of-headers

39
mu4e/mu4e-draft.el
View File

@ -38,16 +38,16 @@
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun mu4e~draft-user-agent-construct ()
"Return the User-Agent string for mu4e. This is either the value
of `mu4e-user-agent', or, if not set, a string based on the versions
of mu4e and emacs."
"Return the User-Agent string for mu4e.
This is either the value of `mu4e-user-agent', or, if not set, a
string based on the versions of mu4e and emacs."
(format "mu4e %s; emacs %s" mu4e-mu-version emacs-version))
(defun mu4e~draft-cite-original (msg)
"Return a cited version of the original message MSG (ie., the
plist). This function use gnus' `message-cite-function', and as
such all its settings apply."
"Return a cited version of the original message MSG as a plist.
This function use gnus' `message-cite-function', and as such all
its settings apply."
(with-temp-buffer
(when (fboundp 'mu4e-view-message-text) ;; keep bytecompiler happy
(insert (mu4e-view-message-text msg))
@ -61,8 +61,8 @@ such all its settings apply."
(buffer-string))))
(defun mu4e~draft-header (hdr val)
"Return a header line of the form HDR: VAL\n. If VAL is nil,
return nil."
"Return a header line of the form \"HDR: VAL\".
If VAL is nil, return nil."
(when val (format "%s: %s\n" hdr val)))
(defun mu4e~draft-references-construct (msg)
@ -97,9 +97,10 @@ e-mail addresses. If LST is nil, returns nil."
lst ", ")))
(defun mu4e~draft-address-cell-equal (cell1 cell2)
"Return t if cell1 and cell2 have the same e-mail
address (case-insensitively), nil otherwise. cell1 and cell2 are
cons cells (NAME . EMAIL)."
"Return t if CELL1 and CELL2 have the same e-mail address.
The comparison is done case-insensitively. If the cells done
match return nil. CELL1 and CELL2 are cons cells of the
form (NAME . EMAIL)."
(string=
(downcase (or (cdr cell1) ""))
(downcase (or (cdr cell2) ""))))
@ -174,9 +175,9 @@ nil, function returns nil."
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun mu4e~draft-insert-mail-header-separator ()
"Insert `mail-header-separator' in the first empty line of the
message. message-mode needs this line to know where the headers end
and the body starts. Note, in `mu4e-compose-mode, we use
"Insert `mail-header-separator' in the first empty line of the message.
`message-mode' needs this line to know where the headers end and
the body starts. Note, in `mu4e-compose-mode', we use
`before-save-hook' and `after-save-hook' to ensure that this
separator is never written to the message file. Also see
`mu4e-remove-mail-header-separator'."
@ -211,8 +212,8 @@ never hits the disk. Also see `mu4e~draft-insert-mail-header-separator."
(replace-match "")))))
(defun mu4e~draft-user-wants-reply-all (origmsg)
"Ask user whether she wants to reply to *all* recipients if there
are more than 1 (based on ORIGMSG)."
"Ask user whether she wants to reply to *all* recipients.
If there is just one recipient of ORIGMSG do nothing."
(let* ((recipnum
(+ (length (mu4e~draft-create-to-lst origmsg))
(length (mu4e~draft-create-cc-lst origmsg t))))
@ -226,8 +227,8 @@ are more than 1 (based on ORIGMSG)."
(eq response 'all)))
(defun mu4e~draft-message-filename-construct (&optional flagstr)
"Construct a randomized name for a message file with flags FLAGSTR; it looks
something like
"Construct a randomized name for a message file with flags FLAGSTR.
It looks something like
<time>-<random>.<hostname>:2,
You can append flags."
(let* ((hostname
@ -307,7 +308,7 @@ You can append flags."
(defvar mu4e~draft-drafts-folder nil
"The drafts-folder for this compose buffer, based on
mu4e-drafts-folder', which will be evaluated once.")
mu4e-drafts-folder', which will be evaluated once.")
(defun mu4e-draft-open (compose-type &optional msg)
"Open a draft file for a new message (when COMPOSE-TYPE is reply, forward or new),

152
mu4e/mu4e-headers.el
View File

@ -67,14 +67,14 @@ rightmost (last) field."
:group 'mu4e-headers)
(defcustom mu4e-headers-date-format "%x"
"Date format to use in the headers view, in the format of
`format-time-string'."
"Date format to use in the headers view.
In the format of `format-time-string'."
:type 'string
:group 'mu4e-headers)
(defcustom mu4e-headers-time-format "%X"
"Time format to use in the headers view, in the format of
`format-time-string'."
"Time format to use in the headers view.
In the format of `format-time-string'."
:type 'string
:group 'mu4e-headers)
@ -122,9 +122,8 @@ indexing operation showed changes."
(defvar mu4e-headers-actions
'( ("capture message" . mu4e-action-capture-message))
"List of actions to perform on messages in the headers list. The actions
are of the form:
(NAME SHORTCUT FUNC) where:
"List of actions to perform on messages in the headers list.
The actions are of the form (NAME SHORTCUT FUNC) where:
* NAME is the name of the action (e.g. \"Count lines\")
* SHORTCUT is a one-character shortcut to call this action
* FUNC is a function which receives a message plist as an argument.")
@ -151,20 +150,21 @@ match.
PREDICATE-FUNC as PARAM. This is useful for getting user-input.")
(defvar mu4e-headers-sortfield :date
"Field to sort the headers by. Field must be a symbol, one of:
:date, :subject, :size, :prio, :from, :to.")
"Field to sort the headers by.
Field must be a symbol, one of: :date, :subject, :size, :prio,
:from, :to.")
(defvar mu4e-headers-sort-revert t
"Whether to revert the sort-order, i.e. Z->A instead of A-Z. When
sorting by date, it's useful to go from biggest to smallest, so
newest messages come first.")
"Whether to revert the sort-order.
i.e. Z>A instead of A>Z. When sorting by date, it's useful to go
from biggest to smallest, so newest messages come first.")
(defvar mu4e-headers-show-threads t
"Whether to show threads in the headers list.")
(defvar mu4e-headers-full-search nil
"Whether to show all results (or just up to
`mu4e-search-results-limit')")
"Whether to show all results.
If this is nil show results up to `mu4e-search-results-limit')")
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@ -173,10 +173,10 @@ newest messages come first.")
;; docid cookies
(defconst mu4e~headers-docid-pre (purecopy "\376")
"Each header starts (invisibly) with the `mu4e~headers-docid-pre',
followed by the docid, followed by `mu4e~headers-docid-post'.")
followed by the docid, followed by `mu4e~headers-docid-post'.")
(defconst mu4e~headers-docid-post (purecopy "\377")
"Each header starts (invisibly) with the `mu4e~headers-docid-pre',
followed by the docid, followed by `mu4e~headers-docid-post'.")
followed by the docid, followed by `mu4e~headers-docid-post'.")
(defvar mu4e~headers-view-win nil
"The view window connected to this headers view.")
@ -188,8 +188,8 @@ newest messages come first.")
("zsize" . :size)
("subject" . :subject)
("to" . :to))
"List of cells describing the various sort-options (in the format
needed for `mu4e-read-option'.")
"List of cells describing the various sort-options.
In the format needed for `mu4e-read-option'.")
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@ -299,11 +299,11 @@ into a string."
" "))))
(defsubst mu4e~headers-flags-str (flags)
"Get a display string for the flags; note, there is
`mu4e-flags-to-string' but that is for internal use; this function
is for display. (This difference is significant, since internally,
the Maildir spec determines what the flags look like, while our
display may be different)."
"Get a display string for the flags.
Note that `mu4e-flags-to-string' is for internal use only; this
function is for display. (This difference is significant, since
internally, the Maildir spec determines what the flags look like,
while our display may be different)."
(let ((str)
(get-prefix
(lambda (cell) (if mu4e-use-fancy-chars (cdr cell) (car cell)))))
@ -327,13 +327,13 @@ display may be different)."
(defconst mu4e-headers-from-or-to-prefix '("" . "To ")
"Prefix for the :from-or-to field when it is showing,
respectively, From: or To:. It's a cons cell with the car element
being the From: prefix, the cdr element the To: prefix.")
"Prefix for the :from-or-to field.
It's a cons cell with the car element being the From: prefix, the
cdr element the To: prefix.")
(defsubst mu4e~headers-from-or-to (msg)
"When the from address for message MSG is one of the the user's addresses,
(as per `mu4e-user-mail-address-list'), show the To address;
\(as per `mu4e-user-mail-address-list'), show the To address;
otherwise ; show the from address; prefixed with the appropriate
`mu4e-headers-from-or-to-prefix'."
(let ((addr (cdr-safe (car-safe (mu4e-message-field msg :from)))))
@ -344,15 +344,16 @@ otherwise ; show the from address; prefixed with the appropriate
(mu4e~headers-contact-str (mu4e-message-field msg :from))))))
(defsubst mu4e~headers-human-date (msg)
"Show a 'human' date -- that is, if the date is today, show the
date, otherwise, show the time. The formats used for date and time
are `mu4e-headers-date-format' and `mu4e-headers-time-format'."
"Show a 'human' date.
If the date is today, show the time, otherwise, show the
date. The formats used for date and time are
`mu4e-headers-date-format' and `mu4e-headers-time-format'."
(let ((date (mu4e-msg-field msg :date)))
(if (= (nth 3 (decode-time date)) (nth 3 (decode-time (current-time))))
(format-time-string mu4e-headers-time-format date)
(format-time-string mu4e-headers-date-format date))))
;; note: this function is very performance-sensitive
;; note: this function is very performance-sensitive
(defun mu4e~headers-header-handler (msg &optional point)
"Create a one line description of MSG in this buffer, at POINT,
if provided, or at the end of the buffer otherwise."
@ -685,8 +686,8 @@ user-interaction ongoing."
"The highlighted docid")
(defun mu4e~headers-highlight (docid)
"Highlight the header with DOCID, or do nothing if it's not
found. Also, unhighlight any previously highlighted headers."
"Highlight the header with DOCID, or do nothing if it's not found.
Also, unhighlight any previously highlighted headers."
(with-current-buffer mu4e~headers-buffer
(save-excursion
;; first, unhighlight the previously highlighted docid, if any
@ -803,8 +804,9 @@ text-property `msg'."
'docid docid 'msg msg)))))))
(defun mu4e~headers-remove-header (docid &optional ignore-missing)
"Remove header with DOCID at POINT; when IGNORE-MISSING is
non-nill, don't raise an error when the docid is not found."
"Remove header with DOCID at point.
When IGNORE-MISSING is non-nill, don't raise an error when the
docid is not found."
(with-current-buffer mu4e~headers-buffer
(if (mu4e~headers-goto-docid docid)
(let ((inhibit-read-only t))
@ -866,9 +868,9 @@ of `mu4e-split-view', and return a window for the message view."
;; search-based marking
(defun mu4e-headers-for-each (func)
"Call FUNC for each header, moving point to the header. FUNC
takes one argument msg, the msg s-expression for the corresponding
header."
"Call FUNC for each header, moving point to the header.
FUNC takes one argument, the msg s-expression for the
corresponding header."
(save-excursion
(goto-char (point-min))
(while (search-forward mu4e~headers-docid-pre nil t)
@ -942,8 +944,9 @@ matching messages with that mark."
(defun mu4e-headers-mark-thread (&optional subthread)
"Mark the thread at point, if SUBTHREAD is non-nil, marking is
limited to the message at point and its descendants."
"Mark the thread at point.
If SUBTHREAD is non-nil, marking is limited to the message at
point and its descendants."
;; the tread id is shared by all messages in a thread
(interactive "P")
(let* ((msg (mu4e-message-at-point))
@ -989,9 +992,10 @@ limited to the message at point and its descendants."
"Maximum size for the query stacks.")
(defun mu4e~headers-push-query (query where)
"Push QUERY to one of the query stacks; WHERE is a symbol telling
us where to push; it's a symbol, either 'future or
'past. Functional also removes duplicats, limits the stack size."
"Push QUERY to one of the query stacks.
WHERE is a symbol telling us where to push; it's a symbol, either
'future or 'past. Functional also removes duplicats, limits the
stack size."
(let ((stack
(case where
(past mu4e~headers-query-past)
@ -1010,8 +1014,9 @@ us where to push; it's a symbol, either 'future or
(future (setq mu4e~headers-query-future stack))))))
(defun mu4e~headers-pop-query (whence)
"Pop a query from the stack. WHENCE is a symbol telling us where
to get it from; it's a symbol, either 'future or 'past."
"Pop a query from the stack.
WHENCE is a symbol telling us where to get it from; it's a
symbol, either 'future or 'past."
(case whence
(past
(unless mu4e~headers-query-past
@ -1085,8 +1090,9 @@ the last search expression."
(defun mu4e-headers-change-sorting (&optional dont-refresh)
"Interactively change the sorting/threading parameters. With prefix-argument,
do _not_ refresh the last search with the new parameters."
"Interactively change the sorting/threading parameters.
With prefix-argument, do _not_ refresh the last search with the
new parameters."
(interactive "P")
(let* ((sortfield
(mu4e-read-option "Sortfield: " mu4e~headers-sortfield-choices))
@ -1105,9 +1111,9 @@ do _not_ refresh the last search with the new parameters."
(mu4e-headers-rerun-search))))
(defun mu4e-headers-toggle-threading (&optional dont-refresh)
"Toggle threading on/off for the search results. With prefix-argument,
do _not_ refresh the last search with the new setting for
threading."
"Toggle threading on/off for the search results.
With prefix-argument, do _not_ refresh the last search with the
new setting for threading."
(interactive "P")
(setq mu4e-headers-show-threads (not mu4e-headers-show-threads))
(mu4e-message "Threading turned %s%s"
@ -1118,9 +1124,9 @@ threading."
(mu4e-headers-rerun-search)))
(defun mu4e-headers-toggle-full-search (&optional dont-refresh)
"Toggle full-search on/off for the search results. With prefix-argument,
do _not_ refresh the last search with the new setting for
threading."
"Toggle full-search on/off for the search results.
With prefix-argument, do _not_ refresh the last search with the
new setting for threading."
(interactive "P")
(setq mu4e-headers-full-search (not mu4e-headers-full-search))
(mu4e-message "Full search turned %s%s"
@ -1147,11 +1153,12 @@ threading."
mu4e~headers-loading-buf)
(defun mu4e-headers-view-message ()
"View message at point. If there's an existing window for the
view, re-use that one. If not, create a new one, depending on the
value of `mu4e-split-view': if it's a symbol `horizontal' or
`vertical', split the window accordingly; if it is nil, replace the
current window. "
"View message at point.
If there's an existing window for the view, re-use that one. If
not, create a new one, depending on the value of
`mu4e-split-view': if it's a symbol `horizontal' or `vertical',
split the window accordingly; if it is nil, replace the current
window. "
(interactive)
(unless (eq major-mode 'mu4e-headers-mode)
(mu4e-error "Must be in mu4e-headers-mode (%S)" major-mode))
@ -1177,9 +1184,9 @@ current window. "
(mu4e-headers-search mu4e~headers-last-query))
(defun mu4e~headers-query-navigate (whence)
"Execute the previous query from the query stacks. WHENCE
determines where the query is taken from and is a symbol, either
`future' or `past'."
"Execute the previous query from the query stacks.
WHENCE determines where the query is taken from and is a symbol,
either `future' or `past'."
(let ((query (mu4e~headers-pop-query whence))
(where (if (eq whence 'future) 'past 'future)))
(when query
@ -1232,16 +1239,18 @@ docid. Otherwise, return nil."
docid)))
(defun mu4e-headers-next (&optional n)
"Move point to the next message header. If this succeeds, return
the new docid. Otherwise, return nil. Optionally, takes an integer
N (prefix argument), to the Nth next header."
"Move point to the next message header.
If this succeeds, return the new docid. Otherwise, return nil.
Optionally, takes an integer N (prefix argument), to the Nth next
header."
(interactive "P")
(mu4e~headers-move (or n 1)))
(defun mu4e-headers-prev (&optional n)
"Move point to the previous message header. If this succeeds, return
the new docid. Otherwise, return nil. Optionally, takes an integer
N (prefix argument), to the Nth previous header."
"Move point to the previous message header.
If this succeeds, return the new docid. Otherwise, return nil.
Optionally, takes an integer N (prefix argument), to the Nth
previous header."
(interactive "P")
(mu4e~headers-move (- (or n 1))))
@ -1274,8 +1283,8 @@ N. Otherwise, don't do anything."
(incf mu4e-headers-visible-columns n)))))))
(defun mu4e-headers-action ()
"Ask user what to do with message-at-point, then do it. The
actions are specified in `mu4e-headers-actions'."
"Ask user what to do with message-at-point, then do it.
The actions are specified in `mu4e-headers-actions'."
(interactive)
(let ((msg (mu4e-message-at-point))
(actionfunc (mu4e-read-option "Action: " mu4e-headers-actions)))
@ -1289,8 +1298,9 @@ region if there is a region, then move to the next message."
(mu4e-headers-next))
(defun mu4e~headers-quit-buffer ()
"Quit the mu4e-headers buffer. This is a rather complex function,
to ensure we don't disturb other windows."
"Quit the mu4e-headers buffer.
This is a rather complex function, to ensure we don't disturb
other windows."
(interactive)
(unless (eq major-mode 'mu4e-headers-mode)
(mu4e-error "Must be in mu4e-headers-mode (%S)" major-mode))

8
mu4e/mu4e-main.el
View File

@ -69,10 +69,10 @@
(defun mu4e~main-action-str (str &optional func-or-shortcut)
"Highlight the first occurence of [..] in STR. If
FUNC-OR-SHORTCUT is non-nil and if it is a function, call it when
STR is clicked (using RET or mouse-2); if FUNC-OR-SHORTCUT is a
string, execute the corresponding keyboard action when it is
"Highlight the first occurence of [..] in STR.
If FUNC-OR-SHORTCUT is non-nil and if it is a function, call it
when STR is clicked (using RET or mouse-2); if FUNC-OR-SHORTCUT
is a string, execute the corresponding keyboard action when it is
clicked."
(let ((newstr
(replace-regexp-in-string

30
mu4e/mu4e-mark.el
View File

@ -83,11 +83,11 @@ where
(clrhash mu4e~mark-map))
(defun mu4e-mark-at-point (mark &optional target)
"Mark (or unmark) message at point. MARK specifies the
mark-type. For `move'-marks and `trash'-marks there is also the
TARGET argument, which specifies to which maildir the message is to
be moved/trashed. The function works in both headers buffers and
message buffers.
"Mark (or unmark) message at point.
MARK specifies the mark-type. For `move'-marks and `trash'-marks
there is also the TARGET argument, which specifies to which
maildir the message is to be moved/trashed. The function works in
both headers buffers and message buffers.
The following marks are available, and the corresponding props:
@ -201,8 +201,9 @@ headers in the region. Optionally, provide TARGET (for moves)."
(mu4e-mark-at-point (car markcell) (cdr markcell)))))))
(defun mu4e~mark-get-markpair (prompt &optional allow-something)
"Ask user for a mark; return (MARK . TARGET). If ALLOW-SOMETHING
is non-nil, allow the 'something' pseudo mark as well."
"Ask user for a mark; return (MARK . TARGET).
If ALLOW-SOMETHING is non-nil, allow the 'something' pseudo mark
as well."
(let* ((marks '( ("refile" . refile)
("move" . move)
("dtrash" . trash)
@ -222,8 +223,9 @@ is non-nil, allow the 'something' pseudo mark as well."
(defun mu4e-mark-resolve-deferred-marks ()
"Check if there are any deferred ('something') marks. If there are such marks,
replace them with a _real_ mark (ask the user which one)."
"Check if there are any deferred ('something') marks.
If there are such marks, replace them with a _real_ mark (ask the
user which one)."
(interactive)
(let ((markpair))
(maphash
@ -248,11 +250,11 @@ replace them with a _real_ mark (ask the user which one)."
(defun mu4e-mark-execute-all (&optional no-confirmation)
"Execute the actions for all marked messages in this
buffer. After the actions have been executed succesfully, the
affected messages are *hidden* from the current header list. Since
the headers are the result of a search, we cannot be certain that
the messages no longer matches the current one - to get that
"Execute the actions for all marked messages in this buffer.
After the actions have been executed succesfully, the affected
messages are *hidden* from the current header list. Since the
headers are the result of a search, we cannot be certain that the
messages no longer matches the current one - to get that
certainty, we need to rerun the search, but we don't want to do
that automatically, as it may be too slow and/or break the users
flow. Therefore, we hide the message, which in practice seems to

39
mu4e/mu4e-message.el
View File

@ -35,26 +35,29 @@
(defcustom mu4e-html2text-command nil
"Shell command that converts HTML from stdin into plain text on
stdout. If this is not defined, the emacs `html2text' tool will be
used when faced with html-only message. If you use htmltext, it's
recommended you use \"html2text -utf8 -width 72\"."
"Shell command that converts from html to plain text.
The command has to read html from stdin and output plain text on
stdout. If this is not defined, the emacs `html2text' tool will
be used when faced with html-only message. If you use htmltext,
it's recommended you use \"html2text -utf8 -width 72\"."
:type 'string
:group 'mu4e-view
:safe 'stringp)
(defcustom mu4e-view-prefer-html nil
"Whether to base the body display on the HTML-version of the
e-mail message (if there is any."
"Whether to base the body display on the html-version.
If the e-mail message has no html-version the plain-text version
is always used."
:type 'boolean
:group 'mu4e-view)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defsubst mu4e-message-field-raw (msg field)
"Retrieve FIELD from message plist MSG. FIELD is one
of :from, :to, :cc, :bcc, :subject, :data, :message-id, :path, :maildir,
:priority, :attachments, :references, :in-reply-to, :body-txt, :body-html
"Retrieve FIELD from message plist MSG.
FIELD is one of :from, :to, :cc, :bcc, :subject, :data,
:message-id, :path, :maildir, :priority, :attachments,
:references, :in-reply-to, :body-txt, :body-html
Returns `nil' if the field does not exist.
@ -128,16 +131,18 @@ there is no message at point."
(unless noerror (mu4e-warn "No message at point")))))
(defsubst mu4e-message-field-at-point (field)
"Get the field FIELD from the message at point; equivalent to
(mu4e-message-field (mu4e-message-at-point FIELD))."
"Get the field FIELD from the message at point.
This is equivalent to:
(mu4e-message-field (mu4e-message-at-point) FIELD)."
(mu4e-message-field (mu4e-message-at-point) field))
(defun mu4e-message-body-text (msg)
"Get the body in text form for this message, which is either :body-txt,
or if not available, :body-html converted to text. By default, it
uses the emacs built-in `html2text'. Alternatively, if
`mu4e-html2text-command' is non-nil, it will use that. Normally,
function prefers the text part, but this can be changed by setting
"Get the body in text form for this message.
This is either :body-txt, or if not available, :body-html
converted to text. By default, it uses the emacs built-in
`html2text'. Alternatively, if `mu4e-html2text-command' is
non-nil, it will use that. Normally, function prefers the text
part, but this can be changed by setting
`mu4e-view-prefer-html'."
(let* ((txt (mu4e-message-field msg :body-txt))
(html (mu4e-message-field msg :body-html))
@ -203,7 +208,7 @@ match."
(defsubst mu4e-message-part-field (msgpart field)
"Get some field in a message part; a part would look something like:
(:index 2 :name \"photo.jpg\" :mime-type \"image/jpeg\" :size 147331)."
(:index 2 :name \"photo.jpg\" :mime-type \"image/jpeg\" :size 147331)."
(plist-get msgpart field))

107
mu4e/mu4e-proc.el
View File

@ -32,8 +32,7 @@
;; internal vars
(defvar mu4e~proc-buf nil
"Buffer (string) for data received from
the backend.")
"Buffer (string) for data received from the backend.")
(defconst mu4e~proc-name " *mu4e-proc*"
"Name of the server process, buffer.")
(defvar mu4e~proc-process nil
@ -42,16 +41,16 @@ the backend.")
;; dealing with the length cookie that precedes expressions
(defconst mu4e~cookie-pre "\376"
"Each expression we get from the backend (mu server) starts with
a length cookie:
<`mu4e~cookie-pre'><length-in-hex><`mu4e~cookie-post'>.")
a length cookie:
<`mu4e~cookie-pre'><length-in-hex><`mu4e~cookie-post'>.")
(defconst mu4e~cookie-post "\377"
"Each expression we get from the backend (mu server) starts with
a length cookie:
<`mu4e~cookie-pre'><length-in-hex><`mu4e~cookie-post'>.")
a length cookie:
<`mu4e~cookie-pre'><length-in-hex><`mu4e~cookie-post'>.")
(defconst mu4e~cookie-matcher-rx
(purecopy (concat mu4e~cookie-pre "\\([[:xdigit:]]+\\)" mu4e~cookie-post))
"Regular expression matching the length cookie. Match 1 will be
the length (in hex).")
"Regular expression matching the length cookie.
Match 1 will be the length (in hex).")
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@ -98,13 +97,13 @@ the length (in hex).")
t))
(defsubst mu4e~proc-eat-sexp-from-buf ()
"'Eat' the next s-expression from `mu4e~proc-buf'. Note: this is a string,
not an emacs-buffer. `mu4e~proc-buf gets its contents from the
mu-servers in the following form:
"'Eat' the next s-expression from `mu4e~proc-buf'.
Note: this is a string, not an emacs-buffer. `mu4e~proc-buf gets
its contents from the mu-servers in the following form:
<`mu4e~cookie-pre'><length-in-hex><`mu4e~cookie-post'>
Function returns this sexp, or nil if there was
none. `mu4e~proc-buf' is updated as well, with all processed sexp
data removed."
Function returns this sexp, or nil if there was none.
`mu4e~proc-buf' is updated as well, with all processed sexp data
removed."
(ignore-errors ;; the server may die in the middle...
;; mu4e~cookie-matcher-rx:
;; (concat mu4e~cookie-pre "\\([[:xdigit:]]+\\)]" mu4e~cookie-post)
@ -129,9 +128,9 @@ data removed."
(defsubst mu4e~proc-filter (proc str)
"A process-filter for the 'mu server' output; it accumulates the
strings into valid sexps by checking of the ';;eox' end-of-sexp
marker, and then evaluating them.
"A process-filter for the 'mu server' output.
It accumulates the strings into valid sexps by checking of the
';;eox' end-of-sexp marker, and then evaluating them.
The server output is as follows:
@ -267,8 +266,7 @@ The server output is as follows:
;;(defconst mu4e-xapian-empty 19 "Error code: xapian is empty/non-existent")
(defun mu4e~proc-sentinel (proc msg)
"Function that will be called when the mu-server process
terminates."
"Function that will be called when the mu-server process terminates."
(let ((status (process-status proc)) (code (process-exit-status proc)))
(setq mu4e~proc-process nil)
(setq mu4e~proc-buf "") ;; clear any half-received sexps
@ -291,7 +289,8 @@ terminates."
(error "Something bad happened to the mu server process")))))
(defsubst mu4e~proc-send-command (frm &rest args)
"Send as command to the mu server process; start the process if needed."
"Send as command to the mu server process.
Start the process if needed."
(unless (mu4e~proc-running-p)
(mu4e~proc-start))
(let ((cmd (apply 'format frm args)))
@ -313,20 +312,21 @@ sexp, which are handled my `mu4e-error-func', respectively."
(mu4e~proc-send-command "remove docid:%d" docid))
(defun mu4e~proc-escape-query (query)
"Escape the query QUERY for transport, in particular, backslashes
and double-quotes."
"Escape the query QUERY for transport.
In particular, backslashes and double-quotes."
(let ((esc (replace-regexp-in-string "\\\\" "\\\\\\\\" query)))
(replace-regexp-in-string "\"" "\\\\\"" esc)))
(defun mu4e~proc-find (query threads sortfield revert maxnum)
"Start a database query for QUERY. If THREADS is non-nil, show
results in threaded fasion, SORTFIELD is a symbol describing the
field to sort by (or nil); see `mu4e~headers-sortfield-choices'. If
REVERT is non-nil, sort Z->A instead of A->Z. MAXNUM determines the
maximum number of results to return, or nil for 'unlimited'. For
each result found, a function is called, depending on the kind of
result. The variables `mu4e-error-func' contain the function that
will be called for, resp., a message (header row) or an error."
"Start a database query for QUERY.
If THREADS is non-nil, show results in threaded fasion, SORTFIELD
is a symbol describing the field to sort by (or nil); see
`mu4e~headers-sortfield-choices'. If REVERT is non-nil, sort Z->A
instead of A->Z. MAXNUM determines the maximum number of results
to return, or nil for 'unlimited'. For each result found, a
function is called, depending on the kind of result. The
variables `mu4e-error-func' contain the function that will be
called for, resp., a message (header row) or an error."
(mu4e~proc-send-command
"find query:\"%s\" threads:%s sortfield:%s reverse:%s maxnum:%d"
(mu4e~proc-escape-query query)
@ -337,10 +337,10 @@ will be called for, resp., a message (header row) or an error."
(if maxnum maxnum -1)))
(defun mu4e~proc-move (docid-or-msgid &optional maildir flags)
"Move message identified by DOCID-OR-MSGID. At least one of
MAILDIR and FLAGS should be specified. Note, even if MAILDIR is
nil, this is still a move, since a change in flags still implies
a change in message filename.
"Move message identified by DOCID-OR-MSGID.
At least one of MAILDIR and FLAGS should be specified. Note, even
if MAILDIR is nil, this is still a move, since a change in flags
still implies a change in message filename.
MAILDIR (), optionally
setting FLAGS (keyword argument :flags). optionally setting FLAGS
@ -393,15 +393,17 @@ of 'my' email addresses (see `mu4e-user-mail-address-list')."
(mu4e~proc-send-command "index path:\"%s\"" path))))
(defun mu4e~proc-add (path maildir)
"Add the message at PATH to the database, with MAILDIR set to the
maildir this message resides in, e.g. '/drafts'; if this works, we
will receive (:info add :path <path> :docid <docid>)."
"Add the message at PATH to the database.
With MAILDIR set to the maildir this message resides in,
e.g. '/drafts'; if this works, we will receive (:info add :path
<path> :docid <docid>)."
(mu4e~proc-send-command "add path:\"%s\" maildir:\"%s\""
path maildir))
(defun mu4e~proc-sent (path maildir)
"Add the message at PATH to the database, with MAILDIR set to the
maildir this message resides in, e.g. '/drafts'.
"Add the message at PATH to the database.
With MAILDIR set to the maildir this message resides in,
e.g. '/drafts'.
if this works, we will receive (:info add :path <path> :docid
<docid> :fcc <path>)."
@ -414,7 +416,7 @@ maildir this message resides in, e.g. '/drafts'.
message (ie, replying to, forwarding, editing) with DOCID or nil
for type `new'.
The result will be delivered to the function registered as
The result will be delivered to the function registered as
`mu4e-compose-func'."
(unless (member type '(forward reply edit new))
(mu4e-error "Unsupported compose-type %S" type))
@ -451,25 +453,24 @@ mean:
(defun mu4e~proc-ping ()
"Sends a ping to the mu server, expecting a (:pong ...) in
response."
"Sends a ping to the mu server, expecting a (:pong ...) in response."
(mu4e~proc-send-command "ping"))
(defun mu4e~proc-contacts (personal after)
"Sends the contacts command to the mu server, expecting
a (:contacts (<list>)) in response. If PERSONAL is non-nil, only
get personal contacts, if AFTER is non-nil, get only contacts
seen AFTER (the time_t value)."
"Sends the contacts command to the mu server.
A (:contacts (<list>)) is expected in response. If PERSONAL is
non-nil, only get personal contacts, if AFTER is non-nil, get
only contacts seen AFTER (the time_t value)."
(mu4e~proc-send-command
"contacts personal:%s after:%d"
(if personal "true" "false")
(or after 0)))
(defun mu4e~proc-view (docid-or-msgid &optional images decrypt)
"Get one particular message based on its
DOCID-OR-MSGID. Optionally, if IMAGES is non-nil, backend will any
images attached to the message, and return them as temp files. The
result will be delivered to the function registered as
"Get one particular message based on its DOCID-OR-MSGID.
Optionally, if IMAGES is non-nil, backend will any images
attached to the message, and return them as temp files.
The result will be delivered to the function registered as
`mu4e-message-func'."
(mu4e~proc-send-command
"view %s extract-images:%s extract-encrypted:%s use-agent:true"
@ -478,9 +479,9 @@ result will be delivered to the function registered as
(if decrypt "true" "false")))
(defun mu4e~proc-view-path (path &optional images decrypt)
"View message at PATH (keyword
argument). Optionally, if IMAGES is non-nil, backend will any
images attached to the message, and return them as temp files. The
"View message at PATH (keyword argument).
Optionally, if IMAGES is non-nil, backend will any images
attached to the message, and return them as temp files. The
result will be delivered to the function registered as
`mu4e-message-func'."
(mu4e~proc-send-command

85
mu4e/mu4e-utils.el
View File

@ -49,8 +49,8 @@ used on a string that terminates immediately after the date.")
(defun mu4e-parse-time-string (s &optional nodefault)
"Parse the standard Org-mode time string.
This should be a lot faster than the normal `parse-time-string'.
If time is not given, defaults to 0:00. However, with optional NODEFAULT,
hour and minute fields will be nil if not given."
If time is not given, defaults to 0:00. However, with optional
NODEFAULT, hour and minute fields will be nil if not given."
(if (string-match mu4e~ts-regexp0 s)
(list 0
(if (or (match-beginning 8) (not nodefault))
@ -65,8 +65,8 @@ hour and minute fields will be nil if not given."
(defun mu4e-user-mail-address-p (addr)
"If ADDR is one of user's e-mail addresses (as per
`mu4e-user-mail-address-list') return t, otherwise return nil."
"If ADDR is one of user's e-mail addresses return t, nil otherwise.
User's addresses are set in `mu4e-user-mail-address-list')."
(when (and addr mu4e-user-mail-address-list
(find addr mu4e-user-mail-address-list :test 'string=))
t))
@ -78,9 +78,10 @@ hour and minute fields will be nil if not given."
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; the standard folders can be functions too
(defun mu4e~get-folder (foldervar msg)
"Get message folder FOLDER. If FOLDER is a string, return it, if
it is a function, evaluate this function with MSG as
parameter (which may be `nil'), and return the result."
"Get message folder FOLDER.
If FOLDER is a string, return it, if it is a function, evaluate
this function with MSG as parameter (which may be `nil'), and
return the result."
(unless (member foldervar '(mu4e-sent-folder mu4e-drafts-folder
mu4e-trash-folder mu4e-refile-folder))
(mu4e-error "Folder must be either mu4e-sent-folder,
@ -137,9 +138,9 @@ see its docstring)."
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun mu4e-create-maildir-maybe (dir)
"Offer to create maildir DIR (full filesystem path) if it does
not exist yet. Return t if the dir already existed, or has been
created, nil otherwise."
"Offer to create maildir DIR if it does not exist yet.
Return t if the dir already existed, or has been created, nil
otherwise. DIR has to be an absolute path."
(if (and (file-exists-p dir) (not (file-directory-p dir)))
(mu4e-error "%s exists, but is not a directory." dir))
(cond
@ -155,31 +156,31 @@ created, nil otherwise."
(apply 'format frm args)))
(defun mu4e-message (frm &rest args)
"Like `message', but prefixed with mu4e. If we're waiting for
user-input, don't show anyhting."
"Like `message', but prefixed with mu4e.
If we're waiting for user-input, don't show anyhting."
(unless (active-minibuffer-window)
(message "%s" (apply 'mu4e-format frm args))
nil))
(defun mu4e-error (frm &rest args)
"Create [mu4e]-prefixed error based on format FRM and ARGS. Does
a local-exit and does not return, and raises a
"Create [mu4e]-prefixed error based on format FRM and ARGS.
Does a local-exit and does not return, and raises a
debuggable (backtrace) error."
(mu4e-log 'error (apply 'mu4e-format frm args))
(error "%s" (apply 'mu4e-format frm args)))
(defun mu4e-warn (frm &rest args)
"Create [mu4e]-prefixed warning based on format FRM and
ARGS. Does a local-exit and does not return. In emacs versions
below 24.2, the functions is the same as `mu4e-error'."
"Create [mu4e]-prefixed warning based on format FRM and ARGS.
Does a local-exit and does not return. In emacs versions below
24.2, the functions is the same as `mu4e-error'."
(mu4e-log 'error (apply 'mu4e-format frm args))
(if (fboundp 'user-error)
(user-error "%s" (apply 'mu4e-format frm args)) ;; only in emacs-trunk
(error "%s" (apply 'mu4e-format frm args))))
(defun mu4e~read-char-choice (prompt choices)
"Compatiblity wrapper for `read-char-choice', which is emacs-24
only."
"Compatiblity wrapper for `read-char-choice'.
That function is available which emacs-24 only."
(let ((choice) (ok) (inhibit-quit nil))
(while (not ok)
(message nil);; this seems needed...
@ -188,17 +189,17 @@ only."
choice))
(defun mu4e-read-option (prompt options)
"Ask user for an option from a list on the input area. PROMPT
describes a multiple-choice question to the user, OPTIONS describe
the options, and is a list of cells describing particular
options. Cells have the following structure:
"Ask user for an option from a list on the input area.
PROMPT describes a multiple-choice question to the user.
OPTIONS describe the options, and is a list of cells describing
particular options. Cells have the following structure:
(OPTIONSTRING . RESULT)
where OPTIONSTRING is a non-empty string describing the
option. The first character of OPTIONSTRING is used as the
shortcut, and obviously all shortcuts must be different, so you
can prefix the string with an uniquifying character.
where OPTIONSTRING is a non-empty string describing the
option. The first character of OPTIONSTRING is used as the
shortcut, and obviously all shortcuts must be different, so you
can prefix the string with an uniquifying character.
The options are provided as a list for the user to choose from;
user can then choose by typing CHAR. Example:
@ -240,8 +241,7 @@ Function will return the cdr of the list element."
(defun mu4e~get-maildirs-1 (path mdir)
"Get maildirs under path, recursively, as a list of relative
paths."
"Get maildirs under path, recursively, as a list of relative paths."
(let ((dirs)
(dentries
(ignore-errors
@ -397,7 +397,7 @@ Also see `mu4e-flags-to-string'.
(mu4e~string-to-flags-1 (substring str 1))))))
(defun mu4e-string-to-flags (str)
"Convert a string with message flags as seen in Maildir messages
"Convert a string with message flags as seen in Maildir messages
into a list of flags in; flags are symbols draft, flagged, new,
passed, replied, seen, trashed and the string is the concatenation
of the uppercased first letters of these flags, as per [1]. Other
@ -420,8 +420,8 @@ http://cr.yp.to/proto/maildir.html "
(defun mu4e-display-manual ()
"Display the mu4e manual page for the current mode, or go to the
top level if there is none."
"Display the mu4e manual page for the current mode.
Or go to the top level if there is none."
(interactive)
(info (case major-mode
('mu4e-main-mode "(mu4e)Main view")
@ -469,10 +469,10 @@ that has a live window), and vice versa."
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defvar mu4e-index-updated-hook nil
"Hook run when the indexing process had one or more updated
messages. This can be used as a simple way to invoke some action
when new messages appear, but note that an update in the index does
not necessarily mean a new message.")
"Hook run when the indexing process had one or more updated messages.
This can be used as a simple way to invoke some action when new
messages appear, but note that an update in the index does not
necessarily mean a new message.")
;; some handler functions for server messages
;;
@ -510,10 +510,10 @@ process."
;; start and stopping
(defun mu4e~fill-contacts (contacts)
"We receive a list of contacts, which each contact of the form
(:name NAME :mail EMAIL)
(:name NAME :mail EMAIL)
and fill the list `mu4e~contacts-for-completion' with it, with
each element looking like
name <email>
name <email>
This is used by the completion function in mu4e-compose."
(let ((lst))
(dolist (contact contacts)
@ -563,13 +563,14 @@ This is used by the completion function in mu4e-compose."
(defun mu4e-running-p ()
"Whether mu4e is running -- that is, the server process is live."
"Whether mu4e is running.
Checks whether the server process is live."
(mu4e~proc-running-p))
(defun mu4e~start (&optional func)
"If mu4e is already running, execute function FUNC (if non-nil). Otherwise,
check various requirements, then start mu4e. When succesful, call
FUNC (if non-nil) afterwards."
"If mu4e is already running, execute function FUNC (if non-nil).
Otherwise, check various requirements, then start mu4e. When
successful, call FUNC (if non-nil) afterwards."
;; if we're already running, simply go to the main view
(if (mu4e-running-p) ;; already running?
(when func ;; yes! run func if defined

102
mu4e/mu4e-vars.el
View File

@ -41,8 +41,9 @@
:safe 'stringp)
(defcustom mu4e-mu-binary (executable-find "mu")
"Name of the mu-binary to use; if it cannot be found in your
PATH, you can specify the full path."
"Name of the mu-binary to use.
If it cannot be found in your PATH, you can specify the full
path."
:type 'file
:group 'mu4e
:safe 'stringp)
@ -71,17 +72,17 @@ mu4e."
:safe 'integerp)
(defcustom mu4e-attachment-dir (expand-file-name "~/")
"Default directory for saving attachments. This can be either a
string, or a function that takes a filename FNAME and MIMETYPE as
arguments, and returns the attachment dir. Note, either or both of
the arguments may be `nil'."
"Default directory for saving attachments.
This can be either a string, or a function that takes a filename
FNAME and MIMETYPE as arguments, and returns the attachment
dir. Note, either or both of the arguments may be `nil'."
:type 'directory
:group 'mu4e
:safe 'stringp)
(defcustom mu4e-user-mail-address-list `(,user-mail-address)
"List of e-mail addresses to consider 'my email addresses',
ie. addresses whose presence in an email imply that it is a
"List of e-mail addresses to consider 'my email addresses'.
I.e. addresses whose presence in an email imply that it is a
personal message. This is used when indexing messages."
:type '(repeat (string :tag "Address"))
:group 'mu4e)
@ -122,19 +123,22 @@ search."
("date:today..now" "Today's messages" ?t)
("date:7d..now" "Last 7 days" ?w)
("mime:image/*" "Messages with images" ?p))
"A list of pre-defined queries; these will show up in the main
screen. Each of the list elements is a three-element list of the
form (QUERY DESCRIPTION KEY), where QUERY is a string with a mu
query, DESCRIPTION is a short description of the query (this will
show up in the UI), and KEY is a shortcut key for the query.")
"A list of pre-defined queries.
These will show up in the main screen. Each of the list elements
is a three-element list of the form (QUERY DESCRIPTION KEY),
where QUERY is a string with a mu query, DESCRIPTION is a short
description of the query (this will show up in the UI), and KEY
is a shortcut key for the query.")
(defcustom mu4e-split-view 'horizontal
"How to show messages / headers; a symbol which is either: * a
symbol 'horizontal: split horizontally (headers on top) * a symbol
'vertical: split vertically (headers on the left). * anything
else: don't split (show either headers or messages, not both) Also
see `mu4e-headers-visible-lines' and
`mu4e-headers-visible-columns'."
"How to show messages / headers.
A symbol which is either:
* `horizontal': split horizontally (headers on top)
* `vertical': split vertically (headers on the left).
* anything else: don't split (show either headers or messages,
not both)
Also see `mu4e-headers-visible-lines'
and `mu4e-headers-visible-columns'."
:type '(choice (const :tag "Split horizontally" horizontal)
(const :tag "Split vertically" vertical)
(const :tag "Don't split" nil)))
@ -161,7 +165,8 @@ view buffer."
:group 'mu4e-crypto)
(defcustom mu4e-decryption-policy t
"Policy for dealing with encrypted parts. The setting is a symbol:
"Policy for dealing with encrypted parts.
The setting is a symbol:
* t: try to decrypt automatically
* `ask': ask before decrypting anything
* nil: don't try to decrypt anything."
@ -193,16 +198,15 @@ details (in particular, how to define your own e-mail addresses)."
:group 'mu4e-compose)
(defcustom mu4e-compose-complete-only-after "2010-01-01"
"Consider only contacts last seen after this date. Date must be a
string, in a format parseable by `org-parse-time-string'. This
excludes really old contacts. Set to nil to not have any
time-based restriction."
"Consider only contacts last seen after this date.
Date must be a string, in a format parseable by
`org-parse-time-string'. This excludes really old contacts.
Set to nil to not have any time-based restriction."
:type 'string
:group 'mu4e-compose)
(defcustom mu4e-compose-complete-ignore-address-regexp "no-?reply"
"Ignore any e-mail addresses for completion if they match this
regexp."
"Ignore any e-mail addresses for completion if they match this regexp."
:type 'string
:group 'mu4e-compose)
@ -223,9 +227,9 @@ replying to messages."
:group 'mu4e-compose)
(defvar mu4e-compose-parent-message nil
"The parent message plist -- the message being replied to,
forwarded or edited; used in `mu4e-compose-pre-hook. For new
messages, it is nil.")
"The parent message plist.
This is the message being replied to, forwarded or edited; used
in `mu4e-compose-pre-hook'. For new messages, it is nil.")
;; Folders
(defgroup mu4e-folders nil
@ -233,7 +237,7 @@ messages, it is nil.")
:group 'mu4e)
(defcustom mu4e-drafts-folder "/drafts"
"Your folder for draft messages, relative to `mu4e-maildir',
"Your folder for draft messages, relative to `mu4e-maildir'.
e.g. \"/drafts\". Instead of a string, may also be a function that
takes a message (a msg plist, see `mu4e-message-get-field'), and
returns a folder. Note, the message parameter refers to the
@ -285,9 +289,9 @@ re-edited, and is nil otherwise."
(defcustom mu4e-maildir-shortcuts nil
"A list of maildir shortcuts to enable quickly going to the
particular for, or quickly moving messages towards them (i.e.,
archiving or refiling). The list contains elements of the form
(maildir . shortcut), where MAILDIR is a maildir (such as
particular for, or quickly moving messages towards them (i.e.,
archiving or refiling). The list contains elements of the form
\(maildir . shortcut), where MAILDIR is a maildir (such as
\"/archive/\"), and shortcut a single shortcut character. With
this, in the header buffer and view buffer you can execute
`mu4e-mark-for-move-quick' (or 'm', by default) or
@ -307,8 +311,8 @@ designated shortcut character for the maildir.")
(defface mu4e-moved-face
'((t :inherit font-lock-comment-face :slant italic))
"Face for a message header that has been moved to some
folder (it's still visible in the search results, since we cannot
"Face for a message header that has been moved to some folder.
\(It's still visible in the search results, since we cannot
be sure it no longer matches)."
:group 'mu4e-faces)
@ -319,8 +323,8 @@ be sure it no longer matches)."
(defface mu4e-draft-face
'((t :inherit font-lock-string-face))
"Face for a draft message header (i.e., a message with the draft
flag set)."
"Face for a draft message header
I.e. a message with the draft flag set."
:group 'mu4e-faces)
(defface mu4e-flagged-face
@ -361,8 +365,7 @@ flag set)."
(defface mu4e-view-header-value-face
'((t :inherit font-lock-doc-face))
"Face for a header value (such as \"Re: Hello!\") in the message
view."
"Face for a header value (such as \"Re: Hello!\") in the message view."
:group 'mu4e-faces)
(defface mu4e-view-special-header-value-face
@ -444,8 +447,7 @@ flag set)."
(defface mu4e-system-face
'((t :inherit font-lock-comment-face :slant italic))
"Face for system message (such as the footers for message
headers)."
"Face for system message (such as the footers for message headers)."
:group 'mu4e-faces)
(defface mu4e-ok-face
@ -547,10 +549,10 @@ Most fields should be self-explanatory. A special one is
to `:to'.")
(defvar mu4e-custom-header-info nil
"A list like `mu4e-custom-header-info', but for
custom (user-specified) headers. Each of the list items is a
property list with :name (the full-name, as displayed in the
message view), :shortname (the name as displayed in the headers
"A list like `mu4e-custom-header-info', but for custom headers.
I.e. user-specified headers. Each of the list items is a property
list with :name (the full-name, as displayed in the message
view), :shortname (the name as displayed in the headers
view), :help (some help information, which shows up in the
tooltip). Furthermore, there are two special fields:
:headers-func and :message-func, and the values should be functions
@ -582,13 +584,13 @@ Note, :sortable does not work for custom header fields.")
(defvar mu4e~view-msg nil "The message being viewed in view mode.")
(defvar mu4e~contacts-for-completion nil
"List of contacts (ie. 'name <e-mail>'),
used by the completion functions in mu4e-compose, and filled when
mu4e starts.")
"List of contacts (ie. 'name <e-mail>').
This is used by the completion functions in mu4e-compose, and
filled when mu4e starts.")
(defvar mu4e~server-props nil
"Properties we receive from the mu4e server process (in the
'pong-handler').")
"Properties we receive from the mu4e server process.
\(in the 'pong-handler').")
(defvar mu4e~headers-last-query nil
"The present (most recent) query.")

123
mu4e/mu4e-view.el
View File

@ -68,8 +68,8 @@ contact."
(make-obsolete-variable 'mu4e-view-hide-cited nil "0.9.9-dev7")
(defcustom mu4e-view-date-format "%c"
"Date format to use in the message view, in the format of
`format-time-string'."
"Date format to use in the message view.
In the format of `format-time-string'."
:type 'string
:group 'mu4e-view)
@ -87,9 +87,9 @@ end of a message. Otherwise, don't move to the next message.")
(defvar mu4e-view-actions
'( ("capture message" . mu4e-action-capture-message)
("view as pdf" . mu4e-action-view-as-pdf))
"List of actions to perform on messages in view mode. The actions
are of the form:
(NAME FUNC)
"List of actions to perform on messages in view mode.
The actions are of the form:
(NAME FUNC)
where:
* NAME is the name of the action (e.g. \"Count lines\")
* FUNC is a function which receives a message plist as an argument.
@ -100,13 +100,13 @@ The first letter of NAME is used as a shortcut character.")
'( ("wopen-with" . mu4e-view-open-attachment-with)
("ein-emacs" . mu4e-view-open-attachment-emacs)
("|pipe" . mu4e-view-pipe-attachment))
"List of actions to perform on message attachments. The actions
are of the form:
(NAME FUNC)
"List of actions to perform on message attachments.
The actions are of the form:
(NAME FUNC)
where:
* NAME is the name of the action (e.g. \"Count lines\")
* FUNC is a function which receives two arguments: the message
plist and the attachment number.
* NAME is the name of the action (e.g. \"Count lines\")
* FUNC is a function which receives two arguments: the message
plist and the attachment number.
The first letter of NAME is used as a shortcut character.")
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@ -121,21 +121,23 @@ The first letter of NAME is used as a shortcut character.")
"A map of some number->url so we can jump to url by number.")
(defvar mu4e~path-parent-docid-map (make-hash-table :test 'equal)
"A map of msg paths --> parent-docids. This is to determine what
is the parent docid for embedded message extracted at some path.")
"A map of msg paths --> parent-docids.
This is to determine what is the parent docid for embedded
message extracted at some path.")
(defconst mu4e~view-url-regexp
"\\(\\(https?\\://\\|mailto:\\)[-+a-zA-Z0-9.?_$%/+&#@!*~,:;=/()]+\\)"
"Regexp that matches http:/https:/mailto: URLs; match-string 1
will contain the matched URL, if any.")
will contain the matched URL, if any.")
(defvar mu4e~view-attach-map nil
"A mapping of user-visible attachment number to the actual part index.")
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun mu4e-view-message-with-msgid (msgid)
"View message with MSGID. This is meant for external programs
wanting to show specific messages - for example, `mu4e-org'."
"View message with MSGID.
This is meant for external programs wanting to show specific
messages - for example, `mu4e-org'."
;; note: hackish; if mu4e-decryption-policy is non-nil (ie., t or 'ask), we
;; decrpt the message. Since here we don't know if message is encrypted or
;; not, when the policy is 'ask'. we simply assume the user said yes... the
@ -145,8 +147,7 @@ wanting to show specific messages - for example, `mu4e-org'."
(defun mu4e-view-message-text (msg)
"Return the message to display (as a string), based on the MSG
plist."
"Return the message to display (as a string), based on the MSG plist."
(concat
(mapconcat
(lambda (field)
@ -463,8 +464,8 @@ at POINT, or if nil, at (point)."
;; decr))))))
(defun mu4e-view-for-each-part (msg func)
"Apply FUNC to each part in MSG. FUNC should be a function taking
two arguments:
"Apply FUNC to each part in MSG.
FUNC should be a function taking two arguments:
1. the message MSG, and
2. a plist describing the attachment. The plist looks like:
(:index 1 :name \"test123.doc\"
@ -672,8 +673,8 @@ at POINT, or if nil, at (point)."
(setq autopair-dont-activate t)))
(defun mu4e~view-mark-as-read-maybe ()
"Clear the current message's New/Unread status and set it to
Seen; if the message is not New/Unread, do nothing."
"Clear the current message's New/Unread status and set it to Seen.
If the message is not New/Unread, do nothing."
(when mu4e~view-msg
(let ((flags (mu4e-message-field mu4e~view-msg :flags))
(docid (mu4e-message-field mu4e~view-msg :docid)))
@ -720,9 +721,9 @@ Seen; if the message is not New/Unread, do nothing."
(add-text-properties p (point-max) '(face mu4e-footer-face)))))))
(defun mu4e~view-browse-url-func (url)
"Return a function that executes `browse-url' with URL. What
browser is called is depending on `browse-url-browser-function' and
`browse-url-mailto-function'."
"Return a function that executes `browse-url' with URL.
What browser is called is depending on
`browse-url-browser-function' and `browse-url-mailto-function'."
(save-match-data
(if (string-match "^mailto:" url)
(lexical-let ((url url))
@ -748,8 +749,8 @@ browser is called is depending on `browse-url-browser-function' and
;; this is fairly simplistic...
(defun mu4e~view-make-urls-clickable ()
"Turn things that look like URLs into clickable things, and
number them so they can be opened using `mu4e-view-go-to-url'."
"Turn things that look like URLs into clickable things.
Also number them so they can be opened using `mu4e-view-go-to-url'."
(let ((num 0))
(save-excursion
(setq mu4e~view-link-map ;; buffer local
@ -833,8 +834,9 @@ N (prefix argument), to the Nth previous header."
(setq mu4e~view-cited-hidden nil))
(defun mu4e-view-action (&optional msg)
"Ask user for some action to apply on MSG (or message-at-point,
if nil), then do it. The actions are specified in
"Ask user for some action to apply on MSG, then do it.
If MSG is nil apply action to message returned
bymessage-at-point. The actions are specified in
`mu4e-view-actions'."
(interactive)
(let* ((msg (or msg (mu4e-message-at-point)))
@ -874,11 +876,11 @@ all messages in the subthread at point in the headers view."
;; attachment handling
(defun mu4e~view-get-attach-num (prompt msg &optional multi)
"Ask the user with PROMPT for an attachment number for MSG, and
ensure it is valid. The number is [1..n] for attachments
[0..(n-1)] in the message. If MULTI is nil, return the number for
the attachment; otherwise (MULTI is non-nil), accept ranges of
attachment numbers, as per `mu4e-split-ranges-to-numbers', and
return the corresponding string."
ensure it is valid. The number is [1..n] for attachments
\[0..(n-1)] in the message. If MULTI is nil, return the number for
the attachment; otherwise (MULTI is non-nil), accept ranges of
attachment numbers, as per `mu4e-split-ranges-to-numbers', and
return the corresponding string."
(let* ((count (hash-table-count mu4e~view-attach-map)) (def))
(when (zerop count) (mu4e-error "No attachments for this message"))
(if (not multi)
@ -903,8 +905,9 @@ number ATTNUM."
(defun mu4e-view-save-attachment-single (&optional msg attnum)
"Save attachment number ATTNUM (or ask if nil) from MSG (or
message-at-point if nil) to disk."
"Save attachment number ATTNUM from MSG.
If MSG is nil use the message returned by `message-at-point'.
If ATTNUM is nil ask for the attachment number."
(interactive)
(let* ((msg (or msg (mu4e-message-at-point)))
(attnum (or attnum
@ -945,17 +948,18 @@ attachments, but as this is the default, you may not need it."
(mu4e-view-save-attachment-single msg num))))
(defun mu4e-view-save-attachment (&optional multi)
"Offer to save attachment(s). If MULTI (prefix-argument) is nil,
save a single one, otherwise, offer to save a range of
attachments."
"Offer to save attachment(s).
If MULTI (prefix-argument) is nil, save a single one, otherwise,
offer to save a range of attachments."
(interactive "P")
(if multi
(mu4e-view-save-attachment-multi)
(mu4e-view-save-attachment-single)))
(defun mu4e-view-open-attachment (&optional msg attnum)
"Open attachment number ATTNUM (or ask if nil) from MSG (or
message-at-point if nil)."
"Open attachment number ATTNUM from MSG.
If MSG is nil use the message returned by `message-at-point'.
If ATTNUM is nil ask for the attachment number."
(interactive)
(let* ((msg (or msg (mu4e-message-at-point)))
(attnum (or attnum
@ -976,16 +980,15 @@ message-at-point if nil)."
(defun mu4e~view-temp-action (docid index what &optional param)
"Open attachment INDEX for message with DOCID, and invoke
ACTION."
"Open attachment INDEX for message with DOCID, and invoke ACTION."
(interactive)
(mu4e~proc-extract 'temp docid index nil what param))
(defvar mu4e~view-open-with-hist nil "History list for the open-with argument.")
(defun mu4e-view-open-attachment-with (msg attachnum &optional cmd)
"Open MSG's attachment ATTACHNUM with CMD; if CMD is nil, ask
user for it."
"Open MSG's attachment ATTACHNUM with CMD.
If CMD is nil, ask user for it."
(interactive)
(let* ((att (mu4e~view-get-attach msg attachnum))
(cmd (or cmd
@ -1000,8 +1003,8 @@ user for it."
"History list for the pipe argument.")
(defun mu4e-view-pipe-attachment (msg attachnum &optional pipecmd)
"Feed MSG's attachment ATTACHNUM through pipe PIPECMD; if
PIPECMD is nil, ask user for it."
"Feed MSG's attachment ATTACHNUM through pipe PIPECMD.
If PIPECMD is nil, ask user for it."
(interactive)
(let* ((att (mu4e~view-get-attach msg attachnum))
(pipecmd (or pipecmd
@ -1023,9 +1026,9 @@ PIPECMD is nil, ask user for it."
(defun mu4e-view-attachment-action (&optional msg)
"Ask user what to do with attachments in MSG (or nil to use
message-at-point, then do it. The actions are specified in
`mu4e-view-attachment-actions'."
"Ask user what to do with attachments in MSG
If MSG is nil use the message returned by `message-at-point'.
The actions are specified in `mu4e-view-attachment-actions'."
(interactive)
(let* ((msg (or msg (mu4e-message-at-point)))
(actionfunc (mu4e-read-option
@ -1072,8 +1075,9 @@ attachments) in response to a (mu4e~proc-extract 'temp ... )."
(member mu4e-split-view '(horizontal vertical)))
(defun mu4e-view-scroll-up-or-next ()
"Scroll-up the current message; if mu4e-view-scroll-to-next is
non-nil, and we can't scroll-up anymore, go the next message."
"Scroll-up the current message.
If `mu4e-view-scroll-to-next' is non-nil, and we can't scroll-up
anymore, go the next message."
(interactive)
(condition-case nil
(scroll-up)
@ -1082,16 +1086,18 @@ non-nil, and we can't scroll-up anymore, go the next message."
(mu4e-view-headers-next)))))
(defun mu4e-view-unmark-all ()
"If we're in split-view, unmark all messages. Otherwise, warn
user that unmarking only works in the header list."
"If we're in split-view, unmark all messages.
Otherwise, warn user that unmarking only works in the header
list."
(interactive)
(if (mu4e~view-split-view-p)
(mu4e~view-in-headers-context (mu4e-mark-unmark-all))
(mu4e-message "Unmarking needs to be done in the header list view")))
(defun mu4e-view-unmark ()
"If we're in split-view, unmark message at point. Otherwise, warn
user that unmarking only works in the header list."
"If we're in split-view, unmark message at point.
Otherwise, warn user that unmarking only works in the header
list."
(interactive)
(if (mu4e~view-split-view-p)
(mu4e-view-mark-for-unmark)
@ -1188,8 +1194,9 @@ or message-at-point."
(defun mu4e~view-quit-buffer ()
"Quit the mu4e-view buffer. This is a rather complex function, to
ensure we don't disturb other windows."
"Quit the mu4e-view buffer.
This is a rather complex function, to ensure we don't disturb
other windows."
(interactive)
(unless (eq major-mode 'mu4e-view-mode)
(mu4e-error "Must be in mu4e-view-mode (%S)" major-mode))

2
mu4e/mu4e.el
View File

@ -29,7 +29,7 @@
(eval-when-compile (require 'cl))
(require 'mu4e-meta) ;; autogenerated file with metadata (version etc.)
(require 'mu4e-headers) ;; headers view
(require 'mu4e-headers) ;; headers view
(require 'mu4e-view) ;; message view
(require 'mu4e-main) ;; main screen
(require 'mu4e-compose) ;; message composition / sending

35
mu4e/org-mu4e.el
View File

@ -42,18 +42,17 @@
(defcustom org-mu4e-link-desc-func
(lambda (msg) (or (plist-get msg :subject) "No subject"))
"Function that takes a msg and returns a string for the
description part of an org-mode link.
description part of an org-mode link.
Example usage:
Example usage:
(defun my-link-descr (msg)
(let
((subject (or (plist-get msg :subject)
\"No subject\"))
(defun my-link-descr (msg)
(let ((subject (or (plist-get msg :subject)
\"No subject\"))
(date (or (format-time-string mu4e-headers-date-format
(mu4e-msg-field msg :date))
\"No date\")))
(concat subject \" \" date)))
(mu4e-msg-field msg :date))
\"No date\")))
(concat subject \" \" date)))
(setq org-mu4e-link-desc-func 'my-link-descr)"
:type 'function
@ -201,8 +200,8 @@ and images in a multipart/related part."
(overlay-put olay 'face 'font-lock-comment-face)))))
(defun org~mu4e-mime-undecorate-headers ()
"Don't make the headers visually distinctive (well,
mu4e-compose-mode will take care of that)."
"Don't make the headers visually distinctive.
\(well, mu4e-compose-mode will take care of that)."
(save-excursion
(goto-char (point-min))
(let* ((eoh (when (search-forward mail-header-separator)
@ -210,14 +209,14 @@ mu4e-compose-mode will take care of that)."
(remove-overlays (point-min) eoh))))
(defvar org-mu4e-convert-to-html nil
"Whether to do automatic org-mode => html conversion when sending
messages.")
"Whether to do automatic org-mode => html conversion when sending messages.")
(defun org~mu4e-mime-convert-to-html-maybe ()
"Convert to html if `org-mu4e-convert-to-html' is non-nil. This
function is called when sending a message (from
`message-send-hook') and, if non-nil, will send the message as the
rich-text version of the what is assumed to be an org-mode body."
"Convert to html if `org-mu4e-convert-to-html' is non-nil.
This function is called when sending a message (from
`message-send-hook') and, if non-nil, will send the message as
the rich-text version of the what is assumed to be an org-mode
body."
(when org-mu4e-convert-to-html
(mu4e-message "Converting to html")
(org~mu4e-mime-convert-to-html)))
@ -261,7 +260,7 @@ or org-mode (when in the body)."
(defun org-mu4e-compose-org-mode ()
"Pseudo-Minor mode for mu4e-compose-mode, to edit the message
body using org-mode."
body using org-mode."
(interactive)
(unless (member major-mode '(org-mode mu4e-compose-mode))
(mu4e-error "Need org-mode or mu4e-compose-mode"))