Local value predicates for bib data variables

[Hugo-Heagren]

I've started using a .bib file to hold data for my CV. When I'm working on the TeX in the CV folder, I the only bib data I want is that in my cv.bib. I never really want to acces it otherwise. So it's useful if these variables can be set locally (using .dir-locals). To avoid having to confirm that they're safe every time, I've added a sensible test for safety.

[bdarcus]

Thanks @Hugo-Heagren.

This seems straightforward enough, but I'm unsure if there are possible unintended consequences, so asked @roshanshariff for a review.

[roshanshariff]

This looks like the same feature as #800, right? Is there a reason the existing local bibliography detection doesn't work using the \bibliography or \addbibresource macros in Latex?

[bdarcus]

This looks like the same feature as #800, right?

I totally forgot about that!

[bdarcus]

Maybe we should add something on this to the wiki and/or README instead?

[Hugo-Heagren]

This looks like the same feature as #800, right?

Yes! Sorry, I hadn't seen that.

Is there a reason the existing local bibliography detection doesn't work using the \bibliography or \addbibresource macros in Latex?

I didn't know about this, thanks for drawing my attention to it. It's very clever, but there are two problems with this approach (which, to be fair, both lie outside of the standard applications of packages like citar):

1. The current auto-detection facilities add the auto-detected local bibliography to the global bibliography and then display an aggregated list of both in citar's interactive commands. My global bibliography is huge, my personal one is tiny (sadly) and so the stuff in the local bibliography is harder to find. I have to search for it manually, but with a local value for the variable only the relevant stuff is presented.
2. the auto-detection only works when visiting files with a bibliography source declaration in them (in my case, when visiting cv.tex). But I often need citar outside of these buffers. I write my clever CV latex code, compile the document and visit the pdf (which does not contain such a line) , only to notice that I haven't included the name of grant/funding institution in a conference or whatever. I want to run citar-open-entry, open the bib entry and edit it -- but I can't because the PDF doesn't declare where the bib data comes from.

I think a local variable is an easy way around this.

[roshanshariff]

@Hugo-Heagren, thanks for clarifying your use cases. That makes sense! I propose a slightly different approach that is hopefully more explicit and less magical:

• Introduce a new defcustom called citar-local-bibliography (with the :local and :safe properties set) which is used by citar--bibliography-files as a source of bibliographies, in addition to citar-bibliography and the auto-detected local bibliographies.
• Define a new minor mode called citar-local-only-mode, which you can enable using file-local or dir-local variables with citar-local-only-mode: t. When enabled, citar--bibliography-files would ignore citar-bibliography.

My thought is that having a separate variable makes things easier to understand and document, and the mode can be enabled or disabled explicitly with a command. What do you think?

[Hugo-Heagren]

@roshanshariff ok thanks. So to be clear your proposed solution involves adding a new mode, and a new custom variable, and the new custom variable functions in the same way as the standard citar-bibliography except that its only used for local things whereas citar-bibliography is only used for global things? If one wants to ignore the global bibliography, one has to enable the mode.

I find this much more confusing than just setting one existing variable locally. Moreover I'm confused about what it adds: the two variables seem to function in exactly the same way, except that one is local-only and the other is global-only?Emacs has a robust (and very flexible) system for this sort of thing which (it seems to me) is designed specifcally to avoid such duplication. Why should we reinvent it within citar?

(to be fair, we may just be disagreeing about about how people 'should' use Emacs -- I'm of the opinion that generally anything should be locally safe unless there is a good reason for it not to be. If you really don't like my proposal, I'm happy to just set it up manually myself in my init file and leave this PR?)

[roshanshariff]

@Hugo-Heagren, I should've been more explicit about my reasons:

Citar internally treats local bibliographies differently from global ones. It tracks which buffers own each local bibliography, and evicts them from the cache when no buffers need them. Currently global bibliographies always remain in the cache, though that might change at some point. So if you make citar-bibliography buffer-local and put local bibliographies in it, Citar will treat them as if they were global and might, in the future, remove your actual global bibliographies from the cache. This would become even more problematic if/when we implement background re-parsing of bibliographies on update. (Citar used to do this using file watchers, and might do so again if we figure out how without freezing Emacs).

That's why I suggested having a separate variable which augments the local bibliography auto-detection mechanism.

Apart from this, there are a few other considerations:

• The approach with file-local variables is fine if you want to replace the global bibliographies, but not so good if you just want to add additional local bibliographies. You'd need to use an eval form, and it would be somewhat fragile. Using a separate local variable lets you do this easily.

• Wanting to see only local bibliography items is orthogonal to how you specify local bibliographies. For example, somebody might be happy using the auto-detection feature, but still want to temporarily restrict Citar commands to local items. With a separate mode, you could do that easily with a command instead of modifying any variables. We might even be able to have that take effect in an ongoing completion session.

I hope that explains my suggestions, which I think handle a broader set of use cases. I also don't think the complexity is excessive, since (apart from docstrings) we only really need

(defcustom citar-local-bibliography :type '(repeat file) :safe t :local t)
(define-minor-mode citar-local-only-mode)

along with some changes to citar--bibliography-files. Of course, in the meantime you can continue to use your approach.

[Hugo-Heagren]

@roshanshariff aha, I understand now -- than you for explaining. I agree -- you approach makes more sense, and I'll close this PR. Thank you again!