mu: rename --my-address into --personal-address

This makes things a bit more uniform with all the places where we use
"personal".

--my-address remains as an alias for the command-line option.

Add unit test.

Resolves #2806.

9 files changed, 85 insertions, 39 deletions

diff --git a/IDEAS.org b/IDEAS.org
index f0435d6..5f1a7c8 100644
--- a/IDEAS.org
+++ b/IDEAS.org
@@ -27,9 +27,6 @@ future.
   the newest though) https://github.com/djcb/mu/issues/2759. Or, from
   new-to-old, reversed in thread: https://github.com/djcb/mu/issues/2807
 
-- perhaps use =--personal-addres= instead of =--my-address= for consistency
-  https://github.com/djcb/mu/issues/2806
-
 ** mu4e
 
 - Allow for *muting* messages https://github.com/djcb/mu/issues/636 Useful;
@@ -93,3 +90,6 @@ future.
   Yes: this is implemented now, in 1.12.9. Various Gnus' mailing list commands
   are now available in the mu4e message view as well, such as
   ~gnus-mailing-list-subscribe~, ~gnus-mailing-list-unsubscribe~.
+
+- perhaps use =--personal-addres= instead of =--my-address= for consistency
+  https://github.com/djcb/mu/issues/2806 (done as per 1.12.12)
diff --git a/lib/mu-server.cc b/lib/mu-server.cc
index 0ea352f..700f5e3 100644
--- a/lib/mu-server.cc
+++ b/lib/mu-server.cc
@@ -345,8 +345,7 @@ Server::Private::make_command_map()
 	cmap.emplace(
 	    "index",
 	    CommandInfo{
-		ArgMap{{":my-addresses", ArgInfo{Type::List, false, "list of 'my' addresses"}},
-		       {":cleanup",
+		ArgMap{{":cleanup",
 			ArgInfo{Type::Symbol,
 				false,
 				"whether to remove stale messages from the store"}},
diff --git a/man/mu-cfind.1.org b/man/mu-cfind.1.org
index c680587..220d9f6 100644
--- a/man/mu-cfind.1.org
+++ b/man/mu-cfind.1.org
@@ -4,8 +4,8 @@
 
 * NAME
 
-mu-cfind - find contacts in the *mu* database and export them
-for use in other programs.
+mu-cfind - find contacts in the *mu* database and export them for use in other
+programs.
 
 * SYNOPSIS
 
@@ -14,15 +14,15 @@ for use in other programs.
 * DESCRIPTION
 
 *mu cfind* is the *mu* command for finding =contacts= (name and e-mail address of
-people who were either an e-mail's sender or receiver). There are different
-output formats available, for importing the contacts into other programs.
+people who were either an e-mail's sender or receiver). Different output formats
+are available, e.g., for importing the contacts into other programs.
 
 * SEARCHING CONTACTS
 
 When you index your messages (see *mu index*), *mu* creates a list of unique e-mail
-addresses found and the accompanying name, and caches this list. In case the
-same e-mail address is used with different names, the most recent non-empty name
-is used.
+addresses found and the accompanying name, and caches this list. If the same
+e-mail address is used with different names, the most recent non-empty name is
+used. If that is not the desired name, see *CORRECTING* below.
 
 *mu cfind* starts a search for contacts that match a =regular expression=. For
 example:
@@ -31,7 +31,7 @@ example:
 $ mu cfind '@gmail\.com'
 #+end_example
 
-would find all contacts with a gmail-address, while
+finds all contacts with a gmail-address, while
 
 #+begin_example
 $ mu cfind Mary
@@ -40,8 +40,8 @@ $ mu cfind Mary
 lists all contacts with Mary in either name or e-mail address.
 
 If you do not specify a search expression, *mu cfind* returns the full list of
-contacts. Note, *mu cfind* uses a cache with the e-mail information, which is
-populated during the indexing process.
+contacts. *mu cfind* uses a cache with the e-mail information, which is populated
+during the indexing process.
 
 The regular expressions are basic case-insensitive PCRE, see {{{man-link(pcre,3)}}}.
 
@@ -56,7 +56,7 @@ Sets the output format to the given value. The following are available:
 | plain       | default, simple list              |
 | mutt-alias  | mutt alias-format                 |
 | mutt-ab     | mutt external address book format |
-| wl          | wanderlust addressbook format     |
+| wl          | wanderlust address book format    |
 | org-contact | org-mode org-contact format       |
 | bbdb        | BBDB format                       |
 | csv         | comma-separated values [1]        |
@@ -69,9 +69,10 @@ any double-quote is replaced by a double-double quote (thus, "hello" become
 should only apply to name fields.
 
 ** -p, --personal
-Only show addresses seen in messages where one of `my' e-mail
-addresses was seen in one of the address fields; this is to exclude addresses
-only seen in mailing-list messages. See the *--my-address* parameter to *mu init*.
+Only show addresses seen in messages where at least one of personal e-mail
+addresses was seen in any of the address fields; this is to exclude addresses
+only seen in mailing-list messages. See the *--personal-address* parameter to *mu
+init* for specifying your personal e-mail addresses.
 
 ** --after _timestamp_
 Only show addresses last seen after _timestamp_. _timestamp_ is a UNIX
@@ -80,7 +81,7 @@ Only show addresses last seen after _timestamp_. _timestamp_ is a UNIX
 From the command line, you can use the *date* command to get this value. For
 example, only consider addresses last seen after 2020-06-01, you could specify
 #+begin_example
-  --after=`date +%s --date='2020-06-01'`
+  --after=$(date +%s --date='2020-06-01')
 #+end_example
 
 #+include: "muhome.inc" :minlevel 2
@@ -142,8 +143,8 @@ For this to work, add the following to your _muttrc_:
 set query_command = "mu cfind --format=mutt-ab '%s'"
 #+end_example
 
-Now, in mutt, you can search for e-mail addresses using the *query*-command,
-which is (by default) accessible by pressing *Q*.
+Now, in mutt, you can search for e-mail addresses using the *query*-command, which
+is (by default) accessible by pressing *Q*.
 
 * ENCODING
 
@@ -151,6 +152,14 @@ which is (by default) accessible by pressing *Q*.
 *--format=bbdb*. This is hard-coded to UTF-8, and as such specified in the
 output-file, so emacs/bbdb can handle things correctly, without guessing.
 
+
+* CORRECTING
+
+If you want to correct the name for a given contact, one trick is to manual
+create an e-mail message with some future date that has all the correct name /
+e-mail address combinations, and put this in the Maildir you use.
+
+
 #+include: "exit-code.inc" :minlevel 1
 
 #+include: "bugs.inc" :minlevel 1
diff --git a/man/mu-init.1.org b/man/mu-init.1.org
index b98cdb5..09681df 100644
--- a/man/mu-init.1.org
+++ b/man/mu-init.1.org
@@ -25,7 +25,8 @@ if it is an existing directory. If neither of those can be used, the *--maildir*
 option is required; it must be an absolute path (but ~~/~ expansion is
 performed).
 
-** --my-address _email-address-or-regex_
+** --personal-address _email-address-or-regex_
+** --my-address _email-address-or-regex_  (alias)
 Specifies that some e-mail address is a personal address. The option can be used
 multiple times, to specify all your addresses.
 
@@ -54,7 +55,7 @@ option can be used multiple times). Such addresses then cannot be found with
 {{{man-link(mu-cfind,1)}}} or in the Mu4e contacts cache.
 
 _my-email-address_ can be either a plain e-mail address or a regexp, just like
-for the *--my-address* option.
+for the *--personal-address* option.
 
 ** --max-message-size _size_
 Specifies the maximum size for an e-mail message. Usually, the default of
diff --git a/mu/mu-cmd-init.cc b/mu/mu-cmd-init.cc
index 26a9600..8463ce7 100644
--- a/mu/mu-cmd-init.cc
+++ b/mu/mu-cmd-init.cc
@@ -1,5 +1,5 @@
 /*
-** Copyright (C) 2023 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
+** Copyright (C) 2023-2025 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 **
 ** This program is free software; you can redistribute it and/or modify it
 ** under the terms of the GNU General Public License as published by the
@@ -56,8 +56,8 @@ Mu::mu_cmd_init(const Options& opts)
 			conf.set<Config::Id::MaxMessageSize>(*opts.init.max_msg_size);
 		if (opts.init.batch_size && *opts.init.batch_size != 0)
 			conf.set<Config::Id::BatchSize>(*opts.init.batch_size);
-		if (!opts.init.my_addresses.empty())
-			conf.set<Config::Id::PersonalAddresses>(opts.init.my_addresses);
+		if (!opts.init.personal_addresses.empty())
+			conf.set<Config::Id::PersonalAddresses>(opts.init.personal_addresses);
 		if (!opts.init.ignored_addresses.empty())
 			conf.set<Config::Id::IgnoredAddresses>(opts.init.ignored_addresses);
 		if (opts.init.support_ngrams)
@@ -130,6 +130,38 @@ test_mu_init_maildir()
 	assert_equal(store.root_maildir(), MU_TESTMAILDIR2);
 }
 
+
+static void
+test_mu_init_personal()
+{
+	TempDir temp_dir{};
+
+	const auto mu_home{temp_dir.path()};
+
+	g_setenv("MAILDIR", MU_TESTMAILDIR2, 1);
+	auto res1 = run_command({MU_PROGRAM, "--quiet", "init",
+			"--muhome", mu_home, "--personal-address", "foo@example.com",
+			"--my-address", "bar@example.com", // backward compat
+			"--personal-address", "/h.llo@example\\.com/"});
+	assert_valid_command(res1);
+
+	auto&& store = unwrap(Store::make(join_paths(temp_dir.path(), "xapian")));
+	g_assert_true(store.empty());
+	assert_equal(store.root_maildir(), MU_TESTMAILDIR2);
+
+	const auto& ccache{store.contacts_cache()};
+
+	// just some basic tests to see the parameters made it through.
+
+	g_assert_true(ccache.is_personal("foo@example.com"));
+	g_assert_true(ccache.is_personal("bar@example.com"));
+	g_assert_true(ccache.is_personal("hello@example.com"));
+	g_assert_true(ccache.is_personal("hallo@example.com"));
+
+	g_assert_false(ccache.is_personal("faa@example.com"));
+	g_assert_false(ccache.is_personal("baa@example.com"));
+}
+
 int
 main(int argc, char* argv[])
 {
@@ -137,6 +169,7 @@ main(int argc, char* argv[])
 
 	g_test_add_func("/cmd/init/basic", test_mu_init_basic);
 	g_test_add_func("/cmd/init/maildir", test_mu_init_maildir);
+	g_test_add_func("/cmd/init/personal", test_mu_init_personal);
 
 	return g_test_run();
 }
diff --git a/mu/mu-options.cc b/mu/mu-options.cc
index 1b58a28..2b96932 100644
--- a/mu/mu-options.cc
+++ b/mu/mu-options.cc
@@ -465,8 +465,9 @@ sub_init(CLI::App& sub, Options& opts)
 		->transform(ExpandPath, "expand maildir path");
 	// don't attempt to canonicalize; in bash this breaks together with
 	// expand path.
-	sub.add_option("--my-address", opts.init.my_addresses,
-		       "Personal e-mail address or regexp")
+	sub.add_option("--personal-address,--my-address",
+		       opts.init.personal_addresses,
+		       "Personal e-mail address or regexp (can be used multiple titmes)")
 		->type_name("<address>");
 	sub.add_option("--ignored-address", opts.init.ignored_addresses,
 		       "Ignored e-mail address or regexp")
@@ -481,6 +482,7 @@ sub_init(CLI::App& sub, Options& opts)
 	sub.add_flag("--reinit", opts.init.reinit,
 		       "Re-initialize database with current settings")
 		->excludes("--maildir")
+		->excludes("--personal-address")
 		->excludes("--my-address")
 		->excludes("--ignored-address")
 		->excludes("--max-message-size")
diff --git a/mu/mu-options.hh b/mu/mu-options.hh
index 6439812..bd5799a 100644
--- a/mu/mu-options.hh
+++ b/mu/mu-options.hh
@@ -188,7 +188,7 @@ struct Options {
 	 */
 	struct Init {
 		std::string	maildir;		/**< where the mails are */
-		StringVec	my_addresses;		/**< personal e-mail addresses */
+		StringVec	personal_addresses;	/**< personal e-mail addresses */
 		StringVec	ignored_addresses;	/**< addresses to be ignored for
 							 * the contacts-cache */
 		OptSize		max_msg_size;		/**< max size for message files */
diff --git a/mu4e/mu4e-main.el b/mu4e/mu4e-main.el
index 803c269..8ba1179 100644
--- a/mu4e/mu4e-main.el
+++ b/mu4e/mu4e-main.el
@@ -354,7 +354,7 @@ Otherwise, do nothing."
             (mu4e-message (concat
                            "Tip: `user-mail-address' ('%s') is not part "
                            "of mu's addresses; add it with 'mu init
-                        --my-address='") user-mail-address)))
+                        --personal-address='") user-mail-address)))
         (goto-char pos)))))
 
 (defun mu4e--main-view-queue ()
diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi
index 9a05eb0..43ee38c 100644
--- a/mu4e/mu4e.texi
+++ b/mu4e/mu4e.texi
@@ -395,18 +395,20 @@ following command:
 You can add some e-mail addresses, so @t{mu} recognizes them as yours:
 
 @example
-  $ mu init --maildir=~/Maildir --my-address=jim@@example.com \
-    --my-address=bob@@example.com
+  $ mu init --maildir=~/Maildir --personal-address=jim@@example.com \
+    --personal-address=bob@@example.com
 @end example
 
-@t{mu} remembers the maildir and your addresses and uses them when
-indexing messages. If you want to change them, you need to @t{init}
-once again.
+(An older synonym for @t{--personal-address} is @t{--my-address}, which is still
+supported).
+
+@t{mu} remembers the maildir and your addresses and uses them when indexing
+messages. If you want to change them, you need to @t{init} once again.
 
 The addresses may also be basic PCRE regular expressions, wrapped in slashes,
 for example:
 @example
-  $ mu init --maildir=~/Maildir '--my-address=/foo-.*@@example\.com/'
+  $ mu init --maildir=~/Maildir '--personal-address=/foo-.*@@example\.com/'
 @end example
 
 If you want to see the values for your message-store, you can use
@@ -1858,7 +1860,7 @@ only consider addresses that were seen in @emph{personal} messages ---
 that is, messages in which one of my e-mail addresses was seen in one
 of the address fields. This is to exclude mailing list posts. You can
 define what is considered `my e-mail address' using the
-@t{--my-address} parameter to @t{mu init}.
+@t{--personal-address} parameter to @t{mu init}.
 
 @item @code{mu4e-compose-complete-only-after} --- only consider e-mail
 addresses last seen after some date. Parameter is a string, parseable by
@@ -2009,7 +2011,7 @@ configuration:
 @item If you want to exclude your own e-mail addresses when ``replying to
 all'', set @code{message-dont-reply-to-names} to
 @code{mu4e-personal-or-alternative-address-p}. In order for this to work
-properly you need to pass your address to @command{mu init --my-address=} at
+properly you need to pass your address to @command{mu init --personal-address=} at
 database initialization time, and/or use @t{message-alternative-emails}.
 @end itemize