Preparing for 1.0; last call for command or function name changes

[bdarcus]

@apc raised a question about the wisdom of the bibtex-actions-open command name, and I explained the reasoning in a followup here: #120 (comment).

I'm kind of agnostic, so would probably leave as is unless there were strong arguments in favor of changing.

But now is the time to raise the question, as I'm planning to tag 1.0 soon, which is me arbitrarily drawing a line-in-the-sand on command and function name changes.

It doesn't mean we can't revisit later, but that I'd prefer not to.

To recap, we have the follow action verbs:

1. open
2. insert
3. add

... and then command names based on these, the potential confusing ones being:

• bibtex-actions-open
• bibtex-actions-open-entry

Do note that aside from the clarity of the commands, I was also shooting for conciseness, to accommodate M-x, and menu displays like which-key (though see [this comment]((defalias 'apc/bib-open #'bibtex-actions-open-entry))) when using embark-act.

Bottomline, this (with marginalia annotations from the docstrings) should be as elegant, clear and concise as possible:

So what do people think?

cc @mtreca @wenjie2wang

[apc]

As I mentioned to you, I found the name bibtex-actions-open confusing as a name for that function. Especially so now that in calling the function you get the initial string has:link\|has:pdf, so that by default you don't see the entire list of entries. If anything, i think if you had asked me what bibtex-actions-open does, knowing only that this is like helm-bibtex and ivy-bibtex (packages advertised as designed to "allow you to search and manage your BibTeX bibliography"), I would have said that it would open the BibTeX entry.

But here's a thought: could you have bibtex-actions-open be a defcustom, give it one of the bibtex-actions-open functions as its default, and allow folks to change it if they so desire? This would essentially give you something like the following functionality:

• A function that is your primary entry point to your list of entries,
• that will perform an action of your choosing (by default) with the selected entries,
• but which (much like the other functions) always make it easy for you to use embark say to call other actions.

You could even allow for customization of the 'initial' string for that function.

You could then have the analog of bibtex-completion-open-any called bibtex-actions-open-any, and reserve bibtex-actions-open to be this alias you can assign to the function you are most likely to use (if the main thing you do with bibtex-actions is navigate to files in your bibliography library, then you'd assign it to bibtex-actions-open-pdf; if instead what you do is use it to manage bookmarks to URLs of some kind, you would assign it to bibtex-actions-open-link; etc.).

The model here would be something like what org-ref does with org-ref-insert-link-function---see here.

EDIT: here's a quick prototype of sorts (not sure if I'm quoting everything I should be quoting here, but the general shape should do what I have in mind):

(defcustom bibtex-actions-open
  'bibtex-actions-open-any
  :type 'function
  :options '(bibtex-actions-open-any
	     bibtex-actions-open-link
	     bibtex-actions-open-pdf
	     bibtex-actions-open-entry
             bibtex-actions-open-note
	     )
  :group 'bibtex-actions)

[apc]

Oh, and you may want to point people to this discussion to address the issue with which-key making it hard to see the full names.

[bdarcus]

... could you have bibtex-actions-open be a defcustom, give it one of the bibtex-actions-open functions as its default, and allow folks to change it if they so desire?

I had thought about that for possibility of a top-level bibtex-actions command.

But that feels like config overkill when you consider one can just use an alias.

(defalias 'apc/bib-open #'bibtex-actions-open-entry)
(defalias 'apc/bib-open-any #'bibtex-actions-open)

Another possibility is to make the following name changes here:

1. bibtex-actions-open -> bibtex-actions-open-source (or -any or -doc)
2. bibtex-actions-open-entry -> bibtex-actions-open (or keep as is)

[apc]

... could you have bibtex-actions-open be a defcustom, give it one of the bibtex-actions-open functions as its default, and allow folks to change it if they so desire?

I had thought about that for possibility of a top-level bibtex-actions command.

But that feels like config overkill when you consider one can just use an alias.

(defalias 'apc/bib-open #'bibtex-actions-open-entry)
(defalias 'apc/bib-open-any #'bibtex-actions-open)

I see the point, yes. Though for users who rely on the customization interface the defcustom approach with the range of options is maybe more user-friendly? It's also a similar setup as this package's cousins/siblings/parents/something, helm- and ivy-bibtex (I just realized that!). But yes, I take your point.

Another possibility is to make the following name changes here:

1. bibtex-actions-open -> bibtex-actions-open-source (or -any or -doc)
2. bibtex-actions-open-entry -> bibtex-actions-open (or keep as is)

Interesting. If you don't go for the top-level command, I would vote for the 'default' sounding function name to go with bibtex-actions-open-entry, if only because that would default to giving you the entire list of entries ATM.

[bdarcus]

What do you mean this?

I would vote for the 'default' sounding function name ...

I do think we've settled on two separate questions:

1. whether there's need to change any existing command (or while we're at it, function) names
2. whether we could use a configurable top-level commands: bibtex-actions

Edit: I will say I have felt less need for 2, given all the action functions here are full commands.

Copying @emiller88 just in case has any thoughts.

[apc]

What do you mean this?

I would vote for the 'default' sounding function name ...

I mean: I would reserve bibtex-actions-open as a name for either a configurable top-level command or for what's now called bibtex-actions-open-entry.

EDIT: I say 'default'-sounding because "bibtex-actions-open" sounds like the default, or main, or primary 'open' action. Does that make sense?

I do think we've settled on two separate questions:

1. whether there's need to change any existing command (or while we're at it, function) names
2. whether we could use a configurable top-level commands: bibtex-actions

Copying @emiller88 just in case has any thoughts.

[bdarcus]

@publicimageltd - can you weigh in on this issue?

[bdarcus]

I say 'default'-sounding because "bibtex-actions-open" sounds like the default, or main, or primary 'open' action. Does that make sense?

Yes.

The confusion comes up different categories of thing these commands open: bibtex entry, notes, and then a mix of different source formats.

[publicimageltd]

I think ...open-any makes more sense. It leaves ...open for the user to define and coheres with bibtex-completion-open-any. Since the latter is the real workhorse, it should be signalled that bibtex-actions is "just" a wrapper.

Why not predefine an alias which maps ...open to ....open-any? This keeps configurations intact and allows configurations for the interested. Such a default kind of says: I offer you to find what I think you like to open, but if you don't like that setting, feel free for your default thing to to open.

[bdarcus]

Emacs does have a mechanism (a macro) that allows you to mark a function as deprecated, and what the new name is. Internally, that I believe creates an alias, but you can, for example, specify when it will be removed.

[bdarcus]

PS - my problem with "any" (and I think Titus agrees, BTW) is it's almost as vague as nothing. "Any" what? Why I was thinking about "open-src" or some such. Edit: I keep with bibtex completion names where it makes sense, and diverge where not. Those function names weren't designed to be interactive, and who knows what happens to this dependency in the future.

[apc]

PS - my problem with "any" (and I think Titus agrees, BTW) is it's almost as vague as nothing. "Any" what? Why I was thinking about "open-src" or some such. Edit: I keep with bibtex completion names where it makes sense, and diverge where not. Those function names weren't designed to be interactive, and who knows what happens to this dependency in the future.

FWIW: I like open-src. And agree that most users of bibtex-completion, who use ivy-bibtex or helm-bibtex, probably don’t interact with bibtex-completion-open-any. So the change of name from -open-any to something else doesn’t seem like an issue to me.

[publicimageltd]

I understand. -open-source (the long, explicit form) then seems to me the best choice, since it offers a kind of metatype (a source is a PDF or a URL or a DOI).

[bdarcus]

Emacs does have a mechanism (a macro) that allows you to mark a function as
deprecated, and what the new name is.

Ah, here it is; how I would do this technically if making the change:

(define-obsolete-function-alias
  'bibtex-actions-open
  'bibtex-actions-open-source
  "1.0")

I understand. -open-source (the long, explicit form) then seems to me the best choice, since it offers a kind of metatype (a source is a PDF or a URL or a DOI).

I do want to point out a problem with this approach, which is why I went originally with just "open". To be totally consistent would suggest also renaming those commands; like to bibtex-actions-open-source-pdf. But I'm not fond of that because it's getting too long.

[bdarcus]

Per discussion on #130, another possible list of command names:

• bibtex-actions-view-source
• bibtex-actions-view-source-pdf
• bibtex-actions-view-source-link
• bibtex-actions-open-notes
• bibtex-actions-open-entry

In this approach, view is a read-only verb, and open read-write.

But I'm not sure that's a necessary distinction. If not, this would be the more explicit and consistent approach:

• bibtex-actions-open-source
• bibtex-actions-open-source-pdf
• bibtex-actions-open-source-link
• bibtex-actions-open-notes
• bibtex-actions-open-entry

... but some of these names become long enough they may not play well in which-key menus.

🤷

[apc]

Crazy idea:

• bibtex-actions-with-pdf (or bibtex-actions-on-pdf?)
• bibtex-actions-with-link
• bibtex-actions-with-notes
• bibtex-actions-with-entry

Each one is a command for acting on a key's pdf, link, etc. What actions are performed for each item depends on what it is: if it's 'notes', it makes sense that the actions are 'add' or 'edit/view'; it it's 'entry', it makes sense that it's just 'open', etc.

Just putting this out there, feel free to ignore (of course)!

[bdarcus]

That's an interesting idea I hadn't thought of. Worth considering, seems to me. Edit: doesn't address the issue that inspired this, however, and the command names aren't shorter.

[publicimageltd]

Crazy idea:

I like it! Maybe the actual actions should be displayed in the prompt, like "Open Bibtex Entries" or "Add or view notes".

This solution also works nicely with the embark basic idea. I can open a list of pdf entries and then decide to call "action-on-notes" on this item. Also one could imagine calling one of these actions in a buffer on a certain item, e.g. on a key or on a citation, and it would do what one expects without prompting (or with preselecting the input at point).

[apc]

I think the command names just won't get significantly shorter, given the name space conventions and the fact that 'bibtex-actions' is, well, a long string. But the issue of the 'bibtex-actions-open' command could be addressed by just getting rid of it(!), or replacing it with bibtex-actions-default-action or some such (similar to what ivy-bibtex has), which could be configurable by the user. Perhaps with customization options that allow the user to determine which action to use and whether to have filters applied?

[apc]

PS: also, bibtex-actions-on-pdf is probably as short as it'll get! ;-)

[bdarcus]

I've opened #131 to settle this.

As I say there, I'm not convinced after this (very helpful though) discussion it's worth changing.

But at minimum, I thought, I'd start with clarifying the docstrings, which I'll have to do either way.