and further clarify `mod -a` docs:
Even though e39dcfc002 and the linked discussion
already does a very good job on clarifying what is actually happening when `mod
-a` is issued, this commit adds further details about the difference between
the album query and what is actually modified.
- New config option for the importer 'singleton_album_disambig' lets
users choose whether they want to display [album names] in the list of
candidates. Enabled by default but ony applicable if the candidate provides
an album attribute.
- Add docs describing the new option and which source plugins currently support
it.
PR #4251 added exact match queries, which are great, but it was
subsequently pointed out that the `~` query prefix was already in use:
https://github.com/beetbox/beets/pull/4251#issuecomment-1069455483
So this changes the prefix from `~` to `=~`. A little longer, but
hopefully it makes the relationship to the similarly-new `=` prefix obvious.
See https://github.com/beetbox/beets/discussions/4172.
I think the confusion arises because the documentation refers to the
query. That is, when `-a` is given, albums are queried, not tracks. This
is especially clear when using `beet list`, because then it truly lists
"albums instead of items". However, for other commands, the distinction
between what is queried and what is acted on should be made more clear.
This PR fixes the section for `modify`, but there are more questions:
- `remove` command: The documentation states that it acts on albums
instead of individual tracks. I guess we should also amend that? I think
the complete album including the tracks is deleted, or is that not true?
- `move` command: I think the same is true for this command. If `-a` is
given, the queried albums including all tracks are moved.
- `update` command: The `-a` flag is not explained here.
