Fixed emacs docstrings to be consistent. No functional change.
- removed some (accidental) indentation
- removed some trailing newlines
- added trailing periods where missing (some exclusions)
Quoting from the elisp reference:
For other types (e.g., lists, vectors, strings), two arguments
with the same contents or elements are not necessarily ‘eq’ to
each other.
Thanks to "Attic Hermit" for the fix.
We now have several customizable options for address completion. There
is a customize group notmuch-address but it only contains one of these
options. Add all the others, and make it part of the notmuch customize
group.
This allows the user to save the address hash so that it is much
faster for the first completion after a restart. This defaults to off
as there are privacy implications to saving this information.
The code tries hard to avoid overwriting the wrong file. It also notes
if changes have been made to any of the relevant user settings, so
that the user does not get surprising results (i.e., outdated options
being used). Finally it stores some version information so that is
easy for us to update the format of the save file.
This makes the code access notmuch-address-full-harvest-finished via a
helper function, notmuch-address--harvest-ready. Later we will use
this to check whether we can load the harvest instead of regenerating
it.
Some of the recent changes to the emacs code have used functions
introduced in emacs 24. The functions used are read-char-choice and
setq-local. This changeset adds a file notmuch-compat.el which
contains compatibility functions so that it should work on emacs
23.
Note, since these functions are taken almost unchanged from the emacs
source they are copyright the Free Software Foundation, and the header
in the file reflects that.
This hook can be used to update the message based on the results of
address completion. For example using message-templ or gnus-alias to set
the From address based on the To address just completed.
The post-completion command is added to the notmuch-company backend to
ensure that the hook is also called company completion is started
without going through notmuch-address-expand-name. See the docstring of
`company-backends' for more information.
The current code for address completion takes the list of possible
completions (whether generated internally or externally), makes the
first match the initial value for the completion, and puts all the
others (but not the first match) into the possible completions.
This has the nice effect that the <down> key takes you immediately to
the next completion (whereas if the first match were included in the
possible completions it would take you to the first match
again).
However, it has two side effects. First, once you have completed to
the full match you find it says and try completing again you get told
"no match" not "sole completion". Secondly, if you delete some of the
text and try completing you don't get the first match as an option.
This tries to get round most of these problems by including the full
list of possible completions, but with the first match moved to the
very end of the list.
This commit makes two changes. The first allows the user to override
an external completion method with the internal notmuch address based
completion for an individual buffer.
Secondly, if the user has company-mode enabled then it sets up company
mode (based on internal completion) but disables the automatic timeout
completion -- the user can still activate it in when desired with
standard company commands such as company-complete.
This commit lets the user customize the address completion. It makes
two changes.
The first change controls whether to build the address completion list
based on messages you have sent or you have received (the latter is
much faster).
The second change add a possible filter query to limit the messages
used -- for example, setting this to date:1y.. would limit the
address completions to addresses used in the last year. This speeds up
the address harvest and may also make the search less cluttered as old
addresses may well no longer be valid.
Many of the external links found in the notmuch source can be resolved
using https instead of http. This changeset addresses as many as i
could find, without touching the e-mail corpus or expected outputs
found in tests.
The new function notmuch-show-message-resend re-sends
message to new recipients using #'message-resend.
Recipients are read from minibuffer as a comma-separated
string (with some keyboard support including tab completion).
Final confirmation before sending is asked.
When company-mode is available (Emacs >= 24), address completion
candidates are shown in a nice popup box. This is triggered either by
pressing TAB or by waiting a while during typing an address. The
completion is based entirely on the asynchronous address harvesting
from notmuch-address.el so the GUI is theoretically not blocked for
long time.
The completion works similarly as the TAB-initiated completion from
notmuch-address.el, i.e. quick harvest based on user input is executed
first and only after full harvesting is finished, in-memory cached data
is used.
[Improved by David Bremner]
Currently, notmuch has an address completion mechanism that requires
external command to provide completion candidates. This commit adds a
completion mechanism inspired by https://github.com/tjim/nevermore,
which is implemented in Emacs lisp only.
The preexisting address completion mechanism, activated by pressing
TAB on To/Cc lines, is extended to use the new mechanism when
notmuch-address-command to 'internal, which is the new default.
The core of the new mechanism is the function notmuch-address-harvest,
which collects the completion candidates from the notmuch database and
stores them in notmuch-address-completions variable. The address
harvesting can run either synchronously (same as with the previous
mechanism) or asynchronously. When the user presses TAB for the first
time, synchronous harvesting limited to user entered text is performed.
If the entered text is reasonably long, this operation is relatively
fast. Then, asynchronous harvesting over the full database is triggered.
This operation may take long time (minutes on rotating disk). After it
finishes, no harvesting is normally performed again and subsequent
completion requests use the harvested data cached in memory. Completion
cache is updated after 24 hours.
Note that this commit restores (different) completion functionality for
users when the user used external command named "notmuch-addresses",
i.e. the old default. The result will be that the user will use
the new mechanism instead of this command. I believe that many users may
not even recognize this because the new mechanism works the same as
http://commonmeasure.org/~jkr/git/notmuch_addresses.git and perhaps also
as other commands suggested at
http://notmuchmail.org/emacstips/#address_completion.
[This feature was significantly improved by David Bremner and Mark Walters]
This allows e.g. Gnus users to load this file without changing
message-mode behaviour.
This will disable completion for those that did not customize the
variable but relied on the existence of a file named "notmuch-addresses"
in their path. In the next commit the default behaviour will change to
use a "workalike" internal completion mechanism.
The TAB-initiated address completion generates completion candidates
synchronously, blocking the UI. Since this can take long time, it is
better to let the use know what's happening.
Added a customizable variable notmuch-address-selection-function
and the function with the same name to provide a way for user to
change the function called to do address selection.
By default the functionality is exactly the same as it has been so
far; completing-read is called with the same parameters as before.
Setting equivalent lambda expression in place of using
notmuch-address-selection-function function is done as follows:
(setq notmuch-address-selection-function
(lambda (prompt collection initial-input)
(completing-read prompt collection nil nil initial-input)))
For example drop-in replacement with ido-completing-read can be done
easily as an one alternative to the default.
From a show buffer, notmuch-bbdb/snarf-from imports the sender into
bbdb. notmuch-bbdb/snarf-to imports all recipients. Newly imported
contacts are reported in the minibuffer / Messages buffer.
Both functions use the BBDB parser to recognize email address formats.
To allow for expansion whilst keeping everything tidy and organized,
move all defcustom/defface variables to the following subgroups,
defined in notmuch-lib.el:
- Hello
- Search
- Show
- Send
- Crypto
- Hooks
- External Commands
- Appearance
As an added benefit, defcustom keyword args are now consistently
ordered as they appear @ defcustom's docstring (OCD much?).
Proper defgroup docstrings and various other improvements
by courtesy of Austin Clements.
If the address matching function generates no matches, don't prompt
the user to choose between them (!). Instead, generate a message to
report that there were no matches.
When completing an address, tell the user how many addresses in the
database matched the query.
Edited-by: Carl Worth <cworth@cworth.org>: Removed a stray numeric
literal that was causing a compiler warning.
A tool `notmuch-addresses' is required to produce addresses which
match a query string. An example of a suitable script can be found in
the git repository at
http://jkr.acm.jhu.edu/git/notmuch_addresses.git
There are no doubt others.
