Add `consult-org-agenda-multi`

[45mg]

Adds a command consult-org-agenda-multi, a command to jump to an agenda file or an agenda heading, using consult--multi.

To achieve this, the following changes have been made:

• consult-org--annotate has been rewritten. It now supports adding the filename as an annotation, which is necessary for consult-org-agenda-multi since it can't group the headings by file. Moreover, the annotations are padded to form neatly aligned columns. The annotations to be added can be specified - this is used to preserve the original behavior for consult-org-heading.

• To simplify the above, some changes have been made to the way consult-org--headings stores the heading attributes in the consult-org--heading text property of each heading. It now adds the correct face to the todo keyword, and the priority is now a propertized priority cookie string.

• A new state function consult-org--heading-state has been introduced. It wraps consult--jump-state, passing the marker from the org-marker text property of each heading to those functions. For consistency, consult-org-heading has also been made to use this state function.

• Two new sources, consult--file-relative-source and consult-org--heading-source, have been introduced for use in consult--multi. They are implemented as functions that generate sources, so that they can be reused with different parameters in other functions.

I haven't signed the FSF papers yet; let me know if you'd be willing to merge this, and then I'll look into it.

[minad]

Hello @45mg,

thanks for this. Consult commands operate on candidates of a single type, similar to how Emacs built-in commands work. consult-buffer is the one exception, where we have multiple candidate types. I don't plan to add additional sources beyond the ones relevant for consult-buffer, since I don't want to reimplement commands on the basis of sources in the style of Helm. It would be unclear where to stop and I want to avoid duplication where we have both simple commands and the corresponding sources.

I am open to merging some utilities here, e.g., the file source helper function, if it turns out to be useful for the consult-buffer sources. Similarly we can add adjustments to the candidate properties, if this is helpful, and of course improvements to the faces/styling.

[45mg]

Fair enough. If you're sure that you won't be adding or accepting any new multi-source commands, go ahead and close this PR. In which case, could you mention that in the docs and/or wishlist? That way people know not to PR stuff like this.

If you decide to close this - can I rework this code as a configuration example on the Wiki? I initially wrote all of this in my config, and maybe other users might want it as well.

Also - what do you think of the changes to consult-org--annotate and consult-org--headings alone? Could they be merged? I think the aligned annotation columns look better, the code is cleaner, and it would allow users to reuse the annotation function in their own custom configurations (as I have).

[minad]

Fair enough. If you're sure that you won't be adding or accepting any new multi-source commands, go ahead and close this PR. In which case, could you mention that in the docs and/or wishlist? That way people know not to PR stuff like this.

New features always require some discussion. I think this applies generally to many projects.

If you decide to close this - can I rework this code as a configuration example on the Wiki? I initially wrote all of this in my config, and maybe other users might want it as well.

Please do. It would be great if you add your code to the wiki.

Also - what do you think of the changes to consult-org--annotate and consult-org--headings alone? Could they be merged? I think the aligned annotation columns look better, the code is cleaner, and it would allow users to reuse the annotation function in their own custom configurations (as I have).

Please rebase these changes on top of the main branch, then I will take a close look. But aren't the annotations already aligned right now?

[45mg]

Please rebase these changes on top of the main branch, then I will take a close look.

I did this in #982.

[minad]

Okay let's continue there.